使用核心 API 建立 PDF

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

更新於 2026年5月5日

Docotic.Pdf 的核心 API 提供對 PDF 建立的完全控制。它允許您在 PDF 頁面、XObject 和圖塊圖案提供的畫布上繪製文字、圖像和向量圖形。

您可以控制每個座標和每個繪圖操作，從而最大限度地控制 PDF 頁面的佈局。對於圖形密集型或需要精確佈局的文檔，這種程度的控制至關重要。

借助核心 API，您還可以為建立的 PDF 新增註釋、表單欄位、圖層、書籤等。該 API 是 Docotic.Pdf 提供的在 .NET 中建立 PDF 的最靈活、最強大的方式。

如果您想更全面地了解 Docotic.Pdf 中所有可用的方法，包括核心 API 以外的方法，請參閱概述 建立 PDF 的每種方法 的文章。

開始之前

在開始使用核心 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 並獲得了許可證金鑰，使用核心 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

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

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 字型：

• 系統自備字體集合
• 外部文件和流

此外，您還可以使用 14 種內建 Type1 字體，這些字體在任何 PDF 檢視器中均可使用。

若要在 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 讓您可以使用 PdfCanvas 類別的方法直接在 PDF 畫布上繪製直線、貝塞爾曲線和常見幾何圖形。使用以 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 還原到先前的狀態。除了撤銷臨時變換和類似變更之外，恢復狀態是移除已套用的裁切的唯一方法。

圖形路徑可讓您使用線條、曲線和更簡單的形狀來建立複雜的形狀，而無需立即繪製它們。使用 Append 方法（例如 AppendLineTo 或 AppendRectangle）為目前路徑新增線段。路徑只有在您明確填滿或描邊後才會產生可見的輸出。

您可以將任何建構的圖形路徑用作裁剪區域，以限制後續的繪製操作。裁切將一直處於作用中狀態，直到圖形狀態恢復為止。

範例庫的 圖形部分 中提供了使用向量圖形的實用可運行範例。

設定顏色和透明度

您可以透過 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 的校準色彩空間。核心 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。

以下 C# 程式碼建立了一個包含插圖的 XObject，並將該插圖繪製在兩個頁面上。

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，然後將其縮放到新的大小即可。這樣，您可以輕鬆地縮小過大的頁面、放大過小的頁面或統一大小不一的文件。

核心 API 的範圍和限制

核心 API 提供對 PDF 建立的精確底層控制，但不提供任何自動佈局功能。它沒有內建的頁邊距、頁首、頁尾或分頁邏輯，所有內容都必須手動定位。文字的測量和跨頁分割完全由您的程式碼負責，這使得它成為創建 PDF 時最繁瑣的手動方式。

自動版面配置（包括對表格、段落和分頁的支援）可透過更高階的版面配置 API實現。

結論

Docotic.Pdf 的核心 API 提供對 PDF 建立的完全控制。它允許您在 PDF 頁面、XObject 和分頁圖案提供的畫布上繪製文字、圖像和向量圖形。

此 API 專為需要精確底層控制的場景而設計：您可以明確定位每個元素，自行管理文字尺寸和頁面分割，並直接操作圖形狀態、顏色和透明度。

總而言之，當精確度和控制至關重要時，核心 API 是建立 PDF 最靈活的工具。