refactor(core): интерфейс DocxNormalizer, конвейер нормализаторов списком в конвертере
PR checks / web (pull_request) Successful in 40s
PR checks / java (pull_request) Successful in 58s

This commit is contained in:
Pjandro
2026-10-25 00:13:29 +00:00
parent e356c36e45
commit 5714bc835b
2 changed files with 59 additions and 28 deletions
@@ -11,6 +11,7 @@ import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import ru.pjandro.wordpdf.fonts.BundledFontMapper;
import ru.pjandro.wordpdf.fonts.BundledFonts;
import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer;
import ru.pjandro.wordpdf.internal.DocxNormalizer;
import ru.pjandro.wordpdf.internal.DocxOnOffNormalizer;
import ru.pjandro.wordpdf.internal.FieldNormalizer;
import ru.pjandro.wordpdf.internal.GlyphCoverageNormalizer;
@@ -23,6 +24,7 @@ import ru.pjandro.wordpdf.internal.SymbolFontNormalizer;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.OutputStream;
import java.util.List;
/**
* Конвертер docx -> PDF на базе docx4j + Apache FOP
@@ -128,34 +130,13 @@ public final class WordPdfConverter {
// em-dash (U+2000–U+2EFF) остаётся на шрифте ранa вместо fallback.
BundledFonts.restrictToBundled();
// 2. Загрузка документа. Первым strict-OOXML: Word в strict пишет
// проценты строками ("130%") и w:start/w:end вместо w:left/
// w:right — JAXB падает на int-биндингах (см. StrictOoxmlNormalizer);
// дальше по конвейеру лежит уже transitional-байт.
byte[] docxBytes = StrictOoxmlNormalizer.normalize(rawDocxBytes);
// ...затем w:val="off"/"on" в "false"/"true": docx4j 11.x теряет
// атрибуты "off"/"on" при JAXB-разборе (см. DocxOnOffNormalizer).
docxBytes = DocxOnOffNormalizer.normalize(docxBytes);
// ...и символьные шрифты Symbol/Wingdings: их коды из PUA экспорт
// в FO не понимает и рисует «#» (см. SymbolFontNormalizer).
docxBytes = SymbolFontNormalizer.normalize(docxBytes);
// ...и поля PAGE/NUMPAGES из fldChar делаем w:fldSimple, иначе
// в колонтитулах печатается кэш docx (см. FieldNormalizer).
docxBytes = FieldNormalizer.normalize(docxBytes);
// ...и невидимые символы (U+0085/U+2028/U+2029, U+2060/U+FEFF,
// bidi-метки): FOP превращает первые три в принудительные переносы
// — пустые строки, а Arimo/Tinos рисуют для них видимые боксы;
// в Word они невидимы (см. InvisibleCharNormalizer).
docxBytes = InvisibleCharNormalizer.normalize(docxBytes);
// ...и раны со знаками, которых нет в их шрифте: без этого
// FOP рисует «#» (docx4j проверяет покрытие не для всех знаков
// и кэширует фолбэк на группу Юникода, см. GlyphCoverageNormalizer).
docxBytes = GlyphCoverageNormalizer.normalize(docxBytes);
// ...и OLE-объекты (внедрённые бинарные .bin-части): docx4j падает и на
// ложном XML-типе bin-части в [Content_Types], и на сериализации VML
// w:object. При выключенном errorOnOle объекты тихо удаляются (часть,
// rels, w:object), при включённом — отказ (см. OleObjectNormalizer).
docxBytes = OleObjectNormalizer.normalize(docxBytes, options.errorOnOle());
// 2. Загрузка документа: байтовый конвейер нормализаторов в фиксированном
// порядке (см. normalizers) — дальше лежит transitional-байт, готовый
// для JAXB/docx4j.
byte[] docxBytes = rawDocxBytes;
for (DocxNormalizer normalizer : normalizers(options)) {
docxBytes = normalizer.normalize(docxBytes);
}
WordprocessingMLPackage pkg = WordprocessingMLPackage.load(
new ByteArrayInputStream(docxBytes));
try {
@@ -202,4 +183,38 @@ public final class WordPdfConverter {
// пакет загружается в память и ничего не закрывает.
}
}
/**
* Конвейер байтовой нормализации docx. Порядок фиксирован:
* StrictOoxml первым (дальше по конвейеру лежит transitional-байт),
* GlyphCoverage после SymbolFont/InvisibleChar (покрытие считается по
* финальному тексту/шрифтам рана), OleObject последним (меняет части,
* а не XML ранов). Регрессии каждого шага — в javadoc нормализатора.
*/
private static List<DocxNormalizer> normalizers(ConvertOptions options) {
return List.of(
// strict-OOXML -> transitional: проценты строками и w:start/w:end
// ломают int-биндинги JAXB (StrictOoxmlNormalizer)
StrictOoxmlNormalizer::normalize,
// w:val="off"/"on" -> "false"/"true": docx4j теряет on/off
// при JAXB-разборе (DocxOnOffNormalizer)
DocxOnOffNormalizer::normalize,
// Symbol/Wingdings PUA -> Unicode + DejaVu Sans, иначе «#»
// (SymbolFontNormalizer)
SymbolFontNormalizer::normalize,
// поля PAGE/NUMPAGES fldChar -> w:fldSimple, иначе печатается
// кэш docx (FieldNormalizer)
FieldNormalizer::normalize,
// невидимые символы (U+0085/U+2028/U+2029, U+2060/U+FEFF,
// bidi-метки): FOP делает из них переносы, Arimo/Tinos — боксы
// (InvisibleCharNormalizer)
InvisibleCharNormalizer::normalize,
// раны со знаками вне покрытия их шрифта: режем ран, иначе
// FOP рисует «#» (GlyphCoverageNormalizer)
GlyphCoverageNormalizer::normalize,
// OLE-объекты: при выключенном errorOnOle тихо удаляем
// (часть/rels/w:object), при включённом — DrawingFoundException
// (OleObjectNormalizer)
bytes -> OleObjectNormalizer.normalize(bytes, options.errorOnOle()));
}
}
@@ -0,0 +1,16 @@
package ru.pjandro.wordpdf.internal;
import java.io.IOException;
/**
* Шаг байтового конвейера нормализации docx перед WordprocessingMLPackage.load():
* принимает байты .docx (zip), возвращает те же байты, если менять нечего,
* иначе переупакованный zip (контракт assertSame — см. тесты нормализаторов).
* Порядок шагов задаёт единственный конвейер — WordPdfConverter#normalizers;
* перестановка шагов ломает конвертацию (см. javadoc каждого нормализатора).
*/
@FunctionalInterface
public interface DocxNormalizer {
byte[] normalize(byte[] docx) throws IOException;
}