使用 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 中可用的所有方法，包括 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

用于创建 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 支持取决于字体类型。Type1 字体仅支持拉丁字符集和编码，有一个例外：内置的 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 可恢复到之前的状态。除了撤销临时变换和类似更改之外，恢复状态也是在应用裁剪后移除裁剪的唯一方式。

图形路径可让您在不立即绘制的情况下，使用线段、曲线和更简单的形状构建复杂图形。使用 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 最灵活的工具。