Поля страниц: PAGE/NUMPAGES пересчитываются, а не печатают кэш

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 и вложенные поля пропускаются.
This commit is contained in:
Pjandro
2026-10-05 21:25:46 +00:00
parent 660bc19da7
commit 3ebb4780dd
7 changed files with 438 additions and 1 deletions
@@ -6,12 +6,17 @@ import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.apache.poi.xwpf.usermodel.XWPFRun;
import org.apache.poi.xwpf.usermodel.XWPFTable;
import org.apache.poi.xwpf.usermodel.XWPFTableCell;
import org.apache.poi.xwpf.usermodel.XWPFHeader;
import org.apache.poi.xwpf.usermodel.XWPFFooter;
import org.apache.poi.wp.usermodel.HeaderFooterType;
import org.apache.poi.xwpf.usermodel.ParagraphAlignment;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTAbstractNum;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTFonts;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTLvl;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTNumPr;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTPPr;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTSym;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.STFldCharType;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.STNumberFormat;
import org.apache.poi.xwpf.usermodel.XWPFAbstractNum;
import org.apache.poi.xwpf.usermodel.XWPFNumbering;
@@ -61,6 +66,7 @@ public final class SampleDocxGenerator {
ruTimes(dir.resolve("ru-times.docx"));
ruTableImage(dir.resolve("ru-table-image.docx"));
symbolBullets(dir.resolve("symbol-bullets.docx"));
pageNumbers(dir.resolve("page-numbers.docx"));
System.out.println("Готово: " + dir.toAbsolutePath());
}
@@ -248,6 +254,53 @@ public final class SampleDocxGenerator {
}
}
/**
* Нумерация страниц: {@code PAGE} в колонтитуле — сложным полем
* ({@code fldChar} + {@code instrText} + кэш), как его пишет Word.
* Экспорт docx4j в FO {@code instrText} в таком поле игнорирует и печатает
* кэш, поэтому без FieldNormalizers все страницы получают одно число.
*/
private static void pageNumbers(Path out) throws Exception {
try (XWPFDocument doc = new XWPFDocument()) {
XWPFHeader header = doc.createHeader(HeaderFooterType.DEFAULT);
XWPFParagraph hp = header.createParagraph();
hp.setAlignment(ParagraphAlignment.CENTER);
complexField(hp, " PAGE \\* MERGEFORMAT ", "2");
XWPFFooter footer = doc.createFooter(HeaderFooterType.DEFAULT);
XWPFParagraph fp = footer.createParagraph();
fp.setAlignment(ParagraphAlignment.CENTER);
complexField(fp, " PAGE ", "2");
fp.createRun().setText(" / ");
complexField(fp, " NUMPAGES \\* ARABIC ", "11");
for (int page = 1; page <= 3; page++) {
XWPFParagraph p = doc.createParagraph();
if (page > 1) {
p.getCTP().addNewPPr().addNewPageBreakBefore();
}
run(p, "Страница " + page, "Times New Roman", false, false);
}
save(doc, out);
}
}
/**
* Поле так, как его сохраняет Word: ран {@code fldChar begin}, ран
* {@code instrText}, {@code separate}, закэшированный результат и
* {@code end}.
*/
private static void complexField(XWPFParagraph p, String instr, String cached) {
p.createRun().getCTR().addNewFldChar()
.setFldCharType(STFldCharType.BEGIN);
p.createRun().getCTR().addNewInstrText().setStringValue(instr);
p.createRun().getCTR().addNewFldChar()
.setFldCharType(STFldCharType.SEPARATE);
p.createRun().setText(cached);
p.createRun().getCTR().addNewFldChar()
.setFldCharType(STFldCharType.END);
}
// ================== Вспомогательные ==================
/** Абзац-заголовок: POI 5.5 не имеет createHeading, поэтому
@@ -44,6 +44,16 @@ class WordPdfConverterTest {
}
}
/** Извлекает текст одной страницы PDF (нумерация колонтитулов). */
private static String pdfPageText(Path pdf, int page) throws IOException {
try (PDDocument doc = Loader.loadPDF(pdf.toFile())) {
PDFTextStripper stripper = new PDFTextStripper();
stripper.setStartPage(page);
stripper.setEndPage(page);
return stripper.getText(doc);
}
}
/** Конвертирует docx в временный PDF и возвращает его путь. */
private static Path convert(Path docx) throws IOException {
Path out = Files.createTempFile("converted-", ".pdf");
@@ -126,6 +136,26 @@ class WordPdfConverterTest {
"пропал текст пункта списка: " + text);
}
/**
* Поля PAGE/NUMPAGES Word пишет как {@code fldChar} + {@code instrText}
* + закэшированный результат. Экспорт docx4j в FO инструкцию игнорирует
* и печатает кэш — все страницы получают одно и то же число.
* FieldNormalizer разворачивает поле в {@code w:fldSimple}, и FOP
* считает номер заново на каждой странице.
*/
@Test
void pageNumbers_recomputedNotCached() throws Exception {
Path pdf = convert(extractSample("page-numbers.docx"));
for (int page = 1; page <= 3; page++) {
String text = norm(pdfPageText(pdf, page));
assertTrue(text.contains("Страница " + page),
"страница " + page + " содержит не своё содержимое: " + text);
assertTrue(text.contains(page + " / 3"),
"колонтитул страницы " + page + " не пересчитан: " + text);
}
}
@Test
void ruPlain_cyrillicAndStyles() throws Exception {
Path in = extractSample("ru-plain.docx");
@@ -0,0 +1,126 @@
package ru.pjandro.wordpdf.internal;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
class FieldNormalizerTest {
/** Сложное поле Word: begin / instrText / separate / кэш / end. */
private static String field(String instr, String cached) {
return "<w:r><w:fldChar w:fldCharType=\"begin\"/></w:r>"
+ "<w:r><w:instrText xml:space=\"preserve\">" + instr
+ "</w:instrText></w:r>"
+ "<w:r><w:fldChar w:fldCharType=\"separate\"/></w:r>"
+ "<w:r><w:rPr><w:sz w:val=\"20\"/></w:rPr><w:t>" + cached + "</w:t></w:r>"
+ "<w:r><w:fldChar w:fldCharType=\"end\"/></w:r>";
}
@Test
void pageFieldBecomesFldSimple() {
String xml = "<w:p>" + field(" PAGE \\* MERGEFORMAT ", "2") + "</w:p>";
String out = FieldNormalizer.rewrite(xml);
assertTrue(out.startsWith("<w:p><w:fldSimple w:instr=\" PAGE \\* MERGEFORMAT \">"),
out);
// кэш остаётся внутри — он даёт оформление (шрифт, размер)
assertTrue(out.contains("<w:rPr><w:sz w:val=\"20\"/></w:rPr><w:t>2</w:t>"), out);
assertTrue(out.endsWith("</w:fldSimple></w:p>"), out);
assertTrue(!out.contains("fldChar"), "fldChar не удалён: " + out);
}
@Test
void numpagesAndSectionpagesAreSupported() {
for (String instr : new String[]{" NUMPAGES \\* ARABIC ", " SECTIONPAGES "}) {
String out = FieldNormalizer.rewrite("<w:p>" + field(instr, "11") + "</w:p>");
assertTrue(out.contains("<w:fldSimple w:instr=\"" + instr + "\">"), instr + ": " + out);
}
}
/** Инструкцию Word дробит на несколько w:instrText — их нужно склеить. */
@Test
void instructionSplitAcrossRuns() {
String xml = "<w:p><w:r><w:fldChar w:fldCharType=\"begin\"/></w:r>"
+ "<w:r><w:instrText xml:space=\"preserve\"> NUM</w:instrText></w:r>"
+ "<w:r><w:instrText xml:space=\"preserve\">PAGES </w:instrText></w:r>"
+ "<w:r><w:fldChar w:fldCharType=\"separate\"/></w:r>"
+ "<w:r><w:t>11</w:t></w:r>"
+ "<w:r><w:fldChar w:fldCharType=\"end\"/></w:r></w:p>";
String out = FieldNormalizer.rewrite(xml);
assertTrue(out.contains("<w:fldSimple w:instr=\" NUMPAGES \">"), out);
}
@Test
void otherFieldsUntouched() {
String xml = "<w:p>" + field(" HYPERLINK \"https://example.com\" ", "ссылка")
+ "</w:p>";
assertNull(FieldNormalizer.rewrite(xml), "чужое поле переписано");
}
/** Вложенное поле: разбирать его не берёмся, но и ломать не должны. */
@Test
void nestedFieldUntouched() {
String xml = "<w:p>"
+ "<w:r><w:fldChar w:fldCharType=\"begin\"/></w:r>"
+ "<w:r><w:instrText>= PAGE </w:instrText></w:r>"
+ field(" PAGE ", "2")
+ "<w:r><w:fldChar w:fldCharType=\"end\"/></w:r></w:p>";
assertNull(FieldNormalizer.rewrite(xml), "вложенное поле переписано");
}
/** Соседние ран-свойства и остальной документ остаются без изменений. */
@Test
void surroundingContentPreserved() {
String xml = "<w:hdr><w:p><w:pPr><w:jc w:val=\"center\"/></w:pPr>"
+ "<w:r><w:t>до</w:t></w:r>" + field(" PAGE ", "2")
+ "<w:r><w:t>после</w:t></w:r></w:p></w:hdr>";
String out = FieldNormalizer.rewrite(xml);
assertTrue(out.startsWith("<w:hdr><w:p><w:pPr><w:jc w:val=\"center\"/></w:pPr>"
+ "<w:r><w:t>до</w:t></w:r>"), out);
assertTrue(out.endsWith("<w:r><w:t>после</w:t></w:r></w:p></w:hdr>"), out);
}
/** Поле внутри w:sdt — так Word пишет нумерацию «Page Numbers (Top of Page)». */
@Test
void fieldInsideSdt() {
String xml = "<w:sdt><w:sdtPr/><w:sdtEndPr/><w:sdtContent>"
+ field(" PAGE ", "2") + "</w:sdtContent></w:sdt>";
String out = FieldNormalizer.rewrite(xml);
assertTrue(out.startsWith("<w:sdt><w:sdtPr/><w:sdtEndPr/><w:sdtContent>"
+ "<w:fldSimple"), out);
assertTrue(out.endsWith("</w:fldSimple></w:sdtContent></w:sdt>"), out);
}
@Test
void nothingToChangeReturnsNull() {
assertNull(FieldNormalizer.rewrite("<w:p><w:r><w:t>текст</w:t></w:r></w:p>"));
}
/** Поле без separate/end — битое, пропускаем, остальное не трогаем. */
@Test
void unterminatedFieldSkipped() {
String xml = "<w:p><w:r><w:fldChar w:fldCharType=\"begin\"/></w:r>"
+ "<w:r><w:instrText> PAGE </w:instrText></w:r></w:p>";
assertNull(FieldNormalizer.rewrite(xml));
}
/** Кавычка и ampersand в инструкции не должны сломать атрибут. */
@Test
void instructionEscapedIntoAttribute() {
String out = FieldNormalizer.rewrite(
"<w:p>" + field(" STYLEREF \"Раздел &amp; номер\" ", "1") + "</w:p>");
// STYLEREF не поддерживается — поле должно остаться как было
assertNull(out);
String page = FieldNormalizer.rewrite(
"<w:p>" + field(" PAGE ", "1") + "</w:p>");
assertEquals("<w:p><w:fldSimple w:instr=\" PAGE \">"
+ "<w:r><w:rPr><w:sz w:val=\"20\"/></w:rPr><w:t>1</w:t></w:r>"
+ "</w:fldSimple></w:p>", page);
}
}