PDFKit JavaScript (Node.js): методы, примеры, установка |…

Что такое PDFKit и зачем он нужен?

PDFKit — это мощная и гибкая библиотека для JavaScript (Node.js), предназначенная для программного создания PDF-документов «на лету». Она позволяет разработчикам генерировать сложные, многостраничные PDF-файлы с богатым содержимым: текстом, изображениями, таблицами, векторной графикой, аннотациями и формами. В отличие от многих других библиотек, PDFKit работает на низком уровне, предоставляя полный контроль над каждым аспектом документа, от координат расположения элементов до встраивания шрифтов.

Основные сценарии использования PDFKit:

Генерация отчетов и счетов: Создание динамических PDF-документов на основе данных из базы данных или API.
Создание накладных и квитанций: Автоматическая генерация документов для интернет-магазинов и бухгалтерских систем.
Формирование сертификатов и дипломов: Генерация персонализированных документов с уникальными данными для каждого получателя.
Экспорт данных: Преобразование веб-страниц, таблиц или графиков в формат PDF для печати или архивации.
Создание электронных книг и руководств: Программная верстка многостраничных документов с оглавлением и закладками.

PDFKit — это выбор разработчиков, которым нужна производительность, гибкость и полный контроль без использования внешних зависимостей (например, без необходимости устанавливать LibreOffice или wkhtmltopdf).

Установка PDFKit

PDFKit распространяется через пакетный менеджер npm. Для установки выполните следующую команду в терминале в корне вашего проекта:

npm install pdfkit

После установки библиотека будет доступна для импорта в вашем коде. Дополнительных зависимостей не требуется.

Быстрый старт: создание первого PDF-документа

Давайте создадим простой PDF-файл с текстом «Hello, World!».

const PDFDocument = require('pdfkit');
const fs = require('fs');

// Создаем новый PDF-документ
const doc = new PDFDocument();

// Указываем поток для записи результата
doc.pipe(fs.createWriteStream('hello_world.pdf'));

// Добавляем текст на страницу
doc.fontSize(25)
   .text('Hello, World!', 100, 100);

// Финализируем документ и завершаем поток
doc.end();

console.log('PDF-файл "hello_world.pdf" успешно создан!');

После запуска этого кода в той же папке появится файл hello_world.pdf с текстом «Hello, World!».

Основные методы и функции PDFKit

PDFKit предоставляет обширный API. Ниже приведены 10 ключевых методов с подробным описанием и примерами.

1. `text(text, x, y, options)`

Описание: Добавляет текст в документ. Это основной метод для работы с текстом. Он поддерживает перенос строк, выравнивание, отступы и стилизацию.

Параметры:

text (String) — Текст для добавления.
x (Number, optional) — Координата X. Если не указана, текст продолжается с текущей позиции.
y (Number, optional) — Координата Y. Если не указана, текст продолжается с текущей позиции.
options (Object, optional) — Объект с настройками:
- align (String) — Выравнивание: 'left', 'center', 'right', 'justify'.
- indent (Number) — Отступ первой строки.
- paragraphGap (Number) — Отступ между абзацами.
- lineGap (Number) — Межстрочный интервал.
- width (Number) — Ширина текстового блока (для переноса строк).
- height (Number) — Высота текстового блока.
- underline (Boolean) — Подчеркивание.
- strike (Boolean) — Зачеркивание.
- link (String) — URL для ссылки.
- oblique (Boolean) — Наклонный текст (имитация курсива).

Пример:

doc.fontSize(14)
   .text('Этот текст с выравниванием по центру и отступом первой строки.', {
       align: 'center',
       indent: 30,
       width: 400
   });

2. `font(fontFamily, size)`

Описание: Устанавливает шрифт и размер текста для последующих операций. PDFKit поддерживает встроенные шрифты (Helvetica, Times-Roman, Courier) и позволяет подключать пользовательские TrueType (.ttf) или OpenType (.otf) шрифты.

Параметры:

fontFamily (String | Buffer) — Имя встроенного шрифта (например, 'Helvetica-Bold') или путь к файлу шрифта, или Buffer с данными шрифта.
size (Number, optional) — Размер шрифта в пунктах.

Пример:

// Использование встроенного шрифта
doc.font('Times-Roman', 12)
   .text('Текст шрифтом Times New Roman.');

// Подключение пользовательского шрифта
doc.font('./fonts/MyCustomFont.ttf', 16)
   .text('Текст пользовательским шрифтом.');

3. `fontSize(size)`

Описание: Устанавливает размер шрифта для последующего текста. Это сокращенный метод, эквивалентный вызову font(currentFont, size).

Параметры:

size (Number) — Размер шрифта в пунктах.

Пример:

doc.fontSize(18)
   .text('Текст размером 18pt.');

4. `image(path, x, y, options)`

Описание: Вставляет изображение в документ. Поддерживаются форматы JPEG и PNG. Изображение можно масштабировать, поворачивать и обрезать.

Параметры:

path (String | Buffer) — Путь к файлу изображения или Buffer с данными изображения.
x (Number, optional) — Координата X.
y (Number, optional) — Координата Y.
options (Object, optional) — Настройки:
- width (Number) — Ширина изображения (в пунктах).
- height (Number) — Высота изображения (в пунктах).
- scale (Number) — Коэффициент масштабирования (например, 0.5 для уменьшения вдвое).
- fit (Array) — Массив [width, height] для вписывания изображения в заданные размеры с сохранением пропорций.
- align (String) — Выравнивание по горизонтали: 'center', 'left', 'right'.
- valign (String) — Выравнивание по вертикали: 'center', 'top', 'bottom'.
- cover (Array) — Массив [width, height] для заполнения области изображением (с обрезкой).
- link (String) — URL для ссылки.

Пример:

doc.image('path/to/image.jpg', 50, 50, { width: 200, height: 150 })
   .text('Подпись под изображением', 50, 210);

5. `moveTo(x, y)`

Описание: Перемещает «перо» в указанную точку без рисования линии. Используется для начала рисования фигур или линий.

Параметры:

x (Number) — Координата X.
y (Number) — Координата Y.

Пример:

doc.moveTo(100, 100)
   .lineTo(200, 200)
   .stroke(); // Рисует линию от (100,100) до (200,200)

6. `lineTo(x, y)`

Описание: Рисует линию от текущей позиции «пера» до указанной точки. Для отображения линии необходимо вызвать метод stroke().

Параметры:

x (Number) — Координата X конечной точки.
y (Number) — Координата Y конечной точки.

Пример:

doc.moveTo(50, 50)
   .lineTo(150, 50)
   .lineTo(150, 150)
   .closePath() // Замыкает фигуру, рисуя линию обратно к начальной точке
   .stroke();

7. `rect(x, y, width, height)`

Описание: Рисует прямоугольник. Для заливки цветом используется fill(), для обводки — stroke().

Параметры:

x (Number) — Координата X левого верхнего угла.
y (Number) — Координата Y левого верхнего угла.
width (Number) — Ширина прямоугольника.
height (Number) — Высота прямоугольника.

Пример:

doc.rect(100, 100, 200, 100)
   .fill('#FF0000'); // Заливает красным цветом

8. `circle(x, y, radius)`

Описание: Рисует окружность с центром в заданной точке.

Параметры:

x (Number) — Координата X центра.
y (Number) — Координата Y центра.
radius (Number) — Радиус окружности.

Пример:

doc.circle(200, 200, 50)
   .fill('#00FF00', 0.5) // Заливает зеленым с прозрачностью 50%
   .stroke('#000000'); // Обводит черным контуром

9. `addPage(options)`

Описание: Добавляет новую страницу в документ. Можно задать размер, ориентацию и поля.

Параметры:

options (Object, optional) — Настройки страницы:
- size (String | Array) — Размер страницы: 'A4', 'Letter', 'A3' или массив [width, height].
- layout (String) — Ориентация: 'portrait' (книжная) или 'landscape'