3ebb4780dd
Word записывает поле колонтитула как fldChar begin -> instrText "PAGE" -> separate -> закэшированный результат -> end. Экспорт docx4j в XSL-FO инструкцию внутри такого поля не видит и печатает кэш из docx: в references/word.docx на всех страницах было «2» и «11/11». FieldNormalizer разворачивает поле в w:fldSimple — его обрабатывает FldSimpleWriter из docx4j-export-fo (PAGE -> fo:page-number, есть также NUMPAGES/SECTIONPAGES). Закэшированные ран сохраняются внутри поля: они дают оформление. Штатный FieldsCombiner docx4j делает то же, но не заходит внутрь w:sdt, а Word держит нумерацию именно в контентном контроле «Page Numbers (Top of Page)» — отсюда нормализация байтов. Переписываются только инструкции, для которых есть обработчик; поле без separate/end и вложенные поля пропускаются.
16 KiB
16 KiB
AGENTS.md
Конвертер docx → PDF на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: wordpdf-core (библиотека), wordpdf-cli (fat-jar через maven-shade).
Сборка
mvn clean verify— все модули + тесты; единственный гейт передgit push(lint/typecheck/CI в репозитории нет).mvn -pl wordpdf-cli package— только fat-jarwordpdf-cli/target/wordpdf-cli-1.0.0.jar.dependency-reduced-pom.xml— артефакт shade, уже в .gitignore, не коммитить.
Тесты
- JUnit 5, без внешних сервисов, headless (surefire уже задаёт
-Djava.awt.headless=true). - Один тест:
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#ruPlain_regularRunsUseRegularFont. - Тесты
wordpdf-cliзависят от test-jarwordpdf-core(classifiertests): сборка-pl wordpdf-cliбез-amне пройдёт — либо строить из корня, либо-am. - Тестовые
.docxкоммитятся вwordpdf-core/src/test/resources/samples/; тесты их не генерируют. Пересоздать — одноразовой утилитойSampleDocxGenerator(команда в javadoc класса); POI — только test scope. BundledFontsTestпроверяет синхронность спискаENTRIESс реальными TTF вresources/fonts/: новый шрифт = файл +Entry, иначе тест красный.
Эталон в references/
- 11-страничный документ (текст, таблицы, колонтитулы, 3 диаграммы + SmartArt, формулы) со своим эталонным PDF, экспортированным из Word 365:
word.docx+word.pdf— Transitional OOXML (schemas.openxmlformats.org/.../2006/...). references/— материалы для ручного сравнения с Word, не тестовые фикстуры: в тесты и в jar их не подключать (фикстуры —wordpdf-core/src/test/resources/samples/).
Шрифты (важно при изменениях)
- 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.
Архитектура (неочевидное)
- Пайплайн: байты docx →
DocxOnOffNormalizer→SymbolFontNormalizer→FieldNormalizer→ docx4j → XSL-FO (XSLT) → FOP → PDF. - Поля страниц: Word пишет
PAGE/NUMPAGESсложным полем (fldChar begin→instrText→separate→ кэш →end). Экспорт docx4j в FOw:instrTextвнутри такого поля игнорирует и печатает кэш docx — во всех колонтитулах одно число (в эталоне «2» вместо 1, 2, 3 …).FieldNormalizerразворачивает поле вw:fldSimple(его обрабатываетFldSimpleWriterиз docx4j-export-fo: PAGE →fo:page-number, есть также NUMPAGES/SECTIONPAGES/PAGEREF), сохраняя внутри закэшированные ран — они дают шрифт/размер. ШтатныйFieldsCombinerdocx4j делает то же, но не заходит внутрь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). - Диаграммы:
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". surface3D(Surface3dPainter): перспективная проекция (c:view3D/perspective, по умолчанию 30°, иdepth), грани — ровно ячейки сетки по 2 треугольника без передискретизации, цвет изc:bandFmtsзатемняется по нормали грани (Lambert). Грани рисуются в модельно-экранных координатах уже умноженными наscale/off— забыть масштаб значит нарисовать поверхность в субпиксельный ноль.- Знак
rotYв DrawingML обратный правому правилу вокруг вертикали: вSurface3dPainter.paintон берётся как-Math.toRadians(spec.rotY). Иначе передняя кромка категорий идёт вверх вправо, а ось рядов — вниз вправо (зеркально Word). c:view3D/perspective— НЕ угол обзора камеры. Расстояние камеры вSurface3dPainter=CAMERA_DISTANCE * (30/perspective), гдеCAMERA_DISTANCE = 2.36(эффективныйfov ≈ 49°, подобран фитом по эталону Word). При наивномfov = perspectiveперспектива слишком слабая: ось рядов уходит вправо вместо почти вертикального ухода в глубину, лента выглядит плоской, а левый край схлопывается в точку.- Пропорции «коробки» surface3D (
DEPTH_RATIO = 0.705,HEIGHT_RATIO = 0.664): глубина = 0.705 ширины (от неёc:view3D/depth), высота значений =0.664 * availH/availW, вписывание в область построения — равномерным масштабом. Раздельный масштаб x/y (или куб 1×1×1) даёт вертикальную гору вместо плоской ленты. - Поля вокруг коробки — доли области построения
GUTTER_LEFT = GUTTER_RIGHT = 0.1485,GUTTER_TOP = 0.116,GUTTER_BOTTOM = 0.146;offX/offYобязаны включать левое и верхнее поле (безtopGutterповерхность сидела на 22 pt выше эталона). Коробка занимает ~70% ширины: при полях «на глаз» поверхность растягивалась на 82% и лезла на подписи оси значений. - Калибровка камеры, коробки и полей зафиксирована тестами
Surface3dPainterTest.cameraMatchesWordReferenceиsurfaceSilhouetteMatchesWordPlacement. Эталон — стр. 3word-export.pdf(экспорт Word), растеризованнаяpdftoppm -r 300; цели замеряются по связному блоку граней (серые грани в силуэт входят, по одной лишь насыщенности силуэт недомерен на 7%), пунктиру переднего ребра пола и подписям осей: уклон передней кромки 0,1282, аспект силуэта 0,207, шаг оси значений 0,0504, вертикальный шаг оси рядов 0,1176 (все — относительно ширины силуэта); сам силуэт 314,9×65,3 pt с центром в (227,3; 82,3). Замеры по скриншотам давали вдвое завышенную ось рядов и раздували глубину. - Нормаль грани считается в той же метрике, что и проекция:
vумножается наdepthScale,wуже умножен наhScale. Без масштаба в нормали поверхность кажется положе и все грани уходят в светлую часть Lambert. - Затенение граней surface3D — Lambert
0.92 + 0,88·dotс клампом[0,80; 1,25]и боковым светомLIGHT = (0,83, 0,48, 0,28). Дискретные множители эталона (гистограмма цветов граней, 300 dpi) — 0,40 / 0,75 / 0,85 / 1,04 / 1,06 / 1,10; группа 0,40 — узкая полоска underside под передним краем, и разгон Lambert до неё (отрицательные dot) по всем граням ухудшает совпадение с эталоном (17,2 → 17,6 средних расхождений на пиксель), поэтому нижний кламп 0,80. Направление света перебрано по 120 направлениям — текущее лучшее. ТестshadingMatchesWordRange. - Триангуляция ячейки — диагональ с большей суммой значений (
z[r][c] + z[r+1][c+1] >= z[r+1][c] + z[r][c+1]→w00–w11, иначеw01–w10), то есть верхняя огибающая седла. Фиксированная диагональ невозможна: у седловой ячейки одна вершина попадает внутрь треугольника остальных трёх, и при «не той» диагонали второй треугольник становится невидимой щепкой, а видимая грань окрашивается не той полосой. Проверено по эталону (стр. 3word-export.pdf, 300 dpi, сравнение полос по пикселям; ячейка Ряд 1→2 / Категория 2→3): верхняя огибающая 92,3 % совпадений полос, фиксированнаяw00–w11— 81,6 %, фиксированнаяw01–w10— 57,9 %, окраска целого квада без разрезки — 74,1 %, билинейная tessellation 3×3/6×6 — 67,8 %/66,0 %. Регрессия —Surface3dPainterTest.saddleCellUsesHigherDiagonal(нижняя кромка силуэта в окне 0,42…0,55 его ширины обязана быть полосы 3–4). Клиппинг полос — по треугольникам, не по кваду. - Пустой
c:titleприc:autoTitleDeleted val="0"даёт автозаголовокChart Title(ChartSpec.AUTO_TITLE); для круговых (pie/pie3D/doughnut) вместо него — имя ряда. ТестыChartSpecTest. - В кваде ячейки
w01обязан бытьz[r+1][c], аw10—z[r][c+1](u=категория, v=ряд). Перестановка закручивает квад в «бабочку»: дыры и самопересечения граней. ChartRenderer.axisBoundsдля линейной оси значений без явногоc:minвсегда поднимает нижнюю границу до 0 (как Word); от этого зависит и легенда полос surface3D (0-1 … 4-5, а не1-2 … 4-5). Юнит-тесты —Surface3dPainterTest.- Не убирать shade-фильтры
META-INF/*.SF|*.DSA|*.RSA— подписанные jar-файлы зависимостей ломают fat-jar.
Точка входа
- Библиотека:
WordPdfConverter.convert(Path)/convert(Path, Path)— статический stateless-класс; ошибки —ConversionException. - CLI:
WordPdfCli(fat-jar, Main-Class в манифесте). Коды возврата: 0 успех, 1 ошибка использования, 2 не конвертирован хотя бы один файл.