Перейти к содержимому
Поиск
Разработка

PptxGenJS: презентации из JavaScript — мастерская и 9 примеров

Создаём редактируемые презентации из данных: девять живых примеров, KPI, таблицы, графики, длинный реестр и полный отчёт. Браузер, Node.js, Windows/Linux и исходники.

Александр Некрасов
PptxGenJS: презентации из JavaScript — мастерская и 9 примеров — обложка

PptxGenJS: презентация из данных вашего приложения

Каждый месяц менеджер открывает прошлую презентацию, меняет название клиента, переносит числа из CRM, обновляет таблицу и перестраивает диаграмму. Работа кажется простой, пока в документе не остаётся старая сумма или название другой компании. PptxGenJS позволяет описать структуру презентации кодом и собирать новый PPTX из проверенного набора данных.

Результат можно открыть в PowerPoint или другом совместимом редакторе: текст остаётся текстом, таблица — таблицей, диаграмма содержит собственные данные. Это удобно для отчётов, коммерческих предложений, результатов обследования, учебных материалов и регулярных сводок. Разработчик определяет оформление один раз, а пользователь выбирает период, клиента и состав отчёта в привычном интерфейсе.

На этой странице находится настоящая мастерская с девятью сценариями: измените JSON, выберите палитру и скачайте созданную презентацию. В архиве есть общий генератор для браузера и Node.js, проверка входных данных, CLI, внутренний HTTP-обработчик, тесты и инструкция для Linux/VPS. Примеры показывают путь от одной подписи до связанного отчёта из пяти слайдов.

Где применять: от кнопки в CRM до регулярной рассылки

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

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

Сначала определите получателя и решение, которое он должен принять после просмотра. В отчёте руководителю важнее несколько сопоставимых показателей и понятный вывод; подробный реестр можно вынести в приложение. Возможность автоматически создать сто слайдов сама по себе не делает документ полезным. Хороший шаблон ограничивает объём, подписывает единицы измерения и оставляет место для объяснения результата.

Что создаёт библиотека и чем это отличается от скриншота

PptxGenJS формирует пакет Office Open XML: внутри PPTX находятся описания слайдов, отношений, изображений, тем и диаграмм. Такой файл можно передать без сервера, на котором он был создан. Для базовой генерации не требуется установленный PowerPoint: код работает в Node.js либо в браузере. Официальные варианты подключения приведены в руководстве по началу работы.

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

Библиотека не заменяет универсальный редактор существующих презентаций. Этот проект строит документ по собственному коду и не открывает произвольный корпоративный PPTX для автоматической замены полей. Также создание файла не означает его отрисовку в браузере или конвертацию в PDF. Генерация, просмотр, редактирование и экспорт в другой формат — отдельные этапы.

Версии, lock-файл и воспроизводимая установка

На 17 ноября 2026 года проект подготовлен на PptxGenJS 4.0.1, JSZip 3.10.1 и Bootstrap 5.3.9. Сборку браузерного файла выполняет esbuild 0.28.2. Используется Node.js 24 LTS не ниже 24.15.0. Точные зависимости сохранены в package-lock.json; начинайте с npm ci, чтобы повторить проверенный набор, а не случайно получить другой результат после обновления пакетов.

В package.json есть узкое переопределение транзитивного image-size на 2.1.0. Исходная зависимость 1.2.1 попадала под опубликованные сообщения об ошибках разбора изображений; после изменения повторены генерация и тесты всех сценариев. На дату подготовки npm audit сообщил ноль уязвимостей для этого lock-файла. Это состояние конкретного набора, поэтому аудит стоит повторять при обновлениях.

Браузерная мастерская использует локально собранный JavaScript и локальный CSS. Во время генерации она не загружает библиотеку с CDN и не отправляет JSON на сервер. Отдельный запрос sources.json нужен только для показа исходников. Такая архитектура позволяет разместить готовую папку public на обычном статическом хостинге или внутри существующего сайта.

Фрагмент package.json

{
  "name": "aen-pptxgenjs-workshop",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT",
  "engines": {"node": ">=24.15.0"},
  "scripts": {"build": "node tools/build.mjs", "serve": "node tools/serve.mjs", "test": "node --test tests/*.test.mjs", "capture": "node tools/capture.mjs", "generate": "node tools/generate.mjs"},
  "dependencies": {"pptxgenjs": "4.0.1", "bootstrap": "5.3.9", "jszip": "3.10.1"},
  "devDependencies": {"esbuild": "0.28.2"},
  "overrides": {"pptxgenjs": {"image-size": "2.1.0"}}
}

Мини-мастерская: измените данные и получите настоящий PPTX

Выберите сценарий из списка. Под ним показано, где применяется такой документ и какое изменение стоит попробовать. В редакторе находятся исходные данные, а палитра меняет акцентный цвет. Нажмите «Собрать презентацию»: библиотека сформирует PPTX, после чего появятся число слайдов, размер файла, структура документа и кнопки скачивания.

Начните с готового примера, затем измените один показатель или название. После редактирования старый результат сбрасывается, поэтому прежний файл нельзя случайно скачать как новую версию. Для проверки ошибки задайте отрицательную цену либо удалите значение из одного ряда диаграммы. Мастерская объяснит, какое поле не подходит, и не выдаст невалидный документ за успешный результат.

Карточки структуры показывают состав презентации, но не воспроизводят расположение объектов PowerPoint. Ниже отдельно размещён реальный сохранённый рендер стандартного отчёта, полученный через LibreOffice. Он подписан как эталон и не меняется при редактировании JSON. Свой результат нужно скачать и открыть в целевом редакторе. На телефоне удобно пользоваться полноэкранной версией мастерской.

Windows: запуск и первый документ в PowerShell

Распакуйте архив в отдельный каталог и откройте PowerShell в этой папке. Проверьте версию Node.js, установите зависимости и выполните тесты. Команда build пересобирает браузерный код и просмотр исходников. После serve откройте адрес из консоли: приложение слушает только локальную машину, поэтому запуск не публикует мастерскую в интернете.

Готовая public уже находится в архиве. Если хочется только попробовать страницу без изменения кода, достаточно Node.js и команды npm run serve: простой сервер написан на стандартных модулях. Установка зависимостей потребуется для генерации через CLI, тестов и новой сборки. Двойной щелчок по index.html не заменяет HTTP-сервер, потому что просмотр исходников использует fetch.

Для остановки локального сервера нажмите Ctrl+C в его терминале. При занятом порте задайте другую переменную PORT и используйте новый адрес. Существующий процесс на выбранном порте может принадлежать другому проекту; менять его состояние ради этой мастерской не требуется. PowerPoint нужен для привычного редактирования результата, но не для самой сборки файла.

Фрагмент README.md

node --version
npm ci
npm test
npm run build
npm run serve
# Открыть http://127.0.0.1:8565/ ; остановить Ctrl+C

Linux: тот же генератор без переноса node_modules

На Linux запускаются те же исходники и те же JSON-наборы. Установите совместимый Node.js 24 LTS способом, принятым для вашей системы, затем выполните npm ci. Папку node_modules с Windows переносить не нужно: инструменты сборки могут иметь платформенные бинарные части. В отличие от неё, готовые HTML, CSS и браузерный JavaScript из public можно раздавать как обычную статику.

Команда generate принимает сценарий, входной JSON и новый путь PPTX. В примере создаётся полный отчёт. Успешное выполнение завершается кодом ноль и сообщает число слайдов и размер. Если выходной файл уже существует, генератор откажется его заменять: выберите другое имя либо осознанно сохраните предыдущую версию в другом месте.

На сервере используйте отдельного пользователя с минимальными правами. Данные клиентов и готовые приватные презентации храните вне открытого web-каталога. Оболочка запуска не должна принимать произвольный путь от посетителя сайта. Ниже разобран внутренний API с фиксированным сценарием и пример службы systemd, а для локального знакомства достаточно обычного терминала.

Фрагмент README.md

node --version
npm ci
npm test
npm run build
npm run generate -- report fixtures/report.json report.pptx
PORT=8565 npm run serve

Один контракт данных для браузера, CLI и API

В центре проекта находится validateInput: он принимает известный сценарий и обычный объект. Проверяются обязательные строки, их длина, допустимые числа, количество строк и соответствие рядов диаграммы списку категорий. Результатом становится новый нормализованный объект; исходный набор не изменяется. Это позволяет использовать одинаковые правила при клике в браузере и запуске на сервере.

JSON сам по себе не определяет бизнес-контракт. Строка «42» и число 42 — разные значения. В мастерской отрицательная цена, бесконечность и лишние категории отклоняются до сериализации. Пустой заголовок тоже не превращается в невидимый объект на слайде. Неизвестные поля не копируются в документ автоматически: генератор явно выбирает только нужные данные.

Ограничения здесь связаны с дизайном конкретных шаблонов: три KPI, до восьми строк небольшой сметы, до восьми категорий графика и до ста строк отдельного реестра. Это не пределы самой библиотеки. В своём сервисе согласуйте контракт с владельцем отчёта, а не расширяйте массивы бесконечно только потому, что JSON позволяет их сохранить.

Фрагмент src/generator.mjs

function number(value, name, max = 1e7) {
  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > max) throw Error(`${name}: нужно число от 0 до ${max}.`);
  return value;
}

Пример 1. Титульный слайд для клиента или проекта

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

В PptxGenJS координаты и размеры объектов задаются в дюймах. Для широкого формата используется LAYOUT_WIDE, а размер текста задаётся в пунктах. Поэтому переносить значения CSS px прямо в x, y, w и h нельзя. Удобнее завести сетку: общий отступ, ширина колонки, зона заголовка и безопасная область для содержимого.

Для реального коммерческого предложения добавьте дату формирования, версию расчёта и имя ответственного. Эти значения лучше получать из доверенных данных приложения. Если документ потом пересылают отдельно от CRM, читатель должен понимать, к какому проекту и периоду он относится. Титул решает задачу идентификации, а не просто занимает первый слайд красивой заставкой.

Фрагмент src/generator.mjs

function cover() {
    const s = slide(d.title, "cover");
    s.addShape(pptx.ShapeType.rect, { x: 0.55, y: 1.72, w: 0.13, h: 3.55, fill: { color: accent }, line: { color: accent } });
    s.addText(d.subtitle, { x: 1, y: 2, w: 10.7, h: 1.2, fontFace: FONT, fontSize: 25, color: "3F5F55", margin: 0 });
    s.addText(d.client, { x: 1, y: 4.5, w: 10.7, h: 0.75, fontFace: FONT, fontSize: 20, bold: true, color: accent, margin: 0 });
  }

Пример 2. Три KPI с понятными единицами измерения

Карточки показателей подходят для короткой сводки: сколько заявок поступило, сколько выполнено и каков средний срок. У каждого значения есть подпись и единица. В мастерской цифры берутся непосредственно из JSON; никаких заранее нарисованных картинок с числами нет. Фигуры и текст можно редактировать после открытия презентации.

Проверьте не только изменение числа, но и смысл показателя. Количество созданных заявок за месяц нельзя без пояснения сравнивать с количеством закрытых заявок из всех периодов. Если данные приходят из API, вычисляйте показатели на одном согласованном наборе и фиксируйте временную зону. Заголовок «Работа за месяц» сам по себе не задаёт фильтр источнику данных.

Для больших чисел полезно заранее выбрать формат: полное значение, тысячи или миллионы. В текущем примере показано исходное число, чтобы связь с JSON была очевидной. В своём шаблоне можно добавить форматирование через Intl.NumberFormat, но подпись должна соответствовать масштабу. Число 2,4 с единицей «дня» информативнее, чем такое же число без объяснения.

Фрагмент src/generator.mjs

function kpi() {
    const s = slide(id === "report" ? "Основные показатели" : d.title, "kpi");
    d.metrics.forEach((m, i) => {
      const x = 0.55 + i * 4.15;
      s.addShape(pptx.ShapeType.roundRect, { x, y: 2, w: 3.85, h: 3.2, rectRadius: 0.12, fill: { color: "E7EEE6" }, line: { color: "D3DFD6" } });
      s.addText(m.label, { x: x + 0.25, y: 2.35, w: 3.35, h: 0.75, fontFace: FONT, fontSize: 19, color: "34584D", margin: 0 });
      s.addText(String(m.value), { x: x + 0.25, y: 3.25, w: 3.35, h: 0.85, fontFace: FONT, fontSize: 40, bold: true, color: accent, margin: 0 });
      s.addText(m.unit, { x: x + 0.25, y: 4.4, w: 3.35, h: 0.45, fontFace: FONT, fontSize: 18, color: "34584D", margin: 0 });
    });
  }

Пример 3. Смета, строки работ и итоговая сумма

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

Здесь используется addTable, а не набор нарисованных вручную линий. У колонок заданы ширины: названию выделено больше места, числам — меньше. Небольшая смета ограничена восемью строками. Для длинного реестра существует отдельный сценарий с переносом по слайдам; уменьшать шрифт до нечитаемого размера ради одного экрана обычно неудобно для получателя.

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

Фрагмент src/generator.mjs

export function tableRows(data) {
  return [["Работа", "Кол-во", "Цена, ₽", "Сумма, ₽"], ...data.map((r) => [r.name, String(r.quantity), String(r.price), String(Math.round(r.quantity * r.price * 100) / 100)])];
}
export function total(data) {
  return Math.round(data.reduce((s, r) => s + r.quantity * r.price, 0) * 100) / 100;
}

Пример 4. Сравнение отделов столбчатой диаграммой

Четвёртый сценарий показывает выполненные заявки и текущую работу по направлениям. В JSON отдельно перечислены категории и числовые ряды. Библиотека создаёт настоящую диаграмму с вложенными данными, а не скриншот графика веб-страницы. Это полезно, когда получатель должен изменить цвет ряда, подписи или оформление уже после скачивания.

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

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

Фрагмент src/generator.mjs

function chart(type) {
    const s = slide(id === "report" ? "Динамика заявок" : d.title, "chart");
    s.addChart(type, d.series.map((s2) => ({ name: s2.name, labels: d.labels, values: s2.values })), { x: 0.6, y: 1.65, w: 12.1, h: 4.85, catAxisLabelFontSize: 13, valAxisLabelFontSize: 12, showLegend: true, legendPos: "b", legendFontSize: 12, showTitle: false, showValue: type === pptx.ChartType.bar, showMarker: true, markerSize: 6, showCatName: false, showBorder: false, chartColors: [accent, "CEAE4D", "91B8A8"], showLine: true, lineSize: 2, showShadow: false, catAxisLineColor: "C9D6CF", valAxisLineColor: "C9D6CF", valGridLine: { color: "E0E7DF", width: 0.5 }, lang: "ru-RU" });
  }

Пример 5. План и факт на временной шкале

Линейная диаграмма помогает увидеть динамику: выполняется ли план, где произошёл скачок и как изменился результат. В исходном наборе четыре месяца и два ряда. Измените один месяц так, чтобы факт оказался ниже плана, затем откройте созданный PPTX. Линия действительно строится по новым значениям, а подписи месяцев сохраняют порядок массива labels.

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

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

Фрагмент fixtures/line.json

{
  "title": "Выполнение плана",
  "labels": [
    "Июль",
    "Август",
    "Сентябрь",
    "Октябрь"
  ],
  "series": [
    {
      "name": "План",
      "values": [
        80,
        85,
        90,
        100
      ]
    },
    {
      "name": "Факт",
      "values": [
        75,
        91,
        88,
        112
      ]
    }
  ]
}

Пример 6. Изображение внутри презентации

В этом сценарии собственная PNG-схема встроена непосредственно в PPTX. После скачивания файл не зависит от доступности сайта с картинкой. Такая схема подходит для фотографии оборудования, иллюстрации процесса или снимка интерфейса, если изображение подготовлено заранее. В мастерской меняются заголовок и пояснение; произвольная загрузка изображений с внешних URL не включена.

Функция containBox рассчитывает вписывание с сохранением пропорций. Известные размеры нашей иллюстрации — 1200 на 360 пикселей. Изображение центрируется внутри выделенной области и не растягивается по двум осям независимо. Этот небольшой расчёт важен: искажённая фотография или схема выглядит неаккуратно даже при правильных числах в отчёте.

Если добавите пользовательские файлы, проверяйте формат, размер и права на использование. Для серверного скачивания внешних URL понадобится отдельная политика допустимых адресов и ограничений. Лучше передавать генератору уже проверенный ресурс. Особенности addImage описаны в официальной документации изображений; в нашем проекте путь от PNG до встроенного файла покрыт тестом.

Фрагмент src/generator.mjs

export function containBox(iw, ih, x, y, w, h) {
  const scale = Math.min(w / iw, h / ih);
  const width = iw * scale, height = ih * scale;
  return { x: x + (w - width) / 2, y: y + (h - height) / 2, w: width, h: height };
}

Пример 7. Мастер: единый вид серии слайдов

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

Измените названия этапов или добавьте ещё один объект steps. Генератор создаст соответствующее количество слайдов с общим оформлением. Верхняя зона отведена под название этапа, ниже находится имя проекта и пояснение. Текст ограничен по длине: мастер задаёт рамку дизайна, но не превращает любой объём содержания в аккуратный слайд автоматически.

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

Фрагмент src/generator.mjs

pptx.defineSlideMaster({ title: "AEN", margin: [0.5, 0.55, 1, 0.55], background: { color: "F8F7F0" }, objects: [
    { rect: { x: 0, y: 0, w: W, h: 0.12, fill: { color: accent }, line: { color: accent } } },
    { text: { text: "ae-nekrasov.ru · учебные данные", options: { x: 0.55, y: 7.03, w: 10, h: 0.2, fontFace: FONT, fontSize: 9, color: "61766F", margin: 0 } } }
  ], slideNumber: { x: 12.1, y: 7, w: 0.6, h: 0.25, color: "61766F", fontSize: 10, align: "right" } });

Пример 8. Длинная таблица и повтор заголовка

Реестр задач нельзя всегда уместить на один слайд. Восьмой пример создаёт от двадцати до ста строк и включает autoPage. Библиотека распределяет таблицу по нескольким слайдам, повторяя строку заголовков. Стандартный набор из 65 задач в закреплённой версии проекта создаёт пять слайдов; первая и последняя задача сохраняются в документе.

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

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

Фрагмент src/generator.mjs

if (id === "longtable") {
    d.rowCount = number(data.rowCount, "rowCount", 100);
    if (!Number.isInteger(d.rowCount) || d.rowCount < 20) throw Error("rowCount: целое число от 20 до 100.");
    d.prefix = text(data.prefix, "prefix", 45);
  }

Пример 9. Связанный отчёт из пяти слайдов

Последний сценарий объединяет предыдущие приёмы. Из одного объекта создаются титул, три показателя, смета, диаграмма и следующие действия. Это уже заготовка кнопки «Скачать отчёт» для личного кабинета. Пользователь может выбрать проект в приложении, а сервер подготовит соответствующий JSON и передаст его общему генератору.

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

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

Фрагмент src/generator.mjs

if (id === "report") d.next = text(data.next, "next", 400);
  if (!["cover", "kpi", "table", "bar", "line", "image", "master", "longtable", "report"].includes(id)) throw Error("Неизвестный пример.");
  return d;
}
export function tableRows(data) {
  return [["Работа", "Кол-во", "Цена, ₽", "Сумма, ₽"], ...data.map((r) => [r.name, String(r.quantity), String(r.price), String(Math.round(r.quantity * r.price * 100) / 100)])];
}
export function total(data) {
  return Math.round(data.reduce((s, r) => s + r.quantity * r.price, 0) * 100) / 100;
}
export function containBox(iw, ih, x, y, w, h) {
  const scale = Math.min(w / iw, h / ih);
  const width = iw * scale, height = ih * scale;
  return { x: x + (w - width) / 2, y: y + (h - height) / 2, w: width, h: height };
}
export function buildPresentation(id, input, { palette = "teal" } = {}) {
  const d = validateInput(id, input);
  if (!palettes[palette]) throw Error("Неизвестная палитра.");
  const accent = palettes[palette], pptx = new pptxgen();
  pptx.layout = "LAYOUT_WIDE";
  pptx.author = "ae-nekrasov.ru";
  pptx.subject = "Учебная мастерская PptxGenJS";
  pptx.title = d.title;
  pptx.company = "Авторская мастерская";
  pptx.lang = "ru-RU";
  pptx.theme = { headFontFace: FONT, bodyFontFace: FONT, lang: "ru-RU" };
  pptx.defineSlideMaster({ title: "AEN", margin: [0.5, 0.55, 1, 0.55], background: { color: "F8F7F0" }, objects: [
    { rect: { x: 0, y: 0, w: W, h: 0.12, fill: { color: accent }, line: { color: accent } } },
    { text: { text: "ae-nekrasov.ru · учебные данные", options: { x: 0.55, y: 7.03, w: 10, h: 0.2, fontFace: FONT, fontSize: 9, color: "61766F", margin: 0 } } }
  ], slideNumber: { x: 12.1, y: 7, w: 0.6, h: 0.25, color: "61766F", fontSize: 10, align: "right" } });
  const manifest = { id, title: d.title, library: LIBRARY_VERSION, palette, slides: [], data: d };
  function slide(title, kind) {
    const s = pptx.addSlide("AEN");
    s.addText(title, { x: 0.55, y: 0.5, w: 12.2, h: 0.8, fontFace: FONT, fontSize: title.length > 55 ? 26 : 30, bold: true, color: "173E37", margin: 0, breakLine: false });
    s.addNotes("Вымышленные данные. Создано библиотекой PptxGenJS.");
    manifest.slides.push({ title, kind });
    return s;
  }
  function cover() {
    const s = slide(d.title, "cover");
    s.addShape(pptx.ShapeType.rect, { x: 0.55, y: 1.72, w: 0.13, h: 3.55, fill: { color: accent }, line: { color: accent } });
    s.addText(d.subtitle, { x: 1, y: 2, w: 10.7, h: 1.2, fontFace: FONT, fontSize: 25, color: "3F5F55", margin: 0 });
    s.addText(d.client, { x: 1, y: 4.5, w: 10.7, h: 0.75, fontFace: FONT, fontSize: 20, bold: true, color: accent, margin: 0 });
  }
  function kpi() {
    const s = slide(id === "report" ? "Основные показатели" : d.title, "kpi");
    d.metrics.forEach((m, i) => {
      const x = 0.55 + i * 4.15;
      s.addShape(pptx.ShapeType.roundRect, { x, y: 2, w: 3.85, h: 3.2, rectRadius: 0.12, fill: { color: "E7EEE6" }, line: { color: "D3DFD6" } });
      s.addText(m.label, { x: x + 0.25, y: 2.35, w: 3.35, h: 0.75, fontFace: FONT, fontSize: 19, color: "34584D", margin: 0 });
      s.addText(String(m.value), { x: x + 0.25, y: 3.25, w: 3.35, h: 0.85, fontFace: FONT, fontSize: 40, bold: true, color: accent, margin: 0 });
      s.addText(m.unit, { x: x + 0.25, y: 4.4, w: 3.35, h: 0.45, fontFace: FONT, fontSize: 18, color: "34584D", margin: 0 });
    });
  }
  function table() {
    const s = slide(id === "report" ? "Стоимость работ" : d.title, "table");
    s.addTable(tableRows(d.rows), { x: 0.55, y: 1.65, w: 12.2, colW: [6.2, 1.5, 2.2, 2.3], rowH: 0.46, fontFace: FONT, fontSize: 15, color: "173E37", fill: "FFFFFF", border: { type: "solid", pt: 0.5, color: "D0DED3" }, margin: 7, bold: false, autoPage: false });
    s.addText(`Итого: ${total(d.rows).toLocaleString("ru-RU")} ₽`, { x: 6.3, y: 6.05, w: 6.45, h: 0.55, align: "right", fontFace: FONT, fontSize: 24, bold: true, color: accent, margin: 0 });
  }
  function chart(type) {
    const s = slide(id === "report" ? "Динамика заявок" : d.title, "chart");
    s.addChart(type, d.series.map((s2) => ({ name: s2.name, labels: d.labels, values: s2.values })), { x: 0.6, y: 1.65, w: 12.1, h: 4.85, catAxisLabelFontSize: 13, valAxisLabelFontSize: 12, showLegend: true, legendPos: "b", legendFontSize: 12, showTitle: false, showValue: type === pptx.ChartType.bar, showMarker: true, markerSize: 6, showCatName: false, showBorder: false, chartColors: [accent, "CEAE4D", "91B8A8"], showLine: true, lineSize: 2, showShadow: false, catAxisLineColor: "C9D6CF", valAxisLineColor: "C9D6CF", valGridLine: { color: "E0E7DF", width: 0.5 }, lang: "ru-RU" });
  }
  if (id === "cover") cover();
  if (id === "kpi") kpi();
  if (id === "table") table();
  if (id === "bar") chart(pptx.ChartType.bar);
  if (id === "line") chart(pptx.ChartType.line);
  if (id === "image") {
    const s = slide(d.title, "image");
    s.addImage({ data: diagramData, ...containBox(1200, 360, 0.8, 1.6, 11.75, 3.65), altText: "Собственная схема: входящая карточка, обработка и подтверждение" });
    s.addText(d.caption, { x: 0.8, y: 5.6, w: 11.75, h: 1, fontFace: FONT, fontSize: 19, color: "34584D", margin: 0 });
  }
  if (id === "master") d.steps.forEach((step, i) => {
    const s = slide(`${i + 1}. ${step.title}`, "master");
    s.addText(d.title, { x: 0.6, y: 1.65, w: 12, h: 0.6, fontFace: FONT, fontSize: 16, color: accent, margin: 0 });
    s.addText(step.text, { x: 0.6, y: 2.65, w: 11.9, h: 2.2, fontFace: FONT, fontSize: 27, color: "34584D", margin: 0 });
  });
  if (id === "longtable") {
    const s = slide(d.title, "longtable");
    const rows = [[{ text: "№", options: { bold: true } }, { text: "Задача", options: { bold: true } }, { text: "Статус", options: { bold: true } }], ...Array.from({ length: d.rowCount }, (_, i) => [String(i + 1), `${d.prefix} ${i + 1}`, i % 3 ? "Готово" : "В работе"])];
    s.addTable(rows, { x: 0.55, y: 1.65, w: 12.2, colW: [0.8, 8.2, 3.2], fontFace: FONT, fontSize: 14, border: { pt: 0.5, color: "D0DED3" }, fill: "FFFFFF", color: "173E37", margin: [0.08, 0.08, 0.08, 0.08], autoPage: true, autoPageRepeatHeader: true, autoPageHeaderRows: 1, autoPageSlideStartY: 0.7 });
  }
  if (id === "report") {
    cover();
    kpi();
    table();
    chart(pptx.ChartType.bar);
    const s = slide("Следующие шаги", "next");
    s.addText(d.next, { x: 0.6, y: 1.8, w: 12, h: 3.6, fontFace: FONT, fontSize: 26, color: "34584D", margin: 0 });
  }

Русский текст, длинные подписи и шрифты

Шрифт участвует в переносе строк. На одной машине Arial доступен, на другой редактор подставляет совместимую гарнитуру, и текст занимает немного другую ширину. Поэтому файл, который успешно открывается, ещё не обязательно выглядит одинаково во всех программах. Для публичного шаблона выбирайте разрешённый шрифт, проверяйте кириллицу и просматривайте результат там, где им будут пользоваться.

Заранее заведите несколько сложных входных наборов: длинное название компании, максимальный заголовок, большие числа, многострочная подпись и длинная последняя строка таблицы. Проверка только на словах «Тест» и «Клиент» пропускает большую часть проблем верстки. Ограничение длины снижает риск, но не заменяет визуальную оценку: одинаковое количество узких и широких букв занимает разное место.

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

Скачивание: готовность, ошибки и устаревший результат

Генерация асинхронна. Пока файл собирается, кнопка запуска отключена; после завершения доступны PPTX и JSON-описание. Изменение входа сбрасывает прежний результат. Дополнительный номер ревизии не позволяет завершившейся старой операции обновить экран, если пользователь успел выбрать другой пример. Этот приём полезен и для других экспортов в интерфейсе.

Объект Blob содержит реальные байты результата. Временная ссылка создаётся через URL.createObjectURL и затем освобождается. JSON-описание помогает проверить состав слайдов и исходные нормализованные данные; оно не является второй презентацией. В браузере файл формируется локально, поэтому содержимое редактора не отправляется внутреннему Node API из архива.

Отдельно обработана загрузка исходников. До получения sources.json кнопки копирования и сохранения неактивны. Если запрос не удался, остаётся понятное сообщение и ссылка на полный архив. Успех копирования подтверждается только после выполнения Clipboard API; при отказе браузера пользователь может выделить код или скачать выбранный файл. Интерфейс не должен молча обещать действие, которое не состоялось.

Фрагмент src/app.mjs

function invalidate() {
  revision++;
  result = null;
  $("download").disabled = $("download-json").disabled = true;
  $("slide-count").textContent = $("byte-count").textContent = "—";
  $("slides").replaceChildren();
  $("manifest").textContent = "Данные изменены. Соберите документ заново.";
}

Node.js CLI: презентация как часть рабочего процесса

Консольный инструмент подходит для сборки отчёта после выгрузки данных, ручного запуска администратором или шага CI. Он читает локальный JSON, вызывает тот же генератор и сохраняет новый PPTX. Благодаря общему модулю браузерная демонстрация и серверная реализация не расходятся в правилах сумм, названиях полей и структуре слайдов.

Запись использует flag wx: существующий файл не будет незаметно заменён. Также проверяется совпадение входного и выходного пути. Для регулярных запусков формируйте отдельное имя по идентификатору задания либо времени и храните связь с набором данных. Возможность повторить исходный отчёт важнее, чем привычка каждый раз писать в один report.pptx.

Ошибки чтения, разбора, проверки и записи завершают CLI ненулевым кодом. Это позволяет управляющему процессу не отправлять пользователю старый файл после неудачной сборки. При интеграции в PHP удобнее передавать работу отдельному сервису или очереди, чем собирать shell-команду из введённых посетителем строк. Пути и имя сценария должны задаваться доверенной логикой приложения.

Фрагмент tools/generate.mjs

import { readFile, writeFile } from "node:fs/promises";
import { resolve } from "node:path";
import { generateBytes } from "../src/generator.mjs";
try {
  const [id, input, output] = process.argv.slice(2);
  if (!id || !input || !output) throw Error("Использование: node tools/generate.mjs report fixtures/report.json result.pptx");
  if (resolve(input) === resolve(output)) throw Error("Выходной файл не должен совпадать с JSON.");
  const raw = await readFile(input);
  if (raw.length > 24 * 1024) throw Error("Лимит JSON: 24 KiB.");
  const { bytes, manifest } = await generateBytes(id, JSON.parse(raw.toString("utf8")));
  await writeFile(output, bytes, { flag: "wx" });
  console.log(JSON.stringify({ status: "PASS", output, slides: manifest.slideCount, bytes: bytes.length }));
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}

Внутренний HTTP API: файл в ответ на проверенный JSON

Архив содержит небольшой обработчик POST /report. Он принимает только фиксированный отчёт, проверяет размер тела и возвращает PPTX с правильным Content-Type и Content-Disposition. Ошибка данных даёт ответ 422, слишком большой запрос — 413. Ответ с документом помечен Cache-Control: no-store, чтобы промежуточные кэши не обращались с приватным отчётом как с общей статикой.

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

В учебной реализации одновременно принимаются две операции, следующая получает 429 и Retry-After. Это простая граница для небольшого процесса, а не полноценная очередь. Для долгих или массовых документов нужны отдельные задания, статус, лимит хранения и защищённое скачивание результата. HTML-мастерская этот endpoint не вызывает: её экспорт остаётся самостоятельным браузерным сценарием.

Фрагмент README.md

PORT=8566 node tools/api.mjs
# Во втором терминале:
curl --fail-with-body -H 'Content-Type: application/json' \
  --data-binary @fixtures/report.json http://127.0.0.1:8566/report -o api-report.pptx

Фрагмент tools/api.mjs

import { createServer } from "node:http";
import { generateBytes } from "../src/generator.mjs";
let active = 0;
const server = createServer(async (req, res) => {
  if (req.method !== "POST" || req.url !== "/report") {
    res.writeHead(404).end();
    return;
  }
  if (active >= 2) {
    res.writeHead(429, { "Retry-After": "2" }).end("Busy");
    return;
  }
  active++;
  try {
    const chunks = [];
    let length = 0;
    for await (const chunk of req) {
      length += chunk.length;
      if (length > 24 * 1024) {
        res.writeHead(413).end("Input too large");
        return;
      }
      chunks.push(chunk);
    }
    const data = JSON.parse(Buffer.concat(chunks).toString("utf8"));
    const { bytes } = await generateBytes("report", data);
    res.writeHead(200, { "Content-Type": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "Content-Disposition": 'attachment; filename="report.pptx"', "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" }).end(Buffer.from(bytes));
  } catch {
    res.writeHead(422, { "Content-Type": "text/plain; charset=utf-8" }).end("Invalid report data");
  } finally {
    active--;
  }
});
server.listen(Number(process.env.PORT || 8566), "127.0.0.1", () => console.log("LISTENING " + server.address().port));
process.on("SIGTERM", () => server.close());

Docker: повторяемая Linux-среда для генерации

Dockerfile закрепляет версию Node и digest образа, устанавливает зависимости из lock-файла, выполняет сборку и тесты. Рабочая команда создаёт стандартный отчёт в каталоге /out. После сборки контейнер использует пользователя node. Для результата подключается отдельная папка; все домашние каталоги и рабочие секреты ему не нужны.

На Windows Docker Desktop запускает Linux-контейнер, поэтому такая проверка дополняет нативный запуск Node. На Linux bind mount должен разрешать запись выбранному UID. Если каталог принадлежит другому пользователю, согласуйте владельца либо пользователя запуска; произвольное открытие прав на весь сервер не требуется. Существующий out/report.pptx останется защищён от перезаписи.

Установка зависимостей во время сборки требует сети, а генерация по локальному JSON и встроенной PNG не обращается к внешним API. Учитывайте это при настройке стенда. Команды для обеих оболочек находятся в README; если нужны несколько связанных сервисов, продолжите с практикой Docker Compose.

Фрагмент Dockerfile

FROM node:24.22.3-bookworm-slim@sha256:dc26ae92c9fb15cf6b1d63e20f0944b2efe0f115b20e00be48fb23fceb061c54
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts --no-audit --no-fund
COPY . .
RUN npm run build && npm test
USER node
CMD ["node","tools/generate.mjs","report","fixtures/report.json","/out/report.pptx"]

Фрагмент README.md

npm run capture
docker build -t aen-pptxgenjs-workshop .
mkdir -p out
docker run --rm --mount type=bind,src="$(pwd)/out",dst=/out aen-pptxgenjs-workshop

Фрагмент README.md

docker build -t aen-pptxgenjs-workshop .
New-Item -ItemType Directory -Force out | Out-Null
docker run --rm --mount "type=bind,src=$((Get-Location).Path)/out,dst=/out" aen-pptxgenjs-workshop

Linux/VPS: разместить браузерную мастерскую через Nginx

Если посетитель сам формирует презентацию в браузере, на VPS достаточно статических файлов. Соберите проект, разместите public и исходный ZIP с сохранением относительных ссылок. Node-процесс для этой страницы запускать не нужно: Nginx отдаёт HTML, JavaScript, CSS, картинки и JSON исходников, а вычисление происходит на устройстве пользователя.

Фрагмент ниже добавляется внутрь уже настроенного HTTPS server. Замените пути под свой каталог, проверьте nginx -t и только после успешной проверки выполните reload. У JavaScript должен быть корректный тип содержимого: HTML вместо app.js обычно означает ошибочный маршрут или правило перенаправления. Ссылка на ZIP должна возвращать архив, который можно реально скачать.

Не копируйте вместе с public весь рабочий каталог. Приватные отчёты, файлы окружения, служебные журналы и node_modules не относятся к открытому содержимому сайта. Если нужна серверная сборка, разместите её отдельно. Ежедневные настройки прокси и диагностика подробно разобраны в материале про Nginx.

Фрагмент VPS.md

location /pptx-lab/ {
    alias /var/www/pptx-lab/;
    index index.html;
    autoindex off;
    add_header X-Content-Type-Options nosniff;
}

Linux/VPS: генератор под systemd и отдельным пользователем

Для внутреннего API создайте системного пользователя и каталог приложения. Установите production-зависимости из lock-файла, затем настройте unit с абсолютным путём Node. Служба не получает интерактивный shell автоматически: если Node установлен через пользовательский менеджер версий, обычный путь /usr/bin/node может не подходить. Проверяйте command -v node в своей среде.

В примере unit ограничены права процесса и задан автоматический перезапуск при сбое. MemoryMax служит примером эксплуатационного лимита, который нужно подобрать по своим измерениям. Он не означает, что любая презентация обязательно уложится в 512 MiB. Изображения большого разрешения, сложные таблицы и параллельные задания заметно меняют расход памяти.

После systemd-analyze verify проверьте статус службы, журнал и один учебный запрос. Обновление размещайте в отдельном каталоге релиза, сохраняя возможность вернуться к предыдущему. Перезапускать нужно только собственный unit. Публикация мастерской на нашем сайте не означает, что этот пример systemd уже развёрнут на вашем VPS: это воспроизводимая инструкция для внедрения.

Фрагмент VPS.md

[Unit]
Description=Internal PPTX report generator
After=network.target

[Service]
Type=simple
User=pptx-report
Group=pptx-report
WorkingDirectory=/opt/pptx-report
Environment=NODE_ENV=production
Environment=PORT=8566
ExecStart=/usr/bin/node /opt/pptx-report/tools/api.mjs
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
MemoryMax=512M
TasksMax=64

[Install]
WantedBy=multi-user.target

Фрагмент VPS.md

sudo systemd-analyze verify /etc/systemd/system/pptx-report.service
sudo systemctl daemon-reload
sudo systemctl enable --now pptx-report
sudo systemctl status pptx-report --no-pager
sudo journalctl -u pptx-report -n 60 --no-pager
curl --fail-with-body -H 'Content-Type: application/json' --data-binary @fixtures/report.json http://127.0.0.1:8566/report -o result.pptx

Большие отчёты, очередь и стоимость генерации

Небольшой документ удобно собирать по клику. Для сотен клиентов или тяжёлых изображений лучше вынести работу из HTTP-запроса в очередь. Интерфейс создаёт задание, показывает состояние и выдаёт ссылку после завершения. Пользователь не держит вкладку открытой ради ответа, а сервер ограничивает число одновременно работающих генераторов.

Измеряйте не только время PptxGenJS, но и подготовку данных, загрузку изображений, сериализацию ZIP и сохранение файла. Рост количества слайдов не всегда линейно связан с размером результата. Проверка 24 KiB входного JSON защищает нашу мастерскую от чрезмерного ввода, однако не является универсальной оценкой памяти для любых изображений и шаблонов.

Отмена задания требует собственной модели. Закрытие вкладки не обязательно прерывает процесс на сервере, а уже начатая сериализация не получает магической отмены от кнопки интерфейса. Храните статус и проверяйте возможность остановки на границах этапов. Для фоновых заданий на Node.js пригодятся очереди, отдельные Worker-процессы и ограничение срока хранения сформированных документов.

Проверка PPTX: данные, структура и реальный внешний вид

В проекте двадцать автоматических тестов. Они действительно создают PPTX, открывают ZIP, проверяют XML слайдов, значения диаграмм, вложенную книгу данных, PNG, повтор заголовков и сохранность всех 65 строк. Отдельные проверки вызывают CLI и loopback API: валидный ответ содержит презентацию, неправильные и слишком большие данные отклоняются. Один факт наличия расширения .pptx здесь не считается проверкой.

Нативный Node.js 24.19.0 на Windows и Node.js 24.22.3 в Linux-контейнере выполняют одинаковые сценарии. Для визуальной проверки девять стандартных документов преобразованы LibreOffice 26.8.0.3 в PDF и изображения: всего девятнадцать слайдов. Просмотрены графики, кириллица, итог сметы, продолжения таблицы и последняя строка реестра. Образец отчёта и пять его изображений доступны в мастерской.

Эта проверка подтверждает указанные шаблоны и наборы. Она не доказывает одинаковый вид произвольного текста во всех версиях PowerPoint, LibreOffice и мобильных просмотрщиков. После изменения дизайна повторите реальные рендеры. Байты PPTX между запусками могут различаться из-за метаданных ZIP; для сравнения содержимого полезнее проверять значимые XML-части и исходные данные.

Фрагмент README.md

mkdir -p rendered
libreoffice -env:UserInstallation=file:///tmp/aen-pptx-render \
  --headless --convert-to pdf --outdir rendered report.pptx
pdftoppm -png -r 100 rendered/report.pdf rendered/report

Скачать проверенный пятистраничный образец PPTX

Исходники и следующий шаг для своего сервиса

В архиве находятся исходные наборы fixtures, общий генератор src/generator.mjs, браузерный интерфейс, CLI, внутренний API, Dockerfile, lock-файл, тесты и инструкция VPS.md. Готовая public позволяет открыть мастерскую без новой сборки, а reference содержит именно тот образец, из которого сделаны статические изображения. Авторская иллюстрация и тексты лицензий включены в проект.

Начните внедрение с одного отчёта и одного источника данных. Зафиксируйте поля, единицы, разрешения и несколько пограничных примеров, затем согласуйте результат с человеком, который будет его читать. После этого добавляйте новые виды слайдов и автоматический запуск. Такой порядок помогает улучшать полезность документа, сохраняя понятную связь между данными приложения и презентацией.

Основные первоисточники — сайт PptxGenJS, репозиторий и сохранение презентаций. Причина закрепления image-size описана в сообщении о JXL/HEIF и сообщении об ICNS. Проверяйте документацию выбранной версии вместе со своими файлами.