1. IronWord
  2. 操作指南
  3. 新增圖片

如何在 C# 中向 DOCX 添加圖像

艾哈邁德·索海爾
艾哈邁德·索海爾
更新:
This article was translated from English: Does it need improvement?
Translated
View the article in English

IronWord 提供了ImageContent類，可以將圖像（.jpg、.png、.bmp、.tiff、.gif）插入到 DOCX 檔案中，並可自訂寬度、高度和文字換行等屬性。 使用 IronWord 為 Word 文件新增圖像，實現文件自動化和報告產生。

快速入門：在 C# 中向 DOCX 添加圖像

  1. 透過 NuGet 套件管理器安裝 IronWord
  2. 建立一個新的WordDocument實例
  3. 使用ImageContent類別載入映像
  4. 使用AddImage()將影像加入文件中
  5. 將文件另存為 DOCX 格式

Nuget Icon立即開始使用 NuGet 建立 PDF 檔案：

  1. 使用 NuGet 套件管理器安裝 IronWord

    PM > Install-Package IronWord

  2. 複製並運行這段程式碼。

    using IronWord;
using IronWord.Models;

// Create new document
WordDocument doc = new WordDocument();

// Add image
ImageContent image = new ImageContent("photo.jpg");
doc.AddImage(image);

// Save document
doc.SaveAs("document-with-image.docx");

  3. 部署到您的生產環境進行測試

    立即開始在您的專案中使用 IronWord，免費試用！
    arrow pointer

試試IronWord

如何在 DOCX 檔案中新增圖像

  1. 下載最新穩定版 IronWord
  2. 初始化一個新的 Word 文檔
  3. 定義影像物件（.bmp、.jpg、.png 或其他支援的格式）
  4. 將圖片加入文件中
  5. 儲存並匯出文檔文件

如何在 DOCX 檔案中新增圖片？

使用檔案路徑引用圖像。 首先，使用字串形式的檔案路徑實例化ImageContent類別。 在整個檔案中使用image變數來修改寬度和高度等屬性。 使用AddImage()函數將影像新增至 .docx 檔案。 匯出文件並儲存到本機。

下面的範例在文件中新增了一張圖片，而沒有新增任何父節點。 支援的檔案格式包括 .jpg、.png、.bmp、.tiff 和 .gif。 這種靈活性使您可以處理任何常見的圖像格式。

[{t:(將影像作為子元素插入段落中，以改善文件層次結構。 該段落定義了文字換行和其他文字格式屬性。 這種方法可以更好地控制圖像位置，並允許圖像與周圍的文字流暢銜接。

:path=/static-assets/word/content-code-examples/how-to/add-image-insert-image.cs
using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

// instantiating image file
IronWord.Models.ImageContent image = new IronWord.Models.ImageContent("sample-image.jpg");

// modifying image properties
image.Width = 200;
image.Height = 200;

// AddImage function saving the image
doc.AddImage(image);

// Save and export the file
doc.SaveAs("inserted-image.docx");
$vbLabelText   $csharpLabel
Word 文件中插入了一張夜幕下的城市天際線圖片，並顯示了

支援哪些圖像格式？

支援的檔案格式：.jpg、.png、.bmp、.tiff 和 .gif。 每種格式插入後都能保持其品質。 JPEG格式最適合照片。 PNG格式支援透明度，適用於標誌和圖形。 BMP提供未壓縮的畫質。 TIFF格式適用於高品質印刷文件。 GIF 允許簡單的動畫（靜態文件中僅顯示第一幀）。

圖片在文件中的位置在哪裡？

預設情況下，影像會新增到目前遊標位置，沒有任何父節點。 為了精確定位，請將圖片作為子元素插入段落中。這樣可以更好地控製文字流，並將圖片融入文件結構中。

為什麼要使用 ImageContent 類別？

ImageContent 類別以結構化的方式管理影像屬性。 插入前修改尺寸、位置和格式。 這種方法可以確保文件產生過程的一致性，並在整個應用程式中應用標準格式規則。 該類別封裝了所有與圖像相關的屬性，使程式碼更易於維護並減少格式錯誤。

如何透過串流媒體添加圖片？

使用前面的方法可以輕鬆新增本機或靜態 URL 圖片。 但是，應用程式通常會處理來自資料庫、Web 服務或動態生成內容的圖像。 使用Stream方法為需要驗證的安全 API 新增映像。

下面的範例展示了 HTTP 用戶端傳送授權令牌以檢索經過驗證的映像流。 資料流在匯出前直接整合到文件中。 這種方法消除了臨時文件存儲，提高了敏感影像資料的安全性。

:path=/static-assets/word/content-code-examples/how-to/add-image-insert-image-via-http-stream.cs
using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

using (HttpClient client = new HttpClient())
{
    // Add authentication headers
    client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY_HERE");
    client.DefaultRequestHeaders.Add("User-Agent", "MyApp/1.0");

    // Get image from authenticated endpoint
    Stream authenticatedStream = client.GetStreamAsync("https://api.example.com/secure/image.png");
    doc.AddImage(authenticatedStream);
}

// Export docx
doc.SaveAs("added-image-via-http-stream.docx");
$vbLabelText   $csharpLabel

何時應該使用 Stream 方法？

在以下情況下使用Stream方法： 圖片位於需要身份驗證的安全 API 之後。

  • 從記憶體動態處理影像
  • 處理以二進位資料形式儲存在資料庫中的影像

這種方法在企業應用中效果很好，影像可以儲存在文件管理系統、雲端儲存中，或由影像處理服務產生。

串流式載入有哪些好處？

串流載入可將來自已認證端點的映像整合到系統中，而無需儲存臨時檔案。 這有助於提高安全性和性能。 福利包括： 減少磁碟 I/O 操作

  • 磁碟上不快取敏感影像
  • 即時影像處理工作流程
  • 更好地管理大型影像的內存
  • 靈活的影像來源選項

如何修改圖像屬性？

IronWord 提供了全面的方式來自訂影像屬性。 在將圖像新增至文件之前或之後調整這些屬性。

設定 描述 例子
寬度 影像的水平尺寸（以像素為單位） image.寬度 = 500;
高度 影像的垂直尺寸（以像素為單位） image.高度 = 300;
環繞文字 圖片周圍的文字環繞行為 image.環繞文字 = 環繞文字.Square;
距左側距離 從左邊緣到間距的測量值（以像素為單位） image.距左側距離 = 10;
距右側距離 從右邊緣測量間距（以像素為單位） image.距右側距離 = 10;
距頂部距離 從頂部邊緣測量間距（以像素為單位） image.距頂部距離 = 15;
距底部的距離 從底部邊緣測量間距（以像素為單位） image.距底部的距離 = 15;
位置 空間位置資訊（X 和 Y 座標） image.位置 = new Element位置(50, 100);
規模 X軸和Y軸的比例尺寸因子 image.規模 = new PointF(1.5f, 1.5f);
翻譯 用於重新定位的位移座標 image.翻譯 = new PointF(20, 30);

如何自訂寬度和高度？

透過改變寬高比來實現自訂寬度和高度。 控製影像在文件中的顯示方式，無論是保持比例還是適應特定的佈局限制。

:path=/static-assets/word/content-code-examples/how-to/add-image-custom-size.cs
using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

// instantiating image file
IronWord.Models.ImageContent image = new IronWord.Models.ImageContent("sample-image.tiff");

// modifying the aspect ratio by introducing custom width
image.Width = 800;
image.Height = 200;

// AddImage function saving the image
doc.AddImage(image);

// Save and export the file
doc.SaveAs("custom-size-image.docx");
$vbLabelText   $csharpLabel
Word 文件顯示了筆記型電腦圖像，並疊加了

寬高比會發生什麼變化？

自訂寬度和高度值會覆蓋原始寬高比。 拉伸或壓縮影像以適應佈局要求，例如標題、側邊欄或固定大小的容器。 過度變形會顯得不夠專業。 為了在調整尺寸時保持縱橫比，請根據目標尺寸計算比例尺寸。

我應該先設定哪些屬性？

請依以下順序設定屬性：

  1. 尺寸（寬/高）－影像佈局的基礎
  2. 定位（DistanceFrom 屬性）- 控制間距和邊距
  3. 高級屬性（縮放/平移）- 微調

這種方法確保每個屬性都能在邏輯上建立在前一個屬性的基礎上。 有些屬性會互相影響——例如，文字換行會影響距離屬性的工作方式。

常見問題解答

如何使用 C# 在 DOCX 檔案中加入圖片？

透過 IronWord，您可以使用圖片檔案路徑建立 ImageContent 實體，然後再使用 AddImage() 方法，將圖片新增至 DOCX 檔案。IronWord 支援 JPG、PNG、BMP、TIFF 和 GIF 等常見格式，讓您可以輕鬆地以程式化的方式在 Word 文件中插入圖片。

在 Word 文件中加入圖片時，支援哪些圖片格式？

IronWord 支援所有主要的圖像格式，包括 .jpg、.png、.bmp、.tiff 及 .gif 檔案。每種格式在插入時都能保持其品質 - JPEG 適用於照片、PNG 適用於具有透明度的圖形、BMP 適用於未壓縮的品質、TIFF 適用於高品質的列印文件，而 GIF 則適用於簡單的動畫 (僅顯示第一幀)。

我可以控制 DOCX 檔案中圖片的大小和位置嗎？

是的，IronWord 的 ImageContent 類別可讓您自訂寬度、高度和文字包覆等圖片屬性。您可以在插入之前修改尺寸和定位，讓您完全控制圖片在 Word 文件中的顯示方式。

如何在段落中插入圖片以改善文件結構？

IronWord 允許您在段落中以子元素的方式插入圖片，提供更好的文件層級結構以及對文字包覆的控制。相較於在沒有父節點的情況下新增圖片，此方法可將圖片與周遭的文字流程整合，並提供您更精確的定位選項。

以程式化方式在 Word 文件中加入圖片的最快方法是什麼？

IronWord 最快速的方法是建立一個 WordDocument 實例，使用 new ImageContent('photo.jpg「) 載入您的圖片，呼叫 doc.AddImage(image)，然後以 doc.SaveAs(」document-with-image.docx') 儲存。這個簡單的四步程序處理了整個圖像插入工作流程。

艾哈邁德·索海爾
艾哈邁德·索海爾
  現在就和工程團隊聊天吧
全端開發工程師

Ahmad 是一位全端開發人員，精通 C#、Python 和 Web 技術。他對建立可擴展的軟體解決方案有著濃厚的興趣，並樂於探索如何在實際應用中實現設計與功能的完美結合。

在加入 Iron Software 團隊之前，Ahmad 曾從事自動化專案和 API 整合工作，專注於提高效能和開發者體驗。

在空閒時間，他喜歡嘗試 UI/UX 設計理念，為開源工具做出貢獻，偶爾還會涉足技術寫作和文件編寫，使複雜的主題更容易理解。

準備好開始了嗎？
Nuget 下載 29,594 | 版本： 2025.12 剛剛發布