pdfmake: создание PDF в JavaScript — мастерская и 9 примеров
Создаём PDF из данных: расчёт стоимости, длинный реестр, отчёт, QR и протокол. Девять живых примеров с настоящим просмотром, Node.js, Windows/Linux и исходники.

pdfmake: PDF из данных, который можно сразу скачать
Пользователь заполнил заявку, выбрал услуги или открыл отчёт в кабинете. Теперь ему нужен документ: отправить коллеге, приложить к письму, распечатать или сохранить вместе с проектом. Ручной перенос данных в редактор отнимает время и оставляет возможность перепутать клиента, период либо сумму. pdfmake позволяет описать шаблон кодом и каждый раз создавать PDF из актуальных данных приложения.
На этой странице можно попробовать девять настоящих сценариев: уведомление, памятку, расчёт стоимости, длинный реестр, предложение в две колонки, карточку с QR, отчёт, недельный план и протокол проверки. Измените JSON, нажмите «Создать PDF» и пролистайте получившийся файл прямо в мастерской. Скачивается полноценный PDF, а не снимок интерфейса.
В исходниках есть общий генератор для браузера и Node.js, кириллические шрифты, проверка данных, CLI, внутренний HTTP API, тесты и инструкция для Linux/VPS. Разберём, где подходит такой подход, как связаны данные и вёрстка, почему таблица занимает несколько страниц и какие детали нужно учесть перед добавлением кнопки «Скачать документ» в свой сервис.
Где применять: CRM, кабинет клиента, отчёты и документы
В CRM генератор собирает предварительный расчёт по выбранным работам: название, количество, цена и итог поступают из карточки проекта. В сервисном кабинете полезны подтверждение обращения и памятка о следующем действии. В системе учёта можно выгружать реестр за период, сохраняя номера записей и повтор заголовка на каждой странице. Читателю не нужно открывать приложение ради одного документа.
Для внутренней команды пригодятся недельные планы, результаты проверки, короткие инструкции и сводки показателей. Один шаблон можно запускать вручную или по расписанию. При массовой подготовке сервер получает список клиентов, выбирает данные каждого и создаёт отдельные файлы. Оформление остаётся одинаковым, а содержание определяется источником данных.
Начинайте с задачи получателя: что он должен понять, проверить или согласовать. У документа должны быть узнаваемый заголовок, идентификатор, период и единицы измерения. Автоматизация не исправит плохо определённый показатель: если «выручка» вычисляется по разным правилам в кабинете и PDF, красивый шаблон только скроет проблему. Сначала согласуйте смысл полей, затем оформление.
pdfmake, PDF.js, печать HTML и редактируемая презентация
pdfmake создаёт PDF по JavaScript-описанию: текст, списки, таблицы, колонки, изображения, QR и настройки страниц. Это отдельная модель документа, а не HTML с Bootstrap-классами. Браузер для серверной генерации не требуется: Node.js формирует файл самостоятельно. Поток текста и разбиение на страницы рассчитывает библиотека.
PDF.js решает другую задачу — отображает уже существующие PDF. В нашей мастерской обе библиотеки работают вместе: pdfmake создаёт байты, PDF.js рисует их на canvas. О просмотрщике отдельно рассказано в материале PDF.js с семью сценариями. Наличие просмотрщика само по себе не создаёт документы.
Если нужно печатать сложную готовую HTML-страницу с CSS, рассмотрите браузерную печать через Puppeteer. Если получатель должен редактировать слайды, таблицы и диаграммы в презентации, подойдёт PptxGenJS. Для отчётов из структурированных данных pdfmake удобен понятным программным шаблоном и одинаковой логикой в браузере и Node.js.
Версии: примеры используют API pdfmake 0.3
На 18 ноября 2026 года проект закреплён на pdfmake 0.3.14, PDF.js 6.5.438 и Bootstrap 5.3.9. Сборку выполняет esbuild 0.28.2. Для команд используем Node.js 24 LTS не ниже 24.15.0. Точные версии и транзитивные зависимости сохранены в package-lock.json: повторяемая установка начинается с npm ci.
В интернете встречается много примеров для ветки 0.2 с другим серверным API и callback-методами. Здесь сервер импортирует pdfmake, регистрирует шрифты и ожидает Promise от getBuffer. Не смешивайте фрагменты разных веток в одном проекте. Официальные отправные точки — запуск на сервере и подключение в браузере.
Готовая мастерская использует локальные JavaScript, CSS, worker и шрифты. Генерация не требует CDN и не отправляет введённый JSON в облачный конвертер. Это не отменяет необходимости обновлять зависимости: после смены версии повторяйте тесты и визуальную проверку своих документов, особенно длинных таблиц и нестандартных шрифтов.
Фрагмент package.json
{"name":"aen-pdfmake-workshop","version":"1.0.0","private":true,"type":"module","license":"MIT","engines":{"node":">=24.15.0"},"scripts":{"build":"node tools/build.mjs","test":"node --test tests/*.test.mjs","capture":"node tools/capture.mjs","generate":"node tools/generate.mjs","serve":"node tools/serve.mjs","api":"node tools/api.mjs"},"dependencies":{"pdfmake":"0.3.14","pdfjs-dist":"6.5.438","bootstrap":"5.3.9"},"devDependencies":{"esbuild":"0.28.2","pdf-lib":"1.17.1"}}
Мини-мастерская: девять документов и настоящий просмотр PDF
Выберите сценарий и прочитайте подсказку под списком: она объясняет применение и полезное изменение для первого эксперимента. В JSON находятся данные документа, рядом выбирается цвет заголовков. После генерации появятся размер файла, количество страниц, кнопки скачивания и просмотр. У реестра можно перейти на последнюю страницу и найти строку 85.
Начните с изменения имени клиента либо одного числа. Затем попробуйте ошибку: отрицательную цену, пустой заголовок или незакрытую JSON-скобку. Мастерская покажет понятное сообщение. После любого редактирования старый PDF сбрасывается: кнопка скачивания не должна выдавать предыдущий результат под видом нового. Кнопка возврата восстанавливает исходные данные выбранного сценария.
На небольшом экране удобнее открыть мастерскую отдельно. Встроенный просмотр показывает настоящие страницы, а для увеличения, поиска и печати можно открыть PDF в отдельной вкладке или скачать его. Если PDF.js не загрузился, готовый файл остаётся доступен. Ниже мастерской находится просмотр точных исходников с копированием и скачиванием каждого файла.
Windows: запустить мастерскую и создать первый PDF
Распакуйте архив в отдельную папку, откройте там PowerShell и проверьте Node.js. Для изменения кода установите зависимости, выполните тесты и соберите public. Команда serve поднимает простой HTTP-сервер на локальном адресе. После запуска откройте http://127.0.0.1:8575/ и создайте первый документ. Остановка выполняется через Ctrl+C в этом терминале.
В архив уже включена собранная public. Если хочется только попробовать браузерную мастерскую, достаточно Node.js и npm run serve: этот сервер использует стандартные модули. npm ci понадобится для серверной генерации, тестов и пересборки. Открытие index.html двойным щелчком не заменяет HTTP: загрузке worker и исходников нужен корректный адрес страницы.
Если порт занят, задайте другой PORT, не завершая чужие процессы. В PowerShell используем npm.cmd и curl.exe, чтобы избежать неоднозначности команд и настроек запуска скриптов. Путь выходного PDF передавайте в кавычках, особенно если он содержит пробелы. CLI не перезаписывает существующий файл: для повторного опыта выберите другое имя.
Фрагмент README.md
node --version
npm.cmd ci --ignore-scripts
npm.cmd test
npm.cmd run build
npm.cmd run serve
Фрагмент README.md
npm.cmd run generate -- invoice fixtures/invoice.json "$env:TEMP\invoice-demo.pdf"
$env:PORT = '8577'
npm.cmd run serve
Linux: генерация без браузера и офисного пакета
На Linux работают те же исходники и JSON-наборы. Установите совместимый Node.js способом, принятым для вашего дистрибутива, и выполните npm ci в каталоге проекта. Не переносите node_modules с Windows: сборочные инструменты могут содержать платформенные бинарные компоненты. HTML, CSS и готовый браузерный bundle из public переносить можно.
Команда generate принимает имя сценария, входной JSON и новый путь PDF. Для report создаётся трёхстраничный отчёт. Ни Chromium, ни LibreOffice, ни установленный графический интерфейс для генерации не нужны. Шрифты находятся в зависимости pdfmake и подключаются явно, поэтому кириллица не зависит от набора системных шрифтов сервера.
Запускайте CLI от отдельного пользователя и храните приватные документы вне открытого каталога сайта. Успешный процесс сообщает размер результата и заканчивается кодом ноль; ошибка даёт ненулевой код. Планировщик или очередь должны учитывать этот статус. Иначе после неудачного запуска приложение рискует отправить ранее созданный файл, который уже не соответствует данным.
Фрагмент README.md
node --version
npm ci --ignore-scripts
npm test
npm run build
npm run generate -- report fixtures/report.json /tmp/report-demo.pdf
npm run serve
Как проходит путь от JSON до страницы PDF
В проекте есть три последовательных этапа. Сначала parseInput разбирает JSON и проверяет размер. Затем validateInput создаёт новый объект с допустимыми полями, а makeDefinition превращает его в Document Definition — описание документа. В последнем этапе pdfmake рассчитывает расположение элементов и формирует PDF. Браузер и Node.js используют одну функцию шаблона.
Document Definition — обычный JavaScript-объект, однако это не просто сохранённый пользовательский JSON. В нём есть функции колонтитулов, настройки таблиц и ссылки на зарегистрированные шрифты. Такие решения принадлежат коду приложения. Посетитель меняет данные, а не получает право передавать произвольный путь к файлу, изображение или кусок шаблона.
Во время layout библиотека может дополнять переданные структуры служебными свойствами. Поэтому сохраняемый манифест данных снимается отдельной копией до генерации. Эту тонкость легко пропустить: обычный текст работает, а списки после обработки могут перестать сериализоваться в JSON. Мы отдельно проверяем, что манифест остаётся сериализуемым и соответствует исходным данным.
const { definition, manifest } = makeDefinition('invoice', data);
const bytes = await pdfmake.createPdf(definition).getBuffer();
// manifest хранит отдельную копию проверенных данных, не layout-объекты.
Проверка данных: размер, типы, числа и разрешённые поля
Ограничение входного JSON в мастерской составляет 32 KiB. Дополнительно проверяются длина строк, количество элементов и тип каждого поля. Цена хранится целым количеством копеек, количество — положительным целым числом. Строка «2» не подменяет число 2 автоматически: такое преобразование должно быть осознанным решением контракта, а не случайным побочным эффектом.
Из входного объекта копируются только ожидаемые поля. Даже если добавить content, image или путь к файлу, они не станут частью шаблона. Сервер запрещает сетевые загрузки, а доступ к файловой системе ограничивает четырьмя известными файлами Roboto. У карточки QR разрешена HTTPS-ссылка без логина и пароля; библиотека кодирует её как содержимое, не запрашивая этот адрес.
Эти границы рассчитаны на учебные сценарии: до 25 позиций расчёта, 120 строк реестра и 18 команд недельного плана. Они не описывают универсальные пределы pdfmake. В своём сервисе согласуйте максимальные объёмы с задачей, измерьте время и память, а затем определите, какой документ можно собирать по клику и какой лучше отправить в очередь.
Фрагмент src/definition.mjs
export function parseInput(raw){if(typeof raw!=='string'||new TextEncoder().encode(raw).length>MAX_BYTES)throw Error('Лимит входных данных: 32 KiB JSON.');try{return JSON.parse(raw);}catch{throw Error('JSON не разобран. Проверьте кавычки, запятые и скобки.');}}
Пример 1. Подтверждение заявки с понятным следующим шагом
Первый пример превращает данные обращения в одностраничное уведомление. Здесь есть номер, дата, получатель, поясняющий текст и следующее действие. Такой документ полезен после регистрации заявки, согласования встречи или передачи запроса в работу. Его можно приложить к письму либо сохранить в истории клиента.
Измените customer и next, создайте PDF и выделите текст в обычном просмотрщике. Надписи остаются текстом, а не изображением: их можно искать и копировать. При этом наличие текстового слоя ещё не означает соответствие стандартам доступности. Структуру чтения и требования конкретного процесса нужно проверять отдельно.
В реальной системе номер и дату лучше брать из сохранённого обращения, а не генерировать независимо в браузере. Если документ создаётся повторно, он должен ссылаться на ту же заявку. Добавьте контакт ответственного и ясное ожидание по сроку, когда это определено вашим процессом. Полезность уведомления определяется тем, понимает ли человек, что делать дальше.
Фрагмент src/definition.mjs
if(id==='letter')content.push({text:`${d.number} / ${d.date}`,style:'sub'},heading(d.customer),para(d.text),{text:d.next,style:'callout'});
Пример 2. Памятка: кириллица, списки и выделение текста
Во втором сценарии короткая инструкция состоит из крупного вступления, нумерованных шагов и примечания. pdfmake поддерживает обычные и нумерованные списки, фрагменты разного начертания внутри абзаца и именованные стили. Это удобно для инструкций сотрудникам, подготовки к запуску и памяток клиенту после оказания услуги.
Попробуйте добавить длинный пункт и посмотрите, как переносится строка. Интервал между строками и отступ после абзаца решают разные задачи: первый влияет на плотность текста внутри блока, второй отделяет смысловые части. Если уменьшить всё сразу, на лист поместится больше слов, но читателю станет труднее выполнять последовательность действий.
В примечании специально есть буква ё и русские слова с разными сочетаниями букв. Проверка кириллицы должна включать обычное, жирное и курсивное начертание. Наличие одного подходящего TTF не гарантирует, что bold и italics настроены правильно. Используйте стабильный набор шрифтов и просматривайте именно созданный PDF, а не только HTML-редактор данных.
Фрагмент src/definition.mjs
if(id==='styles')content.push({text:d.lead,style:'lead'},heading('Порядок действий'),{ol:d.steps,margin:[0,0,0,20],lineHeight:1.5},{text:[{text:'Обратите внимание. ',bold:true},d.note],italics:true,color:C.muted},heading('Один смысл - разные акценты'),{text:[{text:'Готово',bold:true,color:accent},' означает проверенный результат. ',{text:'В работе',italics:true},' требует следующего действия.']});
Пример 3. Расчёт стоимости без ошибок дробных чисел
Расчёт строится из строк работ: наименование, количество, цена и сумма. В готовом примере итог равен 79 500,00 руб. Цена передаётся в копейках: 125050 означает 1 250,50 руб. Арифметика выполняется на целых числах, а форматирование в рубли применяется только при выводе. Так проще избежать распространённых сюрпризов двоичного представления десятичных дробей.
Измените цену одной работы и проверьте строку вместе с итогом. Затем попробуйте отрицательное значение или нулевое количество: документ не должен создаваться. Для дробных объёмов вроде 1,25 часа нужен отдельный контракт точности и округления. Не добавляйте parseFloat поверх текущего примера, не определив правила расчёта.
Это предварительный учебный расчёт без налоговой модели, банковских реквизитов и обязательных полей счёта. Для реального документа цены и доступ к проекту проверяет сервер. Значение из браузера нельзя считать доверенным только потому, что оно успешно прошло проверку типа. Разделяйте математическую корректность, бизнес-правила и требования к конкретному виду документа.
Фрагмент src/definition.mjs
export function money(k){return (k/100).toLocaleString('ru-RU',{minimumFractionDigits:2,maximumFractionDigits:2})+' руб.';}
export function invoiceTotal(rows){const total=rows.reduce((s,r)=>s+r.quantity*r.priceKopecks,0);if(!Number.isSafeInteger(total))throw Error('Сумма выходит за допустимый диапазон.');return total;}
Пример 4. Реестр: 85 строк, повтор шапки и пять страниц
Длинный реестр показывает то, что трудно оценить на одной красивой странице: автоматическое продолжение таблицы. В стандартном наборе 85 обращений, они занимают пять страниц. headerRows задаёт повтор заголовка, dontBreakRows сохраняет небольшую строку целиком, а footer показывает текущую страницу и общее количество. На последней странице есть явная отметка окончания реестра.
Измените текст последней записи и найдите его после генерации. Проверьте не только первые строки, но и границы страниц: номера должны идти непрерывно, шапка повторяться, подписи не попадать на колонтитул. Для контроля потери данных полезно сравнивать количество строк исходного массива и выгрузки, а не только размер файла.
Запрет разрыва строки не подходит для ячейки, которая сама длиннее страницы. Наш контракт ограничивает длину задачи и других полей, поэтому строки помещаются. Для большого текстового описания лучше выделить отдельный раздел. Полезные параметры, ширины и особенности объединённых ячеек приведены в документации таблиц pdfmake.
Фрагмент src/definition.mjs
const table=(headers,widths,rows,options={})=>({table:{headerRows:1,widths,body:[headers.map(text=>({text,style:'th'})),...rows],dontBreakRows:true,...options},layout:{fillColor:i=>i===0?C.teal:(i%2===0?C.pale:null),hLineWidth:()=>0.5,vLineWidth:()=>0,hLineColor:()=>C.line,paddingLeft:()=>8,paddingRight:()=>8,paddingTop:()=>8,paddingBottom:()=>8},margin:[0,10,0,16]});
Пример 5. Две колонки для предложения клиенту
Предложение разделяет содержание на два вопроса: что получит команда и как будет организовано внедрение. Слева расположен маркированный список результатов, справа — последовательность этапов. Общая вводная и итоговая заметка занимают всю доступную ширину. Такой документ удобно использовать перед пилотом, чтобы согласовать ожидания и границы работы.
Колонки pdfmake относятся к потоку документа. Это не CSS Grid и не Bootstrap row: они описываются отдельными объектами, ширинами и промежутком columnGap. Внутри колонки stack объединяет несколько блоков. Если один список станет длиннее, это повлияет на занимаемое место и дальнейший перенос содержимого.
Сначала проверьте самые длинные реальные названия и пункты, а не только короткий демонстрационный набор. Не решайте переполнение постоянным уменьшением шрифта. Иногда правильнее вынести детали в следующий раздел и оставить в двух колонках только результат и этапы. Хороший шаблон помогает увидеть договорённость, а не втиснуть весь проект на один лист.
Фрагмент src/definition.mjs
if(id==='proposal')content.push({text:d.customer,style:'sub'},para(d.intro),{columns:[{stack:[heading(d.leftTitle),{ul:d.left,lineHeight:1.4}]},{stack:[heading(d.rightTitle),{ol:d.right,lineHeight:1.4}]}],columnGap:28}, {text:d.note,style:'callout',margin:[0,24,0,0]});
Пример 6. SVG-иллюстрация и QR со ссылкой на инструкцию
Карточка сервисной заявки содержит крупный идентификатор, подпись, QR и векторную иллюстрацию статуса. QR удобно печатать на карточке оборудования или выдавать участнику события: человек сканирует код и открывает связанную инструкцию. В нашем примере код содержит обычную HTTPS-ссылку и не является платёжным документом.
Изображение здесь задано встроенным SVG, поэтому при масштабировании линии остаются чёткими, а генератор не зависит от внешнего сервера картинок. Для своих фотографий подготовьте изображения заранее, ограничьте размер и проверьте пропорции. Произвольный SVG от посетителя не следует передавать напрямую в этот шаблон: встроенная иллюстрация является доверенной частью проекта.
Перед печатью QR проверьте адрес и читаемость на целевом размере. Избыточно длинная ссылка повышает плотность кода; короткий стабильный адрес обычно практичнее. Не помещайте в QR пароль или закрытый токен, который окажется доступен каждому владельцу распечатки. Доступ к документу всё равно должен проверять сервер назначения.
{ qr: data.url, fit: 120, eccLevel: 'M' }
// SVG в мастерской задан кодом шаблона; URL картинки от пользователя не принимается.
Параметры размера и коррекции ошибок описаны в официальном разделе QR.
Пример 7. Отчёт с разделами и общей нумерацией
Отчёт состоит из трёх частей: что сделали, какие показатели получили и какие действия нужны дальше. Каждая часть начинается на новой странице через pageBreak: before. Такой приём полезен для коротких отчётов с устойчивой структурой. При этом приложение передаёт данные и выводы, а шаблон определяет порядок чтения.
Колонтитулы формируются отдельно от content. Функция footer получает текущий номер и итоговое количество страниц, поэтому подпись не требует предварительного ручного подсчёта. Верхний колонтитул помогает узнать документ, если страницы распечатали или переслали по отдельности. Для производственного отчёта туда можно добавить короткий идентификатор проекта и версию.
Принудительная новая страница — осознанное решение, а не универсальное оформление каждого абзаца. В примере свободное место подчёркивает разделы; для плотного реестра оно было бы лишним. Если текст отчёта вырастет, страниц станет больше. Устанавливать в интерфейсе постоянное число «3» нельзя: мастерская читает фактическое количество из созданного PDF.
footer: (currentPage, pageCount) => ({
text: `${currentPage} / ${pageCount}`,
alignment: 'right', fontSize: 8, margin: [42, 18, 42, 0]
})
Статические и динамические варианты приведены в документации колонтитулов.
Пример 8. Альбомный A4 для недельного плана
Недельный план содержит команду и пять рабочих дней. Для такой таблицы горизонтальный лист удобнее вертикального: текст не приходится дробить на короткие строки. pageOrientation меняет ориентацию самого PDF, поэтому скачанный файл остаётся альбомным независимо от ширины экрана и масштаба браузера.
Добавьте команду и измените занятия на несколько дней. Внутри строки должно быть ровно пять значений: это проверяется до генерации. Если данные приходят из календаря, сначала приведите их к общей временной зоне и выбранной рабочей неделе. Шаблон не должен самостоятельно угадывать, к какому дню относится событие рядом с полуночью.
Для большого расписания одного изменения ориентации недостаточно. Определите, что важнее: показать целую неделю, подробные задачи или нагрузку конкретного сотрудника. Иногда лучше создать несколько листов по командам. В печатном документе недоступна горизонтальная прокрутка таблицы, поэтому ширину и детализацию нужно выбирать ещё на этапе проектирования отчёта.
const definition = {
pageSize: 'A4', pageOrientation: 'landscape',
pageMargins: [42, 58, 42, 54],
content: [/* таблица выбранной недели */]
};
Пример 9. Протокол проверки и область подписей
Последний сценарий собирает внутренний протокол: номер, ответственная команда, перечень проверок, результаты и замечание. Ниже находится общий блок для подтверждения. Свойство unbreakable удерживает небольшой блок с подписями целиком, чтобы заголовок и линии не оказались на разных страницах. При нехватке места такой блок переносится дальше.
Добавьте ещё одну проверку и укажите конкретное замечание вместо общего «не работает». Протокол полезнее, когда результат связан с проверяемым действием: какой файл скачан, какой набор импортирован, какой сценарий пройден. Поле «Пройдено» само по себе не объясняет условия испытания и не заменяет доказательства.
Пустая линия подписи не является электронной подписью, а этот шаблон не объявляется обязательной формой документа. Если требуется юридически значимое подписание, оно выполняется отдельной системой с соответствующей проверкой. Для внутреннего учёта можно сохранять PDF вместе с идентификатором задачи, автором, временем и исходными результатами, чтобы восстановить контекст позднее.
{ unbreakable: true, stack: [
{ text: 'Подтверждение проверки', bold: true },
{ columns: [
{ text: 'Исполнитель\n\n____________________' },
{ text: 'Ответственный\n\n____________________' }
] }
] }
Шрифты: почему UTF-8 недостаточно для кириллицы
Правильная кодировка сохраняет символы в данных, но не создаёт нужные глифы в шрифте. Если выбранный шрифт не содержит букву, в PDF появится пустое место либо квадрат. Кроме кириллицы проверяйте знак валюты, специальные символы, длинное тире и редкие обозначения. Наличие символа в браузерном интерфейсе ничего не говорит о шрифте внутри PDF.
На клиенте подключается VFS с файлами Roboto; на сервере — конкретные TTF из пакета pdfmake. Настроены обычное, жирное, курсивное и жирное курсивное начертания. Системная установка шрифтов не требуется. При замене семейства нужно зарегистрировать все используемые варианты и пересмотреть переносы, потому что ширина букв изменится.
Roboto распространяется по Apache-2.0; текст лицензии включён в архив и публичный LICENSES.txt. Не переносите корпоративный шрифт в браузерный VFS без права на такое распространение: посетитель сможет получить его вместе с bundle. Подключение и структура VFS описаны в документации пользовательских шрифтов.
Фрагмент src/node-generator.mjs
import pdfmake from 'pdfmake';
import fonts from 'pdfmake/fonts/Roboto.js';
import { makeDefinition } from './definition.mjs';
import { resolve } from 'node:path';
pdfmake.addFonts(fonts);
// Templates need no remote resources. Visitors cannot supply raw document definitions.
pdfmake.setUrlAccessPolicy(()=>false);
const fontPaths=new Set(Object.values(fonts.Roboto).map(p=>resolve(p)));
pdfmake.setLocalAccessPolicy(path=>fontPaths.has(resolve(path)));
export async function generatePDF(id,data,options={}){const {definition,manifest}=makeDefinition(id,data,options);const bytes=await pdfmake.createPdf(definition).getBuffer();return{bytes,manifest};}
Размеры, переносы и читаемость печатного листа
Размеры страниц, отступы и шрифты в pdfmake задаются в пунктах, а не в CSS-пикселях. Для A4 важно оставить место под колонтитулы и основной текст. Массив margin задаёт отступы слева, сверху, справа и снизу. В таблице отдельно действуют внутренние отступы ячеек, поэтому её фактическая ширина зависит не только от widths.
Ширины колонок могут быть фиксированными, автоматическими или распределять оставшееся место. Для суммы и количества удобно выделить предсказуемую ширину, а наименование оставить гибким. Выравнивание чисел по правому краю облегчает сравнение значений. Заголовок таблицы и чередующийся фон помогают удерживать строку при чтении, но цвет не должен быть единственным носителем смысла.
Проверяйте крайние данные: длинное название клиента, большое число, последний ряд и пустые дополнительные поля. Нельзя гарантировать хороший вид любого текста одной настройкой fontSize. Иногда требуется другой шаблон или дополнительная страница. Сначала сохраняйте читаемость и правильные переносы, затем сокращайте объём и плотность в соответствии с задачей документа.
Браузер: получить байты, скачать и открыть результат
В браузере createPdf получает определение документа, а getBuffer возвращает готовые байты асинхронно. Из них создаётся Blob с типом application/pdf и временный Object URL. Один результат можно передать просмотрщику, скачать или открыть в новой вкладке. Мастерская не запускает генерацию повторно отдельно для каждой кнопки.
Временные URL нужно освобождать после использования или замены результата. Иначе последовательная генерация большого количества документов будет удерживать память. При редактировании мы сразу отключаем скачивание прошлого файла и уничтожаем связанный просмотр. Счётчик версии результата защищает от ситуации, когда старая асинхронная операция заканчивается после изменения данных.
Для прямого открытия окна действуют ограничения браузера на всплывающие окна. Поэтому здесь пользователь открывает уже созданный файл отдельной кнопкой. На телефоне способ открытия зависит от браузера и установленного просмотрщика; скачивание остаётся запасным вариантом. Различия между download, open, print, getBuffer и getBlob описаны в официальном перечне методов.
const bytes = await pdfmake.createPdf(definition).getBuffer();
const blob = new Blob([bytes], { type: 'application/pdf' });
const url = URL.createObjectURL(blob);
// После использования или замены результата:
URL.revokeObjectURL(url);
Предпросмотр: PDF.js рисует именно созданный файл
Превью мастерской не имитирует документ HTML-блоками. PDF.js получает те же байты, которые скачиваются кнопкой, читает число страниц и рисует выбранную страницу на canvas. На странице сохраняются исходные пропорции листа; плотность пикселей учитывает экран устройства. Переходы назад и вперёд работают с реальным документом.
Worker размещён локально рядом с app.js. Его путь определяется относительно import.meta.url, поэтому мастерскую можно разместить во вложенном каталоге WordPress. Публичный worker называется pdf.worker.min.js и должен отдаваться с корректным JavaScript MIME-типом. Если вместо worker пришла HTML-страница ошибки или запрещён модуль, PDF может создаться успешно, но просмотр не запустится.
Отдельный canvas не заменяет полноценный доступный просмотрщик с выделением текста и поиском. Поэтому рядом оставлены открытие исходного файла и скачивание. При изменении ширины экрана текущая страница перерисовывается, а при смене документа старая задача прекращается. Такой интерфейс даёт понятную обратную связь, не делая успешность генерации зависимой от встроенного просмотра.
pdfjs.GlobalWorkerOptions.workerSrc =
new URL('./pdf.worker.min.js', import.meta.url).href;
const task = pdfjs.getDocument({ data: new Uint8Array(bytes), isEvalSupported: false });
const pdf = await task.promise;
console.log('Страниц:', pdf.numPages);
Node.js CLI: новый файл и понятный код завершения
CLI полезен для регулярных отчётов, фоновых заданий и простого первого внедрения. Он читает файл JSON, проверяет размер, разбирает данные и вызывает тот же генератор. На выходе получает PDF по указанному пути. Все настройки оформления остаются в проекте, поэтому сценарий можно повторить без запуска браузера и действий мышью.
Запись выполняется с флагом wx: существующий файл не заменяется. Также отклоняется совпадение входного и выходного пути. Для производственной системы формируйте имя по идентификатору задания и сохраняйте рядом версию шаблона либо связь с исходными данными. Тогда можно понять, из какого набора получился конкретный документ.
Не собирайте shell-команду из свободного пользовательского текста. Пути и идентификатор сценария определяет доверенная логика, а данные передаются отдельным файлом или через внутренний API. При ошибке вызывающая система должна прекратить отправку результата и показать статус задачи. Ненулевой код завершения важен не меньше, чем красивый PDF при успешном запуске.
Фрагмент tools/generate.mjs
import { readFile, writeFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { parseInput } from '../src/definition.mjs';
import { generatePDF } from '../src/node-generator.mjs';
try{const [id,input,output]=process.argv.slice(2);if(!id||!input||!output)throw Error('node tools/generate.mjs invoice fixtures/invoice.json result.pdf');if(resolve(input)===resolve(output))throw Error('Входной и выходной пути должны различаться.');const raw=await readFile(input);if(raw.length>32768)throw Error('Лимит JSON: 32 KiB.');const {bytes,manifest}=await generatePDF(id,parseInput(raw.toString('utf8')));await writeFile(output,bytes,{flag:'wx'});console.log(JSON.stringify({status:'PASS',output,bytes:bytes.length,id:manifest.id}));}catch(e){console.error(e.message);process.exitCode=1;}
Внутренний API: JSON на входе, application/pdf в ответе
В проекте есть POST /invoice для серверного расчёта. Обработчик принимает application/json, ограничивает тело 32 KiB, проверяет структуру и возвращает PDF с корректными Content-Type и Content-Disposition. Ответ помечен no-store. Ошибочные данные дают 422, слишком большой запрос — 413, неподходящий тип — 415, неизвестный маршрут — 404.
Процесс слушает только 127.0.0.1 и принимает не больше двух операций одновременно; следующий запрос получает 429 с Retry-After. Это небольшая защита внутреннего примера, а не полноценная система управления нагрузкой. Для внешнего доступа основное приложение должно проверить сессию, права на проект и достоверность цен, затем вызвать генератор от своего имени.
Браузерная мастерская этот endpoint не использует: она создаёт PDF локально. API нужен для сценариев, где данные доступны только на сервере или документ должен формироваться независимо от открытой вкладки. Например, PHP-приложение может обратиться к этому внутреннему сервису после проверки заказа, не подменяя серверный расчёт суммой, присланной посетителем.
Фрагмент README.md
curl --fail-with-body -H 'Content-Type: application/json' --data-binary @fixtures/invoice.json http://127.0.0.1:8576/invoice -o /tmp/api-invoice.pdf
Фрагмент README.md
curl.exe --fail-with-body -H "Content-Type: application/json" --data-binary "@fixtures/invoice.json" http://127.0.0.1:8576/invoice -o "$env:TEMP\api-invoice.pdf"
Linux/VPS: отдельный пользователь и служба systemd
Для постоянного внутреннего API установите проект в отдельный каталог и создайте системного пользователя. Production-зависимости устанавливаются через npm ci --omit=dev --ignore-scripts. Затем задайте unit с абсолютным путём Node.js. Если Node установлен через личный менеджер версий, /usr/bin/node может отсутствовать: сначала проверьте command -v node и права службы на чтение проекта.
Пример unit включает перезапуск при ошибке, запрет получения новых привилегий, отдельный временный каталог и ограничение записи в систему. MemoryMax показывает место для эксплуатационного лимита; 512M не заявляются как универсальная потребность pdfmake. Выберите значение после измерений своих шаблонов, количества параллельных задач и изображений.
После настройки проверьте статус, journalctl и один запрос с учебными данными. Не открывайте порт 8576 наружу без уровня авторизации. Инструкция в архиве описывает внедрение, но не означает, что такой сервис уже запущен на вашем сервере. Для обновления сохраняйте предыдущий релиз и перезапускайте только принадлежащую этому проекту службу.
Фрагмент VPS.md
[Unit]
Description=Internal pdfmake invoice generator
After=network.target
[Service]
Type=simple
User=pdfmake
Group=pdfmake
WorkingDirectory=/opt/pdfmake-workshop
ExecStart=/usr/bin/node /opt/pdfmake-workshop/tools/api.mjs
Environment=NODE_ENV=production
Environment=PORT=8576
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
MemoryMax=512M
[Install]
WantedBy=multi-user.target
Фрагмент VPS.md
sudo systemctl daemon-reload
sudo systemctl enable --now pdfmake-workshop
sudo systemctl status pdfmake-workshop --no-pager
sudo journalctl -u pdfmake-workshop -n 50 --no-pager
curl --fail-with-body -H 'Content-Type: application/json' --data-binary @fixtures/invoice.json http://127.0.0.1:8576/invoice -o /tmp/invoice-vps.pdf
Разместить мастерскую как статику через Nginx
Если пользователь создаёт документ в браузере, постоянный Node-процесс на VPS не требуется. Разместите готовую public и раздавайте её Nginx или Caddy. Сохраните рядом исходный архив и относительную структуру ссылок. В публичную папку не нужно переносить рабочие JSON клиентов, .env, логи, node_modules и приватные PDF.
Фрагмент ниже размещается внутри уже настроенного HTTPS server. Для module worker проверьте MIME-таблицу сервера: файл pdf.worker.min.js должен обслуживаться как JavaScript. В разных установках nginx mime.types может отличаться. После изменений сначала выполните nginx -t, затем reload по правилам своего сервера и проверьте страницу с отключённым кэшем.
Не скрывайте ошибку отсутствующего файла универсальной выдачей index.html для любого пути: worker и sources.json должны получать свои данные, а не HTML. Полезные настройки, проверка конфигурации и диагностика ответов разобраны в практическом материале про Nginx. Для мастерской особенно важны правильные типы файлов и работа во вложенном URL.
Фрагмент VPS.md
location /pdfmake-demo/ {
alias /opt/pdfmake-workshop/public/;
index index.html;
}
Docker: воспроизводимый запуск генератора в Linux
Dockerfile закрепляет Linux-образ Node.js по версии и digest, устанавливает зависимости по lock-файлу и запускает CLI от пользователя node. В рабочем контейнере нет графического браузера: PDF создаёт библиотека. Готовая команда пишет документ во временный /tmp; после завершения одноразового контейнера этот результат удалится вместе с ним.
Для сохранения подключите отдельный каталог вывода и передайте новый путь в нём. На Linux согласуйте права каталога с пользователем контейнера. Не открывайте запись во всю файловую систему ради одного PDF. В примере генерации отключена сеть, корневая файловая система доступна только для чтения, а /tmp выделен отдельно.
Сборка зависимостей требует сети, сама генерация по локальным данным и Roboto — нет. На Windows Docker Desktop даёт Linux-среду и дополняет нативную проверку Node.js. Если приложение состоит из PHP, базы, очереди и генератора, следующая ступень — стенд Docker Compose. Начинать полезнее с одного проверенного CLI и конкретного документа.
Фрагмент Dockerfile
FROM node:24.22.3-bookworm-slim@sha256:dc26ae92c9fb15cf6b1d63e20f0944b2efe0f115b20e00be48fb23fceb061c54
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund
COPY src ./src
COPY tools ./tools
COPY fixtures ./fixtures
USER node
CMD ["node", "tools/generate.mjs", "invoice", "fixtures/invoice.json", "/tmp/invoice.pdf"]
Фрагмент VPS.md
docker build -t aen-pdfmake-local .
docker run --rm --network none --read-only --tmpfs /tmp:rw,nosuid,size=32m aen-pdfmake-local
Массовые документы: очередь, память и повторный запуск
Для десятков тяжёлых документов не стоит держать пользовательский HTTP-запрос открытым до конца. Создайте задание, сохраните проверенные параметры и покажите статус. Worker формирует PDF, записывает результат и сообщает готовность. Пользователь получает защищённую ссылку, а сервер контролирует число параллельных задач и срок хранения файлов.
Измеряйте отдельно выборку данных, подготовку изображений, layout и запись результата. Ограничение размера JSON не гарантирует фиксированный расход памяти: длинные таблицы и изображения ведут себя по-разному. Для отмены нужен собственный жизненный цикл задания. Закрытие вкладки не означает автоматическую остановку уже работающего серверного процесса.
Повторный запуск не должен отправлять клиенту два одинаковых письма. Свяжите документ с идентификатором задания и версией данных, отделите генерацию от доставки, а успешный результат храните достаточно долго для повторного скачивания. Практика очередей, повторов и прогресса приведена в материале BullMQ. Сам pdfmake не управляет ни очередью, ни доступом к файлам.
Проверка PDF: структура, текст и реальный внешний вид
Автоматические тесты создают все девять PDF, открывают их как документы, проверяют количество страниц, формат альбомного листа и итог расчёта. Отдельно вызываются CLI и HTTP API, проверяются ошибки, запрет перезаписи и сериализуемость манифеста. Команда capture сохраняет реальные результаты с SHA-256, размерами и числом страниц, а не только сообщение об успешном выполнении.
Проект проверен на Windows с Node.js 24.19.0 и в Linux-контейнере с Node.js 24.22.3. Стандартные сценарии дали девять документов и пятнадцать страниц: пять у реестра, три у отчёта, по одной у остальных. Все страницы отрисованы Poppler и просмотрены: проверены кириллица, суммы, QR, таблицы, колонтитулы и последняя строка реестра.
После изменения данных или шрифтов повторяйте визуальную проверку. Успешный парсинг PDF не обнаружит некрасивый перенос или недостаточный отступ. Хеши помогают подтвердить, какой файл проверялся, но разные запуски могут отличаться метаданными времени. Для сравнения смысла дополнительно проверяйте текст, число строк и значения, а не требуйте побайтового совпадения независимо созданных PDF.
Фрагмент README.md
npm test
npm run capture
Ограничения: что этот генератор не обещает
Этот проект создаёт новые PDF по собственным шаблонам. Он не предназначен для открытия чужого документа и произвольного редактирования его текста. Существующий PDF, скан и форма с полями — другие задачи, для которых нужны подходящие инструменты. Также здесь нет конвертации произвольного HTML и автоматического переноса всей CSS-вёрстки сайта.
Наличие шрифтов и текстового слоя не означает сертифицированное соответствие PDF/A или PDF/UA. Электронная подпись, обязательные реквизиты и требования архивного хранения тоже не возникают от вызова createPdf. Если такие свойства нужны процессу, определите точные требования, используйте подходящий этап проверки и не называйте обычный файл соответствующим стандарту без подтверждения.
Демонстрационные названия, цены и статусы не являются реальными клиентскими данными. Перед внедрением замените их своим контрактом, правилами доступа и проверенными источниками. Пользователь должен понимать, какой период отражает документ, кем он сформирован и где уточнить вопрос. Хорошая автоматизация делает происхождение результата прозрачным и воспроизводимым.
Исходники, лицензии и первый шаг в своём проекте
В ZIP находятся src, готовая public, девять JSON-наборов fixtures, инструменты сборки и запуска, тесты, Dockerfile, lock-файл, README и VPS.md. Встроенный просмотр исходников показывает точные файлы проекта: можно изучить генератор, скопировать фрагмент или скачать отдельный файл. Лицензии библиотек и шрифтов собраны рядом с мастерской.
Выберите один документ, который сейчас готовится вручную. Опишите поля и единицы, получите реальный пример данных, определите шаблон и сравните PDF с ожиданиями получателя. Затем добавьте крайние случаи и автоматические проверки. Только после этого подключайте массовую генерацию, рассылку или кнопку в кабинете: небольшой проверенный сценарий проще поддерживать.
Первоисточники для продолжения: документация pdfmake 0.3, репозиторий pdfmake и PDF.js. Проверяйте примеры именно своей ветки API. Исходники мастерской можно использовать как основу, сохраняя лицензии и адаптируя контракт под смысл данных вашего приложения.


