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

Создать PDF-документы в C# и VB.NET

Вам, как разработчику .NET, необходимо создавать отчеты, счета, квитанции или другие документы в формате PDF? Используйте библиотеку Docotic.Pdf для создания PDF-документов в .NET Core, .NET Standard или проектах .NET Framework. Вы можете сделать это легко и ничего не зная о формате PDF.

Создание PDF-документов на C# и VB.NET.

.NET API для создания PDF-файлов

Docotic.Pdf — это библиотека полностью управляемого кода без внешних зависимостей. Вы можете использовать её, чтобы создавать PDF-документы в Windows, Linux, а также облаках Amazon и Azure. macOS, iOS, Android, и другие облачные среды тоже подойдут.

Библиотека предоставляет различные способы создания PDF-документов. Во-первых, вы можете использовать высокоуровневый API разметки для добавления верхних и нижних колонтитулов страниц, таблиц, абзацев и автоматического разбиения содержимого на страницы. API разметки доступен в бесплатном дополнении Docotic.Pdf.Layout.

Или вы можете создавать документы PDF на основе шаблонов HTML, используя дополнение HTML to PDF (тоже бесплатно). Дополнительные сведения смотрите в статье Преобразование HTML в PDF.

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

Библиотека Docotic.Pdf 9.3.17014-dev Дополнение Layout 9.3.17014-dev Дополнение HTML в PDF 9.3.17014-dev
Регрессионные тесты 14,645 прошло Всего загрузок NuGet 4,172,488

Вы также можете использовать дополнения вместе с основной библиотекой. Например, создайте PDF-документ используя API разметки, а затем добавляйте дополнительный контент с помощью основной библиотеки. Обратите внимание, что дополнение Layout поддерживает .NET Standard 2.1, .NET Core, .NET 5 и более новые платформы. Основная библиотека и дополнение HTML to PDF поддерживает .NET Standard 2.0, .NET 4.7.2+, .NET Core, .NET 5 и новее.

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

Создавать PDF-документы с помощью API разметки

В этом примере на C# показано, как создать PDF-документ на C# с помощью API разметки:

PdfDocumentBuilder
    .Create()
    .Generate("long-text.pdf", doc => doc.Pages(page =>
    {
        string text = File.ReadAllText(@"C# in Depth, Fourth Edition.txt");
        page.Content().Text(text);

        page.Footer().AlignCenter().Text(t => t.CurrentPageNumber());
    }));

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

API разметки — это текучий (fluent) API. Большинство вызовов можно объединить в цепочку, что позволяет писать код более компактно, чем с «декларативными» фреймворками. Давайте рассмотрим API более подробно.

Установить свойства PDF-документа

Генерация PDF начинается с класса PdfDocumentBuilder. Он позволяет вам указать свойства выходного PDF-документа. Например, вы можете установить метаданные, шифрование, версию PDF или включить режим быстрого просмотра в Интернете. Вот базовый пример на C#:

PdfDocumentBuilder
    .Create()
    .Encryption(new PdfStandardEncryptionHandler("owner", "user"))
    .Info(info =>
    {
        info.Author = "Docotic.Pdf library";
        info.Title = "How to create PDF in .NET";
        info.Keywords = "C#, VB.NET";
    })
    .Version(PdfVersion.Pdf16)
    .Generate("result.pdf", doc => doc.Pages(_ => {}));

В этом примере создается пустой PDF-документ, защищенный паролем, с указанными метаданными и сохраняется в файл. Вы также можете сохранить документ в поток, просто воспользуйтесь вызовом PdfDocumentBuilder.Generate(Stream, ..).

После настройки PdfDocumentBuilder пора заполнить PDF-документ содержимым. API разметки предоставляет объект Document для регистрации общих ресурсы (типографика, изображения) и определения содержимого страниц PDF. Вы можете настроить Document, передаваемый вторым аргументом в методы PdfDocumentBuilder.Generate. Давайте научимся настраивать PDF-страницы.

Определить макет страницы PDF

В этом примере на C# показано, как создать документ PDF со страницами формата A3 в альбомной ориентации:

PdfDocumentBuilder.Create().Generate("pages.pdf", doc =>
{
    doc.Pages((PageLayout page) =>
    {
        page.Size(PdfPaperSize.A3, PdfPaperOrientation.Landscape)
            .MarginVertical(50)
            .MarginHorizontal(40);

        page.Header().PaddingBottom(30).AlignRight().Text("Hello PDF");

        page.Content().Column(c =>
        {
            c.Item().Text("Page 1");
            c.Item().PageBreak();
            c.Item().Text("Page 2");
        });

        page.Footer().Text(t => t.CurrentPageNumber());
    });
});

Метод Document.Pages() определяет макет для одной или более страниц. Для начала, пример кода устанавливает общие настройки для всех страниц — размер, ориентацию, поля. Вы также можете указать направление содержимого, стиль текста по умолчанию или цвет фона.

Затем пример генерирует разметку и содержимое страницы. Класс PageLayout предоставляет методы для размещения содержимого страницы в следующих слотах:

Background() — фоновый слой, покрытый другим содержимым
Header() — общий заголовок для всех страниц
Content() - основное содержимое страницы
Footer() — общий нижний колонтитул для всех страниц
Foreground() — слой переднего плана, который покрывает другой контент

Механизм компоновки генерирует страницы в зависимости от содержимого, добавленного в слот PageLayout.Content(). Остальные слоты повторяются на каждой странице. Вы можете добавлять контент в слоты с помощью класса LayoutContainer. Это ключевой строительный блок API разметки, который позволяет создавать произвольные макеты, таблицы, текст или изображения.

В предыдущем примере используется метод LayoutContainer.Column, который вертикально укладывает содержимое. В столбце содержится 3 элемента — текстовый фрагмент для первой страницы, явный разрыв страницы и текстовый фрагмент для второй страницы.

Есть также метод LayoutContainer.Row. Посмотрите как создавать PDF-документы с несколькими столбцами используя строки и столбцы вместе.

В PDF-документе можно смешивать разные макеты страниц. Просто вызовите метод Document.Pages несколько раз. Посмотрите пример настройки разметки страницы PDF на GitHub.

Добавить текст в документы PDF

Текст является важной частью PDF-документов. Вы можете использовать методы LayoutContainer.Text чтобы добавить текст. Ранее вы видели варианты использования перегрузки LayoutContainer.Text(string). Давайте посмотрите на другую перегрузку этого метода:

PdfDocumentBuilder.Create().Generate("text.pdf", doc =>
{
    doc.Pages(p => p.Content().Text(text =>
    {
        text.Span("VB.NET").Style(t => t.Strong);
        text.Span(" is a multi-paradigm, object-oriented programming language, implemented on.NET, Mono, and the ");
        text.Hyperlink(".NET Framework", new Uri("https://dotnet.microsoft.com/en-us/download/dotnet-framework"));
        text.Line(".");

        text.Line("Microsoft launched VB.NET in 2002 as the successor to its original Visual Basic language.");
    }));
});

Класс TextContainer предоставляет методы для рисования текста, ссылок и номеров страниц. Используйте методы Span и Line, чтобы добавить текст в текущую строку. Метод Line дополнительно завершает текущую строку. В этом примере также используется метод Hyperlink, который добавляет ссылку на внешний ресурс.

Вот еще один пример, показывающий, как использовать динамические номера страниц в нижнем колонтитуле страниц:

PdfDocumentBuilder.Create().Generate("footer.pdf", doc =>
{
    doc.Pages(p => p.Footer().AlignRight().Text(text =>
    {
        text.Style(t => t.Parent.FontColor(new PdfRgbColor(255, 0, 0)));

        text.CurrentPageNumber();
        text.Span(" / ");
        text.PageCount();
    }));
});

API разметки предоставляет способ форматирования номеров страниц. Например, вы можете нарисовать шестнадцатеричные номера страниц так:

text.CurrentPageNumber().Format(p => "0x" + p?.ToString("x2"));

Пример Добавление верхнего и нижнего колонтитула в PDF-документы на C# и VB.NET показывает, как форматировать номера страниц в виде римских цифр.

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

Типографика

Стили текста позволяют настроить внешний вид текста. Класс TextStyle предоставляет методы для изменения размера шрифта, межбуквенного интервала, цвета и других свойств текста. Объекты TextStyle являются неизменяемыми, поэтому каждый вызов метода создает новый стиль текста. Вы можете применить стили текста на разных уровнях разметки:

PdfDocumentBuilder.Create().Generate("text-styles.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.TextStyle(TextStyle.Parent.FontSize(30));

        page.Content()
            .TextStyle(TextStyle.Parent.FontColor(new PdfRgbColor(0, 0, 255)))
            .Text(t =>
            {
                t.Style(TextStyle.Parent.Underline());

                t.Span("Hello PDF").Style(TextStyle.Parent.DirectionRightToLeft());
            });
    });
});

Свойство TextStyle.Parent возвращает специальный стиль, в котором все свойства текста не определены. В предыдущем примере «Hello PDF» отображается синим подчеркнутым шрифтом размером 30 пунктов в обратном порядке (справа налево). Посмотрите пример Настроить внешний вид текста в документах PDF для ещё одного примера того, как наследуются стили текста.

Класс TextStyle поддерживает настройку всего, кроме связанного шрифта. Используйте методы Document.TextStyleWithFont, когда вам нужно указать собственный шрифт для вашего стиля текста. В этом примере на C# показано, как использовать системный шрифт:

PdfDocumentBuilder.Create().Generate("fonts.pdf", doc =>
{
    doc.Pages(page =>
    {
        TextStyle style = doc.TextStyleWithFont(SystemFont.Family("Arial").Bold());
        page.Content().Text("Bold text").Style(style);
    });
});

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

API разметки предоставляет коллекцию предопределенных стилей. Вы можете использовать или настраивать их через Класс Typography:

PdfDocumentBuilder.Create().Generate("typography.pdf", doc =>
{
    doc.Typography(t =>
    {
        var baseFont = new FileInfo("arial.ttf");
        t.Document = doc.TextStyleWithFont(baseFont);
        t.Header = t.Parent.FontSize(20).FontColor(new PdfGrayColor(20));
        t.Footer = t.Footnote;
    });

    doc.Pages(page =>
    {
        page.Header().AlignCenter().Text("Header");

        page.Content().Text(t =>
        {
            t.Line("Title").Style(t => t.Title);
            t.Line("Heading 1").Style(t => t.Heading1);
            t.Line("Regular");
        });

        page.Footer().Height(20).AlignCenter().Text(t => t.CurrentPageNumber());
    });
});

С классом Typography вам не нужно использовать переменные для хранения ссылок на стили текста. Вы прописываете необходимые стили с помощью методов Document.Typography а затем загружаете их из объекта Typography. Посмотрите, как использовать предопределенные и пользовательские стили в примере Типографика.

Изображения

Подобно тексту и шрифтам, изображения являются еще одной фундаментальной частью PDF-документов. API разметки позволяет вам добавлять изображения так:

PdfDocumentBuilder.Create().Generate("image.pdf", doc =>
{
    var imageFile = new FileInfo("image.jpg");
    Image image = doc.Image(imageFile);
    doc.Pages(page => page.Content().MaxWidth(200).Image(image));
});

Таблицы

API разметки позволяет создавать таблицы. В этом примере на C# показано, как добавить таблицу в PDF-документ:

PdfDocumentBuilder.Create().Generate("table.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Content().Table(t =>
        {
            t.Columns(c =>
            {
                c.ConstantColumn(200);
                c.RelativeColumn(1);
            });

            t.Header(h =>
            {
                h.Cell().Text("Product");
                h.Cell().Text("Features");
            });

            t.Cell().Text("Docotic.Pdf");
            t.Cell().Text("Extract text, PDF to images, compress PDF");
            t.Cell().Text("Docotic.Pdf.Layout");
            t.Cell().Text("Create PDF");
        });
    });
});

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

Внутренние ссылки

PDF-документы поддерживают внутренние ссылки, которые позволяют создавать закладки или оглавление. В этом простом примере на C# показано, как добавить ссылку на раздел документа с помощью API разметки:

PdfDocumentBuilder.Create().Generate("link.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Content().Column(c =>
        {
            const string SectionName = "Chapter 1";
            c.Item().SectionLink(SectionName).Text("Link");

            c.Item().PageBreak();

            c.Item().Section(SectionName).Text("Target");
        });
    });
});

Вы также можете скачать и попробовать пример Добавить оглавление в документы PDF с GitHub.

Сложные макеты

Вы можете комбинировать различные компоненты разметки для создания сложных PDF-документов. Скачайте и попробуйте Создать PDF-документы со сложной разметкой с GitHub.

Возможно расширить API разметки. Методы LayoutContainer.Component и LayoutContainer.Container позволяют повторно использовать пользовательские компоненты. Пример Компоненты разметки показывает, как реализовать пользовательский компонент, используя интерфейс ILayoutComponent.

Вывод

Библиотека Docotic.Pdf предоставляет различные средства для создания PDF-документов на C# и VB.NET. Вы можете создавать документы PDF с нуля, используя или не используя дополнение Layout. Или вы можете создать PDF из HTML с помощью дополнения HTML to PDF.

Свяжитесь с нами, если у вас есть вопросы о создании PDF-файлов.