使用 Core API 建立 PDF

由 Bit Miracle 翻譯。原文作者：Sergey Bobrovsky

更新於 2026年6月29日

核心 Docotic.Pdf API 提供對 PDF 建立的完整控制。它可讓您在 PDF 頁面、XObject 與平鋪圖樣提供的畫布上繪製文字、影像與向量圖形。

您可以控制每個座標與每個繪圖操作，這使您對 PDF 頁面版面配置擁有最大的控制力。對於圖形密集或自訂版面的文件，只要精確度很重要，這種控制層級就不可或缺。

透過 Core API，您也可以為已建立的 PDF 新增註解、表單欄位、圖層、書籤等。這個 API 是 Docotic.Pdf 在 .NET 中提供的最靈活且最強大的 PDF 建立方式。

如果您想要更廣泛地了解 Docotic.Pdf 中可用的所有建立 PDF 方法（包含 Core API 之外的方法），請參閱 建立 PDF 的所有方法 一文。

開始之前

在開始使用 Core API 之前，請先安裝 Docotic.Pdf 並申請授權金鑰。

安裝 Docotic.Pdf

若要在 C# 或 VB.NET 中建立 PDF 文件，請先從 NuGet 安裝此程式庫。

Install-Package BitMiracle.Docotic.Pdf

如果您偏好手動安裝，請下載包含程式庫二進位檔的 ZIP 壓縮檔，解壓縮後，將專案參考加入 BitMiracle.Docotic.Pdf.dll。

取得授權金鑰

使用此程式庫需要授權金鑰。若要試用，請填寫 Docotic.Pdf 下載頁面 上的表單，以申請免費的限時授權金鑰。

基本 PDF 建立範例

本節提供使用 Core API 建立 PDF 文件的基本範例，先以 C#，再以 VB.NET 示範。

如何在 C# 中建立 PDF

既然您已安裝 Docotic.Pdf 並取得授權金鑰，就很容易使用 Core API 建立 PDF。

BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

using var pdf = new PdfDocument();
pdf.Save("empty.pdf");

這段程式碼示範如何建立空白 PDF 檔案。第一行會加入授權金鑰。沒有授權時，您會在建立 PdfDocument 的那一行收到例外。最後一行會將文件儲存為 PDF 檔案。

所建立檔案的內部結構取決於儲存選項。在此範例中，程式碼使用會以預設選項儲存的 Save 方法多載。若要了解這些預設值的作用，以及何時可能需要調整，請參閱 儲存選項 一節。

為了遵循程式設計傳統，第二個範例示範使用 Core API 建立的 Hello, world!。

using var pdf = new PdfDocument();

var page = pdf.Pages[0];
page.Canvas.DrawString(50, 50, "Hello, world!");

pdf.Save("hello.pdf");

這段程式碼會將這句經典字串放在文件第一頁的畫布上，從明確指定的位置開始。此行使用預設字型與預設字型大小。請繼續閱讀，以取得使用 PDF 畫布的更多資訊。

使用 VB.NET 建立 PDF

用 VB.NET 建立 PDF 的程式碼與前一節的程式碼非常相似。

Using pdf As New PdfDocument()
    Dim page = pdf.Pages(0)
    page.Canvas.DrawString(50, 50, "Hello, world!")

    pdf.Save("hello.pdf")
End Using

前一節包含 C# 範例，已說明這段程式碼的作用與運作方式。

使用 PDF 畫布

若要變更 PDF 文件中的畫布，請使用 Canvas API。它是 Core API 的子集。

Canvas API 採用絕對定位模型。您選擇座標，畫布就會精確地在您指定的位置繪製。座標系會將原點放在頁面的左上角。座標會沿著 X 軸向右增加，沿著 Y 軸向下增加。

(0,0) ──► X
  │
  │
  ▼
  Y

繪製文字

在 PdfCanvas 類別中，Docotic.Pdf 提供兩個主要方法來呈現文字：DrawString 與 DrawText。這兩個方法都會使用目前的畫布字型，因此建議在繪製任何文字之前先設定所需字型。

使用 DrawString

DrawString 一律繪製單行文字。除非您使用帶有明確座標的多載，否則此方法會從畫布目前的文字位置開始繪製。某些多載可讓您指定其他選項，以控制文字行的繪製方式。

您已在 Hello, world! 範例中看過 DrawString 的簡單用法。以下是另一個使用 字串繪製選項 為文字加上底線的範例。

using var pdf = new PdfDocument();

var canvas = pdf.Pages[0].Canvas;
canvas.DrawString(50, 50, "This text is underlined", new PdfStringDrawingOptions
{
    Underline = true,
});

pdf.Save("underlined-text.pdf");

使用 DrawText

DrawText 可在指定矩形內呈現多行文字。此方法會處理換行，並裁切無法放入允許空間的文字。文字繪製選項 可定義文字的水平與垂直對齊方式，以及文字定位與呈現的其他層面。

以下是使用 C# 在 PDF 中繪製文字的方法：

using var pdf = new PdfDocument();

const string LongString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit";
var multiLineOptions = new PdfTextDrawingOptions(new PdfRectangle(70, 70, 40, 150))
{
    HorizontalAlignment = PdfTextAlign.Left,
    VerticalAlignment = PdfVerticalAlign.Top
};

var canvas = pdf.Pages[0].Canvas;
canvas.DrawText(LongString, multiLineOptions);

pdf.Save("drawtext.pdf");

若要細調文字外觀，您可以調整下列畫布屬性：

• 字元間距
• 詞間距
• 文字縮放
• 文字上升量（基線位移）
• 呈現模式（填色、描邊、填色與描邊等）

如需文字相關方法與屬性的實作範例，請參閱 文字範例組。

新增與使用字型

除非您只需要預設的 Helvetica 字型，否則應將所需字型加入 PDF，以確保文字完全依照預期呈現。

Docotic.Pdf 可加入來自下列來源的 Type1、TrueType、Compact Font Format (CFF) 與 OpenType 字型：

• 系統已安裝字型集合
• 外部檔案與串流

此外，您可以使用任何 PDF 檢視器中都可用的 14 種內建 Type1 字型。

若要在 PDF 中使用字型，請使用對應 PdfDocument 物件的 CreateFont 或 CreateFontFromFile 方法建立 PdfFont 物件。然後在繪製文字之前將字型指派給畫布。同時也建議設定字型大小。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var font = pdf.CreateFont("NSimSun");
canvas.Font = font;
canvas.FontSize = 14;
canvas.DrawString(10, 50, "Olá. 你好. Hello, Unicode!");

font.RemoveUnusedGlyphs();

pdf.Save("unicode-text.pdf");

字型必須包含您嘗試繪製之文字中所有字元的字形。否則，您會收到 CannotShowTextException。請使用 PdfFont.ContainsGlyphsForText 來驗證字型是否包含所有必要字形。

Unicode 支援取決於字型類型。Type 1 字型只支援拉丁字元集與編碼，但有一個例外。內建的 Symbol 與 ZapfDingbats 字型提供數學、希臘與裝飾性符號。

TrueType、CFF 與 OpenType 字型通常支援 Unicode，但它們可能不包含所有 Unicode 字元的字形。

Docotic.Pdf 會盡量嵌入最少的字型位元組，以維持輸出 PDF 較小。不過，當文件使用具有大量字形的字型時，產生的檔案仍可能相對較大。請使用 PdfFont.RemoveUnusedGlyphs 來將嵌入字型所加入的位元組數降到最低。

計算文字尺寸

由於 Canvas API 使用絕對定位，在繪製文字之前，通常需要知道一段文字會佔用多少空間。當您要分段輸出文字時，這尤其重要，例如切分長字串、精確對齊文字，或避免與其他內容重疊。PdfCanvas 類別提供多個方法，可協助您使用目前選取的字型與字型大小來測量文字。

使用 PdfCanvas.MeasureText 取得字串在畫布上顯示時的寬度與高度。典型使用情境包括：

• 判斷文字是否能放入指定區域
• 手動計算換行
• 相對於彼此定位文字區塊

當您要將文字置中或靠右對齊，且只需要水平範圍時，請使用 PdfCanvas.GetTextWidth。若要知道目前字型下一行文字的高度，請使用 PdfCanvas.GetTextHeight。

繪製影像

若要在 PDF 畫布上繪製影像，請先建立 PdfImage 物件，然後使用 PdfCanvas.DrawImage 方法繪製該物件。

以下是使用 C# 在 PDF 中加入影像的方法：

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var image = pdf.CreateImage("image.png");
canvas.DrawImage(image, 10, 50);

pdf.Save("image.pdf");

這段程式碼會使用對應 PdfDocument 物件的 CreateImage 方法建立影像物件，並將影像繪製在第一頁的畫布上。

請閱讀 從影像建立 PDF 以了解支援的影像格式與更進階的影像轉 PDF 技術。

使用向量圖形

Docotic.Pdf 可讓您直接在 PDF 畫布上繪製直線、貝茲曲線與常見幾何圖形，方法是使用 PdfCanvas 類別的方法。使用以 Draw 開頭的方法（例如 DrawLineTo、DrawCircle、DrawRectangle）即可在畫布上放置可見標記。

線條與曲線會使用 目前的筆 來呈現，此筆透過 PdfCanvas.Pen 定義，會指定描邊色彩、寬度與其他繪圖屬性。視繪圖模式而定，圖形可以只有描邊、只有填色，或先描邊再填色。目前的刷子 則透過 PdfCanvas.Brush 存取，用於填滿圖形內部。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.DrawCircle(new PdfPoint(60, 100), 40);
canvas.DrawRectangle(
    new PdfRectangle(300, 60, 110, 70),
    PdfDrawMode.Fill);

canvas.CurrentPosition = new PdfPoint(150, 90);
canvas.DrawCurveTo(new PdfPoint(180, 60), new PdfPoint(230, 120), new PdfPoint(250, 90));

pdf.Save("curve-and-shapes.pdf");

每個 PDF 畫布都會維護圖形狀態，包含筆、刷子、字型與目前位置。請使用 SaveState 來保留目前狀態，並使用 RestoreState 回復到先前狀態。除了回復暫時性的變形與類似變更之外，還原狀態也是在套用裁剪之後將其移除的唯一方法。

圖形路徑可讓您以線條、曲線與較簡單的圖形建立複雜形狀，而不必立即繪製。使用 AppendLineTo 或 AppendRectangle 等 Append 方法可將區段加入目前路徑。路徑不會產生可見輸出，直到您明確對其填色或描邊。

您可以將任何已建立的圖形路徑用作裁剪區域，以限制後續的繪圖操作。裁剪會持續有效，直到圖形狀態被還原。

可執行的向量圖形實作範例，請參閱範例存放庫中的 圖形章節。

設定色彩與透明度

您可以透過 PDF 畫布的筆與刷子變更描邊色彩與填色彩色。若要這麼做，請使用 PdfPen.Color 與 PdfBrush.Color。

支援的裝置相依色彩空間包括 Gray、RGB 與 CMYK，分別由 PdfGrayColor、PdfRgbColor 與 PdfCmykColor 表示。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.Pen.Color = new PdfRgbColor(30, 60, 160);
canvas.Pen.Width = 3;

canvas.Brush.Color = new PdfCmykColor(0, 20, 5, 0);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

pdf.Save("fill-and-stroke-colors.pdf");

Docotic.Pdf 支援基於 CIE 的裝置無關色彩空間，包括 L*a*b* 色彩與基於 ICC 的校準色彩。Core API 也支援專色與分色彩空間，適用於需要自訂油墨或特定色版輸出的工作流程。

下列範例程式碼示範如何建立 Lab 色彩、以描述檔為基礎的色彩與專色。若要執行此範例，請先下載其使用的 ICC 描述檔。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var labColorSpace = new PdfLabColorSpace(pdf, [0.5, 1, 0.5]);
canvas.Pen.Color = new PdfLabColor(labColorSpace, 50, -50, 50);
canvas.Pen.Width = 3;

var rgbProfile = pdf.CreateColorProfile("AdobeCompat-v2.icc");
canvas.Brush.Color = new PdfRgbColor(rgbProfile, 210, 105, 30);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

var tintTransform = new PdfExponentialFunction(
    pdf, 1, [0d, 0, 0, 0], [0, 0.8, 0.73, 0.25], [0d, 1]);
var separationColorSpace = new PdfSeparationColorSpace(
    pdf, "BLOODRED", new PdfCmykColorSpace(), tintTransform);
canvas.Pen.Color = new PdfSpotColor(1.0, separationColorSpace);

canvas.DrawCircle(new PdfPoint(100, 70), 60);

pdf.Save("using-special-colors.pdf");

您也可以使用平鋪圖樣對圖形進行描邊與填色。圖樣由繪製在其專屬畫布上的圖樣格定義。圖樣有兩種類型：

• 有色圖樣。其格子定義自身的色彩。
• 無色圖樣。其格子會在使用時由筆/刷色彩著色。

若要使用圖樣，請使用對應 PdfDocument 物件的 CreateColoredPattern 或 CreateUncoloredPattern 來建立圖樣，然後透過 PdfPen.Pattern 與／或 PdfBrush.Pattern 套用。請查看範例存放庫中 建立與使用圖樣 的範例程式碼。

半透明色彩可讓您以不同不透明度繪製形狀、文字與影像。請使用 PdfPen.Opacity 與 PdfBrush.Opacity 產生半透明色彩。

此外，混合模式 會控制透明內容與其下方內容的互動方式。若要變更畫布的混合模式，請使用 PdfCanvas.BlendMode。

新增與自訂頁面

Docotic.Pdf 提供 PdfDocument.Pages 集合，您可用它管理文件中的所有頁面。在 PdfDocument 類別中，有兩個主要方法可用來新增頁面：AddPage 與 InsertPage。

使用 AddPage() 可在文件末尾附加新頁面。若要在任意位置插入頁面，請使用 InsertPage(index)。這兩個方法都會回傳新建立的 PdfPage 實例。

每個新頁面的預設大小為 595 x 842 使用者空間單位。這相當於 A4 紙張大小。在大多數情況下，PDF 中的使用者空間單位是 1/72 英吋。換句話說，當頁面解析度為每英吋 72 像素時，一個使用者空間單位就等於一個像素。

您可以隨時透過將頁面的寬度與／或高度設為特定的使用者空間單位數值來變更頁面大小。

using var pdf = new PdfDocument();
var page = pdf.Pages[0];

page.Width = 600;
page.Height = 800;

另一個做法是使用其中一個預先定義的大小：

page.Size = PdfPaperSize.Ledger;

也可以將頁面方向從直向改為橫向，並以順時針 90°、180° 或 270° 旋轉頁面。

page.Orientation = PdfPaperOrientation.Landscape;
page.Rotation = PdfRotation.Rotate180;

除了設定頁面寬度、高度或預先定義的大小之外，也可以在 裁剪或重新調整現有內容 的同時調整頁面大小。

使用 XObjects 重用內容

PDF XObject 是一個容器，可包含向量圖形、影像與文字。每個 XObject 都有自己的畫布，因此您可以建立像一般 PDF 頁面一樣複雜的 XObject。

XObject 類似向量影像。您可以在多個頁面上重複使用相同物件，而不必重新建立內容或增加文件大小。您可以縮放並旋轉這類物件，而不會產生視覺失真。由於這些特性，XObject 很適合用於重複元素，例如標誌、插圖、背景、浮水印與其他重複出現的圖形。

建立與使用 XObjects

若要建立 XObject，請使用 PdfDocument.CreateXObject 方法。必要時，請變更物件的寬度與高度。然後以與一般頁面畫布相同的方式，將文字、影像與圖形填入該畫布。

在您的 C# 或 VB.NET 程式碼中使用 PdfCanvas.DrawXObject 方法，將 XObject 加入其他畫布。請注意，您可以在頁面與其他 XObject 提供的畫布上繪製 XObject。

以下是建立含有插圖的 XObject，並將該插圖繪製到兩個頁面的 C# 程式碼。

using var pdf = new PdfDocument();

var xobj = pdf.CreateXObject();

var options = new PdfTextDrawingOptions(new PdfRectangle(0, 0, 100, 50))
{
    HorizontalAlignment = PdfTextAlign.Center,
    VerticalAlignment = PdfVerticalAlign.Center,
};
xobj.Canvas.FontSize = 16;
xobj.Canvas.DrawText("Company Logo", options);
xobj.Canvas.DrawRectangle(options.Bounds);

var page1 = pdf.Pages[0];
page1.Canvas.DrawXObject(xobj, 100, 100);

var page2 = pdf.AddPage();
page2.Canvas.DrawXObject(xobj, 200, 200);

pdf.Save("using-xobjects.pdf");

使用 XObjects 轉換頁面

XObject 也能支援超出單純重用圖形的情境。一個常見範例是將兩個現有 PDF 頁面合併為單一、更大的頁面。透過將每個來源頁面轉換為 XObject，您可以將它們並排繪製在新的畫布上，實際建立 合併的雙頁跨頁。這種做法可讓您完全控制定位、間距與縮放，因此很容易建立比較版面、書本跨頁或多頁預覽。

當您需要 重新調整 PDF 頁面大小 時，也可以套用相同技術。您不必重新繪製或重建內容，而是可以從原始頁面建立 XObject，然後按新大小縮放繪製。如此可用最少的工作量縮小過大的頁面、放大較小的頁面，或標準化混合尺寸的文件。

Core API 的範圍與限制

Core API 提供精確的低階 PDF 建立控制，但不提供任何自動版面配置功能。它沒有內建邊界、頁首、頁尾或分頁邏輯，所有內容都必須手動定位。文字測量與跨頁切分的責任完全由您的程式碼負責，因此這是建立 PDF 最手動的方法。

包含表格、段落與分頁支援的自動版面配置，可透過 較高階的 Layout API 使用。

結論

核心 Docotic.Pdf API 提供對 PDF 建立的完整控制。它可讓您在 PDF 頁面、XObject 與平鋪圖樣提供的畫布上繪製文字、影像與向量圖形。

此 API 專為需要精確低階控制的情境而設計：您可明確定位每個元素，自行管理文字測量與頁面切分，並直接操作圖形狀態、色彩與透明度。

整體而言，當精確度與控制是優先考量時，Core API 是建立 PDF 最靈活的工具。