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», а не конкретное семейство.
This commit is contained in:
@@ -28,15 +28,21 @@
|
||||
- 28 TTF в `wordpdf-core/src/main/resources/fonts/` — бинарные фикстуры, часть jar; не удалять/переименовывать без обновления маппинга.
|
||||
- Алиасы MS→open-source: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans.
|
||||
- `slf4j-simple` обязателен: без него docx4j печатает предупреждение прямо в выходной PDF (регрессионный тест `noLoggingWarningInPdf`).
|
||||
- Символы U+2000–U+2EFF (em-dash, кавычки, многоточие) рендерятся DejaVu Sans, а не шрифтом ранa — по дизайну; виртуальный «Segoe UI Symbol» мапится на fallback.
|
||||
- Символы U+2000–U+2EFF (em-dash, кавычки, многоточие): `RunFontSelector.symbolBlockFont` оставляет шрифт ранa, если в нём есть этот глиф, и только иначе подставляет виртуальный «Segoe UI Symbol» (маппится на fallback DejaVu Sans, см. `BundledFontMapper`). Так же делает Word: в `references/word.pdf` em-dash нарисован Calibri/Times, DejaVu там нет вообще. Регрессия — `ruPlain_emDashEmbeddedNotHelvetica` (проверяет, что глиф рисует **вшитый** шрифт, а не базовый Helvetica).
|
||||
|
||||
## Архитектура (неочевидное)
|
||||
|
||||
- Пайплайн: байты docx → `DocxOnOffNormalizer` → `SymbolFontNormalizer` → `FieldNormalizer` → docx4j → XSL-FO (XSLT) → FOP → PDF.
|
||||
- Поля страниц: Word пишет `PAGE`/`NUMPAGES` сложным полем (`fldChar begin` → `instrText` → `separate` → кэш → `end`). Экспорт docx4j в FO `w:instrText` внутри такого поля игнорирует и печатает кэш docx — во всех колонтитулах одно число (в эталоне «2» вместо 1, 2, 3 …). `FieldNormalizer` разворачивает поле в `w:fldSimple` (его обрабатывает `FldSimpleWriter` из docx4j-export-fo: PAGE → `fo:page-number`, есть также NUMPAGES/SECTIONPAGES/PAGEREF), сохраняя внутри закэшированные ран — они дают шрифт/размер. Штатный `FieldsCombiner` docx4j делает то же, но не заходит внутрь `w:sdt`, а Word держит нумерацию именно в контентном контроле («Page Numbers (Top of Page)»). Трогаются только инструкции, для которых есть обработчик; вложенные поля пропускаются. Регрессия — `WordPdfConverterTest#pageNumbers_recomputedNotCached`, фикстура `samples/page-numbers.docx`.
|
||||
- Символьные шрифты: Word хранит маркеры списков и спецсимволы кодами из PUA (U+F0xx), глиф выбирается по имени шрифта (`Symbol`, `Wingdings`, `Webdings`). Экспорт docx4j в FO этих шрифтов не знает: код уходит в fallback, глифа нет, FOP рисует `.notdef` — в PDF решётка «#». `SymbolFontNormalizer` (шаг 1.6, тоже правит байты до JAXB) меняет код на Unicode, а имя шрифта — на `DejaVu Sans`. Таблица кодов — `SymbolMapper` из docx4j 17.x, отфильтрована по наличию глифа в DejaVu; константы сгенерированы, менять руками нельзя. Обрабатываются `w:lvl` (numbering.xml), `w:r` и `w:sym`; ран с `w:sym` разрезается, т.к. у символа собственный `w:font`. Регрессия — `WordPdfConverterTest#symbolFonts_bulletsAreNotHash`, фикстура `samples/symbol-bullets.docx`.
|
||||
- Порядок инициализации в `WordPdfConverter.convertToStream` важен: сначала `new BundledFontMapper()`, потом `BundledFonts.init()` (бандл-шрифты регистрируются поверх системных), затем `BundledFonts.restrictToBundled()` (чистит реестр `PhysicalFonts` от системных шрифтов до `load()`; конструктор маппера каждый раз заново добавляет их, и `GlyphCheck` на Windows находит системный Calibri — em-dash остаётся на Carlito, красный `ruPlain_emDashEmbeddedNotHelvetica`). Не менять местами.
|
||||
- docx4j 11.x теряет атрибуты `w:val="off"/"on"` при JAXB-разборе — поэтому нужна нормализация байтов до загрузки (регрессионный тест `ruPlain_regularRunsUseRegularFont`).
|
||||
- Порядок инициализации в `WordPdfConverter.convertToStream` важен: сначала `new BundledFontMapper()`, потом `BundledFonts.init()`, затем `BundledFonts.restrictToBundled()` (чистит реестр `PhysicalFonts` от системных шрифтов до `load()`; конструктор маппера каждый раз заново добавляет их). Не менять местами.
|
||||
- docx4j 17.x по-прежнему теряет атрибуты `w:val="off"/"on"` при JAXB-разборе — нормализация байтов до загрузки (`DocxOnOffNormalizer`) нужна и на 17.x (проверялось отключением: красный `ruPlain_regularRunsUseRegularFont`).
|
||||
- Ключ реестра `PhysicalFonts` — имя шрифта, и `addPhysicalFont(URI)` **не перезаписывает** занятый ключ. Системный `DejaVuSerif.ttf` занимает «dejavu serif», и наш `DejaVuSerif-Regular.ttf` (то же имя) не добавился бы — `BundledFonts.init()` перед регистрацией вызывает `dropNonBundled()`.
|
||||
- **`docx4j.convert.out.fo.gsubFeatures=false`** ставится в статическом блоке `WordPdfConverter` — критично. Иначе docx4j навешивает на `fo:inline` атрибут `fox:gsub-features`, не объявляя префикс `fox`; FO становится некорректным XML, `WordLayoutFixups` не может его разобрать, молча отказывается от всех фикс и оставляет хинты `docx4j-baseline`, которые FOP отвергает (`Invalid property encountered on "fo:block": docx4j-baseline`). Без фиксов нет ни колонок, ни колонок таблиц.
|
||||
- `WordLayoutFixups` (включён по умолчанию в 17.x) — постобработка DOM XSL-FO: `columnBreaks` (реально работают `w:cols/@w:num`, 2 колонки на стр. 9–11 эталона), `disregardBaselineShifts`, `lineBoxAttributes`, `stripHints` и др. Побочный эффект: авто-ширины колонок таблиц без `tblGrid`/`tcW` стали уже (слово может перенестись внутри ячейки) — в `tableImage_tableAndImage` сравнение нормализовано по пробелам.
|
||||
- Формулы OMML (`m:oMath`) рисует `jeuclid-fop`, который в 17.x пришёл вместе с `docx4j-export-fo` — отдельного кода не требуется (в 11.5.3 формула молча исчезала).
|
||||
- **`ServicesResourceTransformer` в maven-shade (`wordpdf-cli`) обязателен**: `META-INF/services/org.apache.fop.fo.ElementMapping` лежит и в `docx4j-fo-renderer-core`, и в `docx4j-export-fo`; без слияния второй перезаписывает первый, FOP не узнаёт namespace `fo:` и падает на `UnknownXMLObj cannot be cast to Root`. В fat-jar это не видно из тестов — тесты идут по classpath, проверять `java -jar`.
|
||||
- FOP в 17.x — форк `org.docx4j:docx4j-fo-renderer*` (пакеты `org.apache.fop.*`), он знает хинты `docx4j:baseline`/`docx4j:line-box` через `WordLayoutElementMapping`. `Fop.Renderers.getRenderer()` теперь возвращает **список** `w:renderer` (по mime) — `FopFallbackFonts.rendererFonts` ищет `application/pdf`.
|
||||
- Диаграммы: `docx2fo.xslt` умеет только `a:graphicData/pic:pic`, для `c:chart` и `dgm:relIds` там `notImplemented` (объект молча исчезает). Поэтому `DrawingPreRenderer.run(pkg)` (шаг 3.5 в `convertToStream`, после `setFontMapper` и до `FOSettings`) рендерит их своим Java2D-движком в PNG 300 dpi (`internal/chart/*`) и подменяет на `pic:pic`. Тест `chartsSmartArt_drawingsBecomeImages`, фикстура `samples/charts-smartart.docx`.
|
||||
- В `DrawingPreRenderer` нужны собственные rels части — `part.getRelationshipsPart()` (`Base`), а **не** `getOwningRelationshipPart()`: у `document.xml` последнее указывает на пакетный `.rels`. Обход `pkg.getParts()` — только по снимку списка: `createImagePart` докидывает части в тот же реестр.
|
||||
- SmartArt рисуется из `word/diagrams/drawing1.xml` (кэш разложенной Word-ом схемы: абсолютные позиции + `prstGeom`); текст-заполнители (`[Текст]`) лежат в `data1.xml` на `dgm:pt type="node"`, а формы ссылаются на `dgm:pt type="pres"` — связь через `dgm:cxn type="presOf"`.
|
||||
|
||||
Reference in New Issue
Block a user