Files
java-word-pdf/README.md
T
Pjandro 0c10bae3cf docx4j 11.5.3 -> 17.3.0: формулы OMML, колонки и постобработка XSL-FO
17.x приносит WordLayoutFixups (постобработка DOM XSL-FO: columnBreaks,
lineBoxAttributes, stripHints и др.) и jeuclid-fop, поэтому начинают
работать две вещи, которых не было: формулы m:oMath (на стр. 4 эталона
формула молча исчезала) и w:cols/@w:num (две колонки на стр. 9-11).
Сходимость текста references/word.docx с экспортом Word 0,848 -> 0,981,
средний постраничный пиксельный diff 10,5% -> 7,4%.

Что пришлось починить по пути:

* docx4j навешивает на fo:inline fox:gsub-features, не объявляя префикс
  fox. FO становится некорректным XML, WordLayoutFixups не парсит его и
  молча отказывается от всех фикс, а оставленный хинт docx4j-baseline
  отвергает уже FOP. Отключаем генерацию через
  docx4j.convert.out.fo.gsubFeatures=false.

* FOP теперь форк org.docx4j:docx4j-fo-renderer*, и его
  META-INF/services/org.apache.fop.fo.ElementMapping лежит ещё и в
  docx4j-export-fo: в fat-jar без ServicesResourceTransformer второй файл
  перезаписывает первый, FOP не узнаёт namespace fo: и падает на
  UnknownXMLObj. Тесты этого не видят — они идут по classpath.

* addPhysicalFont не перезаписывает занятый ключ реестра: системный
  DejaVuSerif.ttf занимает «dejavu serif» и наш DejaVuSerif-Regular.ttf
  не регистрировался. BundledFonts.init() чистит реестр до регистрации.

* Fop.Renderers.getRenderer() теперь список w:renderer по mime —
  FopFallbackFonts ищет application/pdf.

Em-dash (U+2000-U+2EFF) остался на шрифте ранa, если в нём есть глиф —
так же делает Word (в references/word.pdf em-dash нарисован Calibri/Times,
DejaVu нет вообще), поэтому тест проверяет «вшитый шрифт, не Helvetica»,
а не конкретное семейство.
2026-10-05 21:48:23 +00:00

130 lines
6.2 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 ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
```
1. Байты `.docx` нормализуются, пока docx4j не увидел документ:
`DocxOnOffNormalizer` (docx4j теряет `w:val="off"/"on"` при JAXB-разборе,
из-за чего regular-раны могли рендериться жирным курсивом),
`SymbolFontNormalizer` (маркеры из Symbol/Wingdings вместо «#») и
`FieldNormalizer` (поля `PAGE`/`NUMPAGES` пересчитываются, а не печатают
кэш из docx).
2. Документ загружается в `WordprocessingMLPackage`, привязывается
`BundledFontMapper`, диаграммы и SmartArt предварительно растеризуются
в PNG (`DrawingPreRenderer`).
3. Экспорт в XSL-FO (XSLT-проход + `WordLayoutFixups`), затем `Apache FOP`
рендерит PDF, встраивая используемые подмножества шрифтов.
## Ограничения
- Это **не** pixel-perfect рендер Word: раскладка, поля и некоторые эффекты
приближённые (ограничения FOP/docx4j, а не «мы что-то упустили»).
- Символы U+2000–U+2EFF (em-dash и т.п.) берутся из шрифта ранa, если в нём
есть глиф, иначе — из fallback-семейства DejaVu.
- Поддержка таблиц/изображений — базовая (через docx4j/FOP).
## Тесты
Тесты используют готовые `.docx` из `wordpdf-core/src/test/resources/samples/`
(генерируются POI) и проверяют извлечённый PDFBox'ом текст и встраивание
шрифтов. Запуск: `mvn test`.