# PptxGenJS — девять практических примеров

Авторская мастерская ae-nekrasov.ru. PptxGenJS 4.0.1, JSZip 3.10.1, Bootstrap 5.3.9; Node.js 24 LTS >=24.15.0. Все учебные данные вымышлены, геометрическая PNG-иллюстрация создана для проекта. Авторские файлы MIT, зависимости сохраняют собственные лицензии.

В lock-файле закреплён scoped override `pptxgenjs → image-size 2.1.0`: исходная транзитивная 1.2.1 попадает под GHSA-5p2g-fcmc-qvqq и GHSA-w3rx-r6r6-pgpr. Проверены все девять сценариев с override; `npm audit` на 17.11.2026 сообщает 0 уязвимостей. Наш генератор принимает только собственную встроенную PNG, а не произвольные удалённые изображения. При обновлении повторяйте тесты и аудит: этот результат относится к закреплённому набору, а не ко всем будущим версиям.

## Что можно попробовать

Титул; три KPI; смета с итогом; столбчатая диаграмма; план/факт линиями; встроенное изображение; мастер для этапов; длинная таблица с повтором заголовка; связанный отчёт из пяти слайдов. Поле JSON редактируется, палитра переключается. После изменений предыдущий результат очищается. PPTX создаётся настоящей библиотекой в браузере. Превью структуры не является рендером PowerPoint. Отдельно подписанные PNG — сохранённый реальный рендер стандартного отчёта LibreOffice; они не меняются при вводе.

## Windows / PowerShell

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

Готовая public уже входит в архив. Для её просмотра достаточно Node.js и `npm run serve`: зависимости нужны для пересборки и запуска генератора. Открытие HTML через file:// не подходит для загрузки sources.json.

```powershell
npm run generate -- report fixtures/report.json report.pptx
$env:PORT = '8566'
node tools/api.mjs
# В другой PowerShell:
curl.exe --fail-with-body -H 'Content-Type: application/json' --data-binary '@fixtures/report.json' http://127.0.0.1:8566/report --output api-report.pptx
```

CLI откажется перезаписывать существующий выходной файл. Выберите новое имя либо самостоятельно перенесите старый документ. Не указывайте путь входного JSON как выходной.

## Linux

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

Node24 можно установить официальным способом для вашей системы. Не запускайте генерацию от root. Для production используйте отдельного пользователя и совместимый LTS; `VPS.md` содержит пример каталога, systemd и отдачи статики. Node не требует установленного PowerPoint для генерации файла.

```bash
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
```

API — внутренний учебный endpoint. Он слушает loopback, принимает только отчёт по фиксированной схеме, не читает указанные посетителем пути и не скачивает URL. До доступа из интернета нужны аутентификация, авторизация конкретного отчёта, лимиты и журнал приложения. В HTML-мастерской этот API не используется: браузер создаёт файл локально.

## Проверки и воспроизведение

```bash
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
```

```powershell
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
```

Выход `out/report.pptx` также защищён от перезаписи. Docker Desktop на Windows выполняет Linux-контейнер: это отдельная среда от нативного Node Windows. Команда capture создаёт девять настоящих PPTX, проверяемое описание и хеши исходников. В PPTX входят текущие даты метаданных, поэтому байты ZIP двух запусков не обязаны совпадать. Сравнивайте слайды, таблицы, данные диаграмм и исходники.

## Проверка внешнего вида

Откройте результат в PowerPoint либо LibreOffice. Проверьте длинные русские названия, итоги, подписи диаграмм, повтор заголовка и последнюю строку длинного реестра. Статический образец public/examples/report.pptx и PNG public/proof созданы из стандартного примера9. Генерация не превращает произвольный существующий PPTX в редактируемый шаблон и не конвертирует его автоматически в PDF.

```bash
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
```

```powershell
$office = 'C:\Program Files\LibreOffice\program\soffice.exe'
& $office '-env:UserInstallation=file:///C:/Temp/aen-pptx-render' --headless --convert-to pdf --outdir rendered report.pptx
```

Это отдельный процесс просмотра/конверсии. Укажите собственный временный профиль LibreOffice; не закрывайте работающие пользовательские документы. В Linux без Arial возможна замена шрифта; установите разрешённый совместимый шрифт и повторите просмотр в конечном редакторе. Наличие XML внутри ZIP само по себе не доказывает хороший перенос текста.

## Структура

- src/cases.mjs — девять исходных наборов и объяснения.
- src/generator.mjs — общий валидатор, мастер, таблицы, графики и генерация.
- src/app.mjs — браузерный ввод, состояния, скачивание, просмотр кода.
- tools/generate.mjs — настоящий CLI; tools/api.mjs — внутренний API.
- tools/capture.mjs — реальные результаты и хеши; tests — проверки OOXML и CLI.
- tools/make-image.py — необязательное повторение собственной геометрической PNG; требует Pillow, для обычной работы не нужен.
- VPS.md — Linux-размещение. package-lock.json закрепляет зависимости.

## Ограничения

24KiB JSON, максимум8 категорий/3 ряда графика,8 строк обычной сметы,20–100 строк большого реестра. Эти границы защищают интерфейс и читаемость; для больших отчётов спроектируйте отдельную очередь и шаблон. Суммы в демонстрации округляются до сотых обычной арифметикой JavaScript; для бухгалтерских расчётов используйте целые минимальные денежные единицы или decimal.

Официальные источники: https://gitbrent.github.io/PptxGenJS/ и https://github.com/gitbrent/PptxGenJS .
