使用核心 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 最灵活的工具。