Эта страница может содержать автоматически переведенный текст.

Создание PDF-файлов с помощью Core API

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

Обновлено 5 мая 2026

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

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

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

Иллюстрация возможностей основного API для создания PDF-файлов, демонстрирующая векторную графику, размещение изображений и отрисовку текста.

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

Прежде чем начать

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

Установите Docotic.Pdf

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

Install-Package BitMiracle.Docotic.Pdf

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

Получите лицензионный ключ

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

Примеры создания простых 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

Отрисовка текста

Docotic.Pdf предоставляет два основных метода для отображения текста в классе PdfCanvas: 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");

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

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

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

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

Если вам не подходит шрифт 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 зависит от типа шрифта. Шрифты типа 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.

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

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

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

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

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

Для создания объекта 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

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

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

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

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

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

Заключение

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

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

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

Попробуйте библиотеку с бесплатным ключом