0c10bae3cf
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», а не конкретное семейство.
130 lines
6.2 KiB
Markdown
130 lines
6.2 KiB
Markdown
# 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`.
|