docx→PDF конвертер на docx4j + FOP (без LibreOffice/Aspose)

- wordpdf-core: WordPdfConverter, встроенные TTF-шрифты (Carlito/Caladea/
  Arimo/Tinos/Cousine/DejaVu), BundledFontMapper с фолбэком в DejaVu
- нормализация w:val on/off (regular-раны не рендерятся жирным курсивом)
- символы U+2000–U+2EFF (em-dash) встраиваются через DejaVu, а не
  системным неembedded-шрифтом
- wordpdf-cli: fat-jar CLI (один/несколько docx, явный выходной файл)
- тесты (docx4j/FOP/PDFBox/POI), README
This commit is contained in:
Pjandro
2026-09-23 17:54:39 +00:00
commit 76c251ddd9
53 changed files with 2163 additions and 0 deletions
+125
View File
@@ -0,0 +1,125 @@
# 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`) и CLI (`wordpdf-cli`, fat-jar).
## Структура
```
java-word-pdf/
├── wordpdf-core/ библиотека: конвертер, шрифты, маппинг
└── wordpdf-cli/ командная строка (fat-jar через maven-shade)
```
Ключевые классы (`wordpdf-core`):
| Класс | Назначение |
|---|---|
| `ru.pjandro.wordpdf.WordPdfConverter` | публичный API: `convert(Path)` / `convert(Path, Path)` |
| `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 17** и **Maven**.
```bash
mvn clean verify # сборка всех модулей + тесты
mvn -pl wordpdf-cli package # только fat-jar CLI
```
Результат: `wordpdf-cli/target/wordpdf-cli-<версия>.jar` (fat-jar, все
зависимости внутри).
## Использование
### CLI
```bash
java -jar wordpdf-cli-1.0.0.jar in.docx # рядом создаётся in.pdf
java -jar wordpdf-cli-1.0.0.jar in.docx out.pdf # в указанный файл
java -jar wordpdf-cli-1.0.0.jar a.docx b.docx # пакетно: каждый -> свой .pdf
```
Коды возврата: `0` — успех, `1` — ошибка использования, `2` — не удалось
конвертировать хотя бы один файл.
### Библиотека
```java
import ru.pjandro.wordpdf.WordPdfConverter;
import java.nio.file.Path;
Path pdf = WordPdfConverter.convert(Path.of("doc.docx")); // doc.pdf рядом
WordPdfConverter.convert(Path.of("doc.docx"), Path.of("out.pdf")); // явный выход
```
Ошибки валидации (не `.docx`, файл не найден) бросают `ConversionException`.
## Шрифты
В `wordpdf-core/src/main/resources/fonts/` упакованы 28 TTF (по 4 начертания
на семейство):
| Семейство | Аналог MS-шрифта |
|---|---|
| Carlito | Calibri |
| Caladea | Cambria |
| Arimo | Arial |
| Tinos | Times New Roman |
| Cousine | Courier New |
| DejaVu Sans / DejaVu Serif | fallback |
`BundledFontMapper` подставляет метрически совместимые аналоги при конвертации
(`Calibri → Carlito` и т.д.). Нераспознанные шрифты и символы, не найденные в
шрифте ранa (em-dash «—», кавычки, U+2000–U+2EFF), падают в **DejaVu Sans**
(гарантированная кириллица). Все шрифты встраиваются в 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`).
## Как это работает
```
docx ──> (нормализация w:val on/off) ──> docx4j (WordprocessingMLPackage)
──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
```
1. Байты `.docx` нормализуются (`DocxOnOffNormalizer`): docx4j 11.x теряет
атрибуты `w:val="off"/"on"` при JAXB-разборе, из-за чего regular-раны
могли рендериться жирным курсивом.
2. Документ загружается в `WordprocessingMLPackage`, привязывается
`BundledFontMapper`.
3. Экспорт в XSL-FO (XSLT-проход), затем `Apache FOP` рендерит PDF, встраивая
используемые подмножества шрифтов.
## Ограничения
- Это **не** pixel-perfect рендер Word: раскладка, поля и некоторые эффекты
приближённые (ограничения FOP/docx4j, а не «мы что-то упустили»).
- Символы U+2000–U+2EFF (em-dash и т.п.) рендерятся fallback-шрифтом DejaVu,
а не шрифтом самого ранa.
- Поддержка таблиц/изображений — базовая (через docx4j/FOP).
## Тесты
Тесты используют готовые `.docx` из `wordpdf-core/src/test/resources/samples/`
(генерируются POI) и проверяют извлечённый PDFBox'ом текст и встраивание
шрифтов. Запуск: `mvn test`.