Word в strict пишет проценты строками (a:shade val="50%", w14:fillToRect w14:t="130%") и w:start/w:end вместо w:left/w:right — JAXB-разбор docx4j падает на NumberFormatException (в mc-preprocessor.xslt ветка % закомментирована, start/end не маппятся). Новый байтовый StrictOoxmlNormalizer первым в цепочке нормализаторов приводит strict к transitional-байту; mc-preprocessor доделывает namespaces и pt. - StrictOoxmlNormalizer: %-атрибуты a:/w14:fillToRect -> тысячные (x1000), текст wp14:pctWidth/pctHeight, элементы/атрибуты w:start/w:end -> w:left/w:right (кроме w:lvl/w:start в numbering.xml), значения start/end у w:jc/w:tab; transitional-документы — no-op (assertSame) - WordPdfValidator: lightweight-путь читает атрибуты по локальному имени (attrLocal) — иначе в strict не засчитываются w:br type="page"; pageCountOf при провале JAXB-разбора бросает ConversionException вместо NPE - тесты: StrictOoxmlNormalizerTest (13), регрессии strictOoxml_convertsNotRejected (in-memory strict-zip), pageCount_strictBreaksCountedLightweight; AGENTS.md обновлён Реальный develop/openxml.docx: 11 страниц как в эталоне Word, диаграммы и SmartArt рендерятся. mvn clean verify: core 104 + app 20, BUILD SUCCESS.
java-word-pdf
Конвертация docx → PDF на чистом Java: docx4j + Apache FOP, без
LibreOffice/Aspose. Шрифты упакованы в jar — конвертация не зависит от
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
Возможности
- Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества).
- Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются в docx4j/FOP.
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами (см. «Шрифты» ниже).
- Клиентская библиотека (
wordpdf-core), REST API (wordpdf-app, Spring Boot) и веб-интерфейс (wordpdf-web, React SPA).
Структура
java-word-pdf/
├── wordpdf-core/ библиотека: конвертер, шрифты, маппинг
├── wordpdf-app/ REST API: POST /api/v1/convert (Spring Boot, Swagger UI)
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
Ключевые классы (wordpdf-core):
| Класс | Назначение |
|---|---|
ru.pjandro.wordpdf.WordPdfConverter |
публичный API: convert(byte[], String) — байты на входе, байты PDF на выходе |
ru.pjandro.wordpdf.ConversionException |
исключение конвертации |
ru.pjandro.wordpdf.fonts.BundledFonts |
выгрузка TTF из jar и регистрация в docx4j |
ru.pjandro.wordpdf.fonts.BundledFontMapper |
маппинг имён шрифтов документа → TTF |
ru.pjandro.wordpdf.internal.DocxOnOffNormalizer |
нормализация w:val="off"/"on" перед загрузкой |
ru.pjandro.wordpdf.internal.FopFallbackFonts |
декларация fallback-семейства в FOP-конфиге |
Сборка
Требуется Java 21 и Maven (бэкенд), Node.js ≥ 20.19 (веб-интерфейс).
mvn clean verify # все модули + тесты
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
Результат: wordpdf-app/target/wordpdf-app-<версия>.jar (все зависимости
внутри). Для фронтенда — отдельный деп: npm install && npm run build
в wordpdf-web/ (результат — статика в wordpdf-web/dist/).
Использование
REST API
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
POST /api/v1/convert принимает multipart-поле file (.docx) и синхронно
возвращает байты PDF (application/pdf, attachment).
| Код | Смысл |
|---|---|
| 200 | PDF в теле ответа |
| 400 | некорректный вход: не .docx / пустой / не zip / > 5 МБ / > 100 страниц |
| 413 | тело запроса больше контейнерного лимита multipart (6 МБ) |
| 503 | очередь конвертации занята — повторить позже |
| 504 | конвертация дольше таймаута (wordpdf.convert-timeout, по умолчанию 2m) |
Ошибки — JSON {"error": "..."}. Интерактивная документация:
Swagger UI — /swagger-ui.html, OpenAPI — /v3/api-docs.
Библиотека
import ru.pjandro.wordpdf.WordPdfConverter;
import java.nio.file.Files;
import java.nio.file.Path;
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
byte[] pdf = WordPdfConverter.convert(docx, "doc"); // заголовок PDF
Files.write(Path.of("out.pdf"), pdf);
Ошибки валидации (не .docx по содержимому, размер больше 5 МБ, страниц
больше ста) бросают ConversionException. Работа с файлами — забота
вызывающего: ядро пути не принимает.
Веб-интерфейс и Docker
docker compose up -d --build
Всё на http://localhost:8080/: nginx-контейнер web раздаёт SPA и проксирует
/api, /swagger-ui, /v3/api-docs на бэкенд (контейнер app наружу не
публикуется).
Dev-режим без Docker: бэкенд java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
(порт 8080) + npm run dev в wordpdf-web/ → http://localhost:5173
(Vite проксирует /api на 8080, CORS не нужен).
Шрифты
В wordpdf-core/src/main/resources/fonts/ упакованы 30 TTF: 7 текстовых
семейств по 4 начертания плюс два покрывающих шрифта (только regular):
| Семейство | Аналог MS-шрифта |
|---|---|
| Carlito | Calibri |
| Caladea | Cambria |
| Arimo | Arial |
| Tinos | Times New Roman |
| Cousine | Courier New |
| DejaVu Sans / DejaVu Serif | fallback |
| Noto Naskh Arabic | арабские дополнения U+07B1–U+08FF |
| Noto Sans Armenian | армянские знаки Unicode 16 |
BundledFontMapper подставляет метрически совместимые аналоги при конвертации
(Calibri → Carlito и т.д.). Нераспознанные шрифты и символы, не найденные в
шрифте ранa (em-dash «—», кавычки, U+2000–U+2EFF), падают в DejaVu Sans
(гарантированная кириллица). Знак, которого нет ни в шрифте ранa, ни там, куда
его отправил docx4j, ищет себе место сам: GlyphCoverageNormalizer режет такой
ран и для каждой части назначает покрывающее семейство — serif-раны в
DejaVu Serif, sans — в DejaVu Sans, экзотика — в Noto. Все шрифты
встраиваются в PDF как подмножества.
Лицензии шрифтов
- Arimo, Cousine, Tinos, Carlito, Caladea — SIL OFL 1.1
(см.
fonts/FONT-LICENSE.txt). - DejaVu Sans / DejaVu Serif — SIL OFL 1.1 / Bitstream Vera
(см.
fonts/DejaVu-LICENSE.txt). - Noto Naskh Arabic, Noto Sans Armenian — SIL OFL 1.1
(см.
fonts/Noto-LICENSE.txt).
Как это работает
docx ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
- Байты
.docxнормализуются, пока docx4j не увидел документ:DocxOnOffNormalizer(docx4j теряетw:val="off"/"on"при JAXB-разборе, из-за чего regular-раны могли рендериться жирным курсивом),SymbolFontNormalizer(маркеры из Symbol/Wingdings вместо «#») иFieldNormalizer(поляPAGE/NUMPAGESпересчитываются, а не печатают кэш из docx) иGlyphCoverageNormalizer(раны со знаками вне их шрифта). - Документ загружается в
WordprocessingMLPackage, привязываетсяBundledFontMapper, диаграммы и SmartArt предварительно растеризуются в PNG (DrawingPreRenderer). - Экспорт в XSL-FO (XSLT-проход +
WordLayoutFixups), затемApache FOPрендерит PDF, встраивая используемые подмножества шрифтов.
Ограничения
- Это не pixel-perfect рендер Word: раскладка, поля и некоторые эффекты приближённые (ограничения FOP/docx4j, а не «мы что-то упустили»).
- Символы U+2000–U+2EFF (em-dash и т.п.) берутся из шрифта ранa, если в нём есть глиф, иначе — из fallback-семейства DejaVu.
- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них
остаётся
.notdef. В эталонном экспорте Word (develop/, вне git) таких два — U+2188 (ↈ) и U+218A (↊), они есть только в GNU FreeSerif под GPL, а бандл держится целиком на SIL OFL. - Поддержка таблиц/изображений — базовая (через docx4j/FOP).
Тесты
Тесты используют готовые .docx из wordpdf-core/src/test/resources/samples/
(генерируются POI) и проверяют извлечённый PDFBox'ом текст и встраивание
шрифтов. Запуск: mvn test.
API (wordpdf-app) проверяется MockMvc-сквозняками (ConvertControllerTest)
на тех же фикстурах — ядро отдаёт их test-jar'ом.