Создание PDF с помощью Core API

Перевод Bit Miracle. Автор оригинала: Sergey Bobrovsky

Обновлено 29 июня 2026

Основной API Docotic.Pdf предоставляет полный контроль над созданием PDF. Он позволяет рисовать текст, изображения и векторную графику на холстах, предоставляемых страницами PDF, XObjects и мозаичными шаблонами.

Вы управляете каждой координатой и каждой операцией рисования, и это дает вам максимальный контроль над компоновкой страниц PDF. Для документов с большим количеством графики или с нестандартной компоновкой, где важна точность, такой уровень контроля незаменим.

С помощью Core API вы также можете добавлять аннотации, поля форм, слои, закладки и многое другое в создаваемые PDF. Этот API — самый гибкий и мощный способ создавать PDF в .NET, предоставляемый Docotic.Pdf.

См. статью, в которой описаны все способы создания PDF, если вам нужен более широкий обзор всех доступных в Docotic.Pdf подходов, включая выходящие за рамки Core API.

Перед началом

Перед тем как начать работать с Core API, настройте окружение, установив Docotic.Pdf и запросив лицензионный ключ.

Установка Docotic.Pdf

Чтобы создавать PDF-документы на C# или VB.NET, начните с установки библиотеки из NuGet.

Install-Package BitMiracle.Docotic.Pdf

Если вы предпочитаете устанавливать библиотеку вручную, загрузите ZIP-архив с бинарными файлами библиотеки, распакуйте его и добавьте в проект ссылку на BitMiracle.Docotic.Pdf.dll.

Получение лицензионного ключа

Для использования библиотеки требуется лицензионный ключ. Чтобы попробовать библиотеку, запросите бесплатный лицензионный ключ с ограниченным сроком действия, заполнив форму на странице загрузки Docotic.Pdf download page.

Базовые примеры создания PDF

В этом разделе приведены базовые примеры, демонстрирующие, как создавать PDF-документы с помощью Core API сначала на C#, а затем на VB.NET.

Как создать PDF на C#

Теперь, когда вы установили Docotic.Pdf и получили лицензионный ключ, создать PDF с помощью Core API очень просто.

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

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

Код показывает, как создать пустой PDF-файл. Первая строка добавляет лицензионный ключ. Без лицензии на строке, где создается экземпляр PdfDocument, будет выброшено исключение. Последняя строка сохраняет документ в PDF-файл.

Внутренняя структура создаваемого файла зависит от параметров сохранения. В этом примере код использует перегрузку метода Save, которая сохраняет файл с параметрами по умолчанию. Чтобы понять, что именно делают эти значения по умолчанию и когда их может потребоваться изменить, см. раздел параметров сохранения.

Чтобы соблюсти традицию программирования, второй пример демонстрирует Hello, world!, созданный с помощью Core API.

using var pdf = new PdfDocument();

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

pdf.Save("hello.pdf");

Код размещает классическую фразу на холсте первой страницы документа, начиная с явно заданной позиции. Эта строка использует шрифт по умолчанию и размер шрифта по умолчанию. Продолжайте чтение, чтобы получить дополнительную информацию о работе с холстом PDF.

Создание PDF с помощью VB.NET

Код 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 всегда рисует одну строку текста. Метод начинает рисование с текущей позиции текста на холсте, если только вы не используете перегрузку с явными координатами. Некоторые перегрузки позволяют задать дополнительные параметры, управляющие тем, как рисуется строка текста.

Вы уже видели простой пример DrawString в фрагменте Hello, world!. Вот еще один пример, который использует параметры рисования строк для подчеркивания текста.

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 может отображать несколько строк текста в пределах заданного прямоугольника. Метод обрабатывает переносы строк и обрезает текст, который не помещается в разрешенное пространство. Параметры рисования текста определяют горизонтальное и вертикальное выравнивание текста и другие аспекты того, как текст позиционируется и отображается.

Вот как рисовать текст в PDF на C#:

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");

Для тонкой настройки внешнего вида текста можно изменить следующие свойства холста:

• межсимвольный интервал
• межсловный интервал
• масштабирование текста
• подъём текста (смещение базовой линии)
• режим отображения (заливка, обводка, заливка и обводка и другие)

Практические примеры методов и свойств, связанных с текстом, см. в группе примеров Text.

Добавление и использование шрифтов

Если вас не устраивает шрифт Helvetica по умолчанию, следует добавить в PDF нужные шрифты, чтобы текст отображался точно так, как задумано.

Docotic.Pdf может добавлять шрифты Type1, TrueType, Compact Font Format (CFF) и OpenType из:

• коллекции системных шрифтов
• внешних файлов и потоков

Кроме того, можно использовать 14 встроенных шрифтов Type1, доступных в любом PDF-просмотрщике.

Чтобы использовать шрифт в PDF, создайте объект PdfFont, используя метод CreateFont или CreateFontFromFile соответствующего объекта PdfDocument. Затем назначьте шрифт холсту перед рисованием текста. Также рекомендуется задать размер шрифта.

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.

Вот как добавить изображение в PDF на C#:

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");

Код создает объект изображения с помощью метода CreateImage соответствующего объекта PdfDocument и рисует изображение на холсте первой страницы.

Подробнее о создании 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, чтобы вернуться к предыдущему состоянию. Помимо отмены временных преобразований и подобных изменений, восстановление состояния — это единственный способ удалить обрезку после ее применения.

Графические пути позволяют строить сложные фигуры из линий, кривых и более простых форм без немедленного рисования. Используйте методы Append, такие как AppendLineTo или AppendRectangle, чтобы добавлять сегменты к текущему пути. Пути не дают видимого результата, пока вы явно не выполните заливку или обводку.

Любой созданный графический путь можно использовать как область отсечения, чтобы ограничить последующие операции рисования. Отсечение остается активным, пока не будет восстановлено состояние графики.

Практические, запускаемые примеры работы с векторной графикой доступны в разделе Graphics в репозитории примеров.

Настройка цветов и прозрачности

Цвета обводки и заливки можно изменять через перо и кисть холста 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");

Также можно выполнять обводку и заливку фигур с использованием мозаичных шаблонов. Шаблон определяется ячейкой шаблона, нарисованной на собственном холсте. Существуют два типа:

• Цветные шаблоны. Их ячейки определяют собственные цвета.
• Неокрашенные шаблоны. Их ячейки окрашиваются цветом пера/кисти в момент использования.

Чтобы использовать шаблон, создайте его с помощью CreateColoredPattern или CreateUncoloredPattern соответствующего объекта PdfDocument. Затем примените шаблон через 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 есть свой собственный холст, поэтому вы можете создавать XObject такой же сложности, как и обычные страницы PDF.

XObject похожи на векторные изображения. Одни и те же объекты можно использовать на нескольких страницах без повторного создания содержимого и без увеличения размера документа. Такие объекты можно масштабировать и поворачивать без появления визуальных артефактов. Благодаря этим качествам XObject идеально подходят для повторяющихся элементов, таких как логотипы, иллюстрации, фоны, водяные знаки и другая повторяющаяся графика.

Создание и использование XObjects

Чтобы создать XObject, используйте метод PdfDocument.CreateXObject. При необходимости измените ширину и высоту объекта. Затем заполните холст текстом, изображениями и графикой так же, как обычный холст страницы.

Используйте метод PdfCanvas.DrawXObject в коде C# или VB.NET, чтобы добавить 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 из исходной страницы и отрисовать его с масштабированием до нового размера. Это позволяет уменьшать слишком большие страницы, увеличивать маленькие или нормализовать документ со смешанными размерами страниц с минимальными усилиями.

Область применения и ограничения Core API

Core API предоставляет точный низкоуровневый контроль над созданием PDF, но не предлагает автоматических возможностей компоновки. Встроенных полей, колонтитулов, логики разбиения на страницы нет, и все содержимое нужно размещать вручную. Измерение текста и разбиение по страницам полностью остаются на стороне вашего кода, что делает этот подход к созданию PDF самым ручным.

Автоматическая компоновка, включая поддержку таблиц, абзацев и разбиения на страницы, доступна через Layout API более высокого уровня.

Заключение

Основной API Docotic.Pdf предоставляет полный контроль над созданием PDF. Он позволяет рисовать текст, изображения и векторную графику на холстах, предоставляемых страницами PDF, XObjects и мозаичными шаблонами.

Этот API предназначен для сценариев, где требуется точный низкоуровневый контроль: вы явно размещаете каждый элемент, самостоятельно управляете измерением текста и разбиением страниц, а также напрямую работаете с состоянием графики, цветами и прозрачностью.

В целом Core API — это самый гибкий инструмент для создания PDF, когда приоритетны точность и контроль.