Files
java-word-pdf/README.md
T
Pjandro 76c251ddd9 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
2026-09-23 17:54:54 +00:00

126 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.