feat: 完成 DOCX R4 元素级视觉门禁

建立 Chromium、Word 与 WPS 的可编辑内容、段落几何、页眉页脚、封面、媒体和逐页视觉比较链路。支持封面独立分节、正文页码重启、主题页边距与横向纸张，并将自然分页差异降为诊断项。修正代码块内边距和折叠表格单元格边框映射，14 套主题生产矩阵与六组布局视觉矩阵通过。
2026-08-02 03:27:11 +08:00
parent f9f5fccfc9
commit 58f87cc19f
100 changed files with 10409 additions and 386 deletions
@@ -5,6 +5,7 @@ import {
  MAXIMUM_DOCX_RESOURCE_COUNT,
  type DocxMediaCapturePlan,
  type DocxMediaCaptureTarget,
+  type DocxMediaAlignment,
  type DocxMediaKind,
  type PagedDocumentPayload
 } from "@md-to-pdf/core";
@@ -93,6 +94,33 @@ function fitElementToContent(
  return element.getBoundingClientRect();
 }

+function getMediaAlignment(
+  article: HTMLElement,
+  rect: DOMRect
+): DocxMediaAlignment {
+  const articleRect = article.getBoundingClientRect();
+  const articleWidth = finitePositive(articleRect.width, rect.width);
+  if (rect.width >= articleWidth - 2) {
+    return "center";
+  }
+
+  const leftScore = Math.abs(rect.left - articleRect.left);
+  const centerScore = Math.abs(
+    (rect.left + rect.right) / 2 -
+      (articleRect.left + articleRect.right) / 2
+  );
+  const rightScore = Math.abs(articleRect.right - rect.right);
+  const minimumScore = Math.min(
+    leftScore,
+    centerScore,
+    rightScore
+  );
+  if (centerScore <= minimumScore + 2) {
+    return "center";
+  }
+  return leftScore <= rightScore ? "left" : "right";
+}
+
 function getRasterScale(width: number, height: number) {
  return Math.min(
    DOCX_MEDIA_RASTER_SCALE,
@@ -179,6 +207,7 @@ export function collectDocxMediaCaptureTargets(
      ...(getCaption(element)
        ? { caption: getCaption(element) }
        : {}),
+      alignment: getMediaAlignment(article, rect),
      displayWidthPx: width,
      displayHeightPx: height,
      captureX,
@@ -12,6 +12,9 @@ export * from "./mermaid-static-image.js";
 export * from "./paged-break-token.js";
 export * from "./paged-document-runtime.js";
 export * from "./paged-preview.js";
+export * from "./paged-page-sequence.js";
+export * from "./semantic-cover-fit.js";
+export * from "./paged-page-decorations.js";
 export * from "./paged-render-target.js";
 export * from "./pdf-document-links.js";
 export * from "./preview-styles.js";
@@ -44,13 +44,13 @@ import {
  documentBaseCss,
  documentGeometryCss,
  documentInteractionCss,
-  formatPageNumber,
-  resolvePageNumberAlignment,
-  shouldRenderPageNumber,
  type PagedPreviewPayload
 } from "./paged-preview.js";
+import { constrainSemanticCoversToPage } from "./semantic-cover-fit.js";
 import type { PagedRenderTarget } from "./paged-render-target.js";
 import { preparePdfDocumentLinks } from "./pdf-document-links.js";
+import { classifyPagedPages } from "./paged-page-sequence.js";
+import { applyPagedPageDecorations } from "./paged-page-decorations.js";

 export type {
  PagedDocumentRenderResult,
@@ -155,48 +155,6 @@ function mountMeasurementContainer(
  };
 }

-function applyPageNumbers(
-  container: ParentNode,
-  payload: PagedPreviewPayload,
-  totalPages: number
-) {
-  if (!payload.exportConfig.footer.enabled) {
-    return;
-  }
-
-  const pages = Array.from(
-    container.querySelectorAll<HTMLElement>(".pagedjs_page")
-  );
-
-  for (const [pageIndex, page] of pages.entries()) {
-    if (
-      !shouldRenderPageNumber(
-        payload.exportConfig.footer,
-        pageIndex
-      )
-    ) {
-      continue;
-    }
-    const alignment = resolvePageNumberAlignment(
-      payload.exportConfig.footer,
-      pageIndex
-    );
-    const content = page.querySelector<HTMLElement>(
-      `.pagedjs_margin-bottom-${alignment} .pagedjs_margin-content`
-    );
-    if (!content) {
-      continue;
-    }
-
-    content.textContent = formatPageNumber(
-      payload.exportConfig.footer,
-      pageIndex,
-      totalPages
-    );
-    content.setAttribute("data-page-number-rendered", "true");
-  }
-}
-
 function removeTrailingPdfPageBreak(container: ParentNode) {
  const pages = Array.from(
    container.querySelectorAll<HTMLElement>(".pagedjs_page")
@@ -215,6 +173,7 @@ function createPagedRenderIdentity(
    mermaidOutput: options.mermaidOutput,
    themeCss: payload.themeCss,
    exportConfig: payload.exportConfig,
+    semanticDocument: payload.semanticDocument,
    metadata: payload.metadata,
    features: payload.features
  });
@@ -676,7 +635,8 @@ export class PagedDocumentRuntime {
    if (
      payload.features.includes("echarts") ||
      content.querySelector(".mermaid svg") ||
-      content.querySelector("img.md-document-image")
+      content.querySelector("img.md-document-image") ||
+      content.querySelector('[data-semantic-region="cover"]')
    ) {
      const measurement = mountMeasurementContainer(
        documentRef,
@@ -687,6 +647,10 @@ export class PagedDocumentRuntime {
      );
      try {
        await documentRef.fonts.ready;
+        constrainSemanticCoversToPage(
+          measurement.host,
+          getPageContentDimensions(payload.exportConfig).height
+        );

        const echartsStartedAt = performance.now();
        echartsErrors = await this.renderECharts(
@@ -902,7 +866,8 @@ export class PagedDocumentRuntime {
    }

    const finalizeStartedAt = performance.now();
-    applyPageNumbers(this.root, payload, pageCount);
+    const pageSequence = classifyPagedPages(this.root, payload);
+    applyPagedPageDecorations(this.root, payload, pageSequence);
    if (options.target === "pdf") {
      removeTrailingPdfPageBreak(this.root);
    }
@@ -0,0 +1,107 @@
+import {
+  formatPageNumber,
+  resolvePageNumberAlignment,
+  type PagedPreviewPayload
+} from "./paged-preview.js";
+import type { PagedPageSequence } from "./paged-page-sequence.js";
+
+const alignments = ["left", "center", "right"] as const;
+
+function setMarginBoxesVisible(
+  page: HTMLElement,
+  position: "top" | "bottom",
+  visible: boolean
+) {
+  for (const alignment of alignments) {
+    const box = page.querySelector<HTMLElement>(
+      `.pagedjs_margin-${position}-${alignment}`
+    );
+    if (!box) {
+      continue;
+    }
+    if (visible) {
+      box.style.removeProperty("visibility");
+    } else {
+      box.style.setProperty("visibility", "hidden", "important");
+    }
+  }
+}
+
+function clearInjectedPageNumbers(page: HTMLElement) {
+  for (const alignment of alignments) {
+    const content = page.querySelector<HTMLElement>(
+      `.pagedjs_margin-bottom-${alignment} .pagedjs_margin-content`
+    );
+    if (!content) {
+      continue;
+    }
+    content.textContent = "";
+    content.removeAttribute("data-page-number-rendered");
+    content.removeAttribute("data-page-number-alignment");
+  }
+}
+
+export function applyPagedPageDecorations(
+  container: ParentNode,
+  payload: PagedPreviewPayload,
+  sequence: PagedPageSequence
+) {
+  const pages = Array.from(
+    container.querySelectorAll<HTMLElement>(".pagedjs_page")
+  );
+  const pageNumberConfig = {
+    ...payload.exportConfig.footer,
+    startFrom: sequence.bodyPageNumberStart
+  };
+
+  for (const state of sequence.pages) {
+    const page = pages[state.physicalPageIndex];
+    if (!page) {
+      continue;
+    }
+
+    clearInjectedPageNumbers(page);
+    const isCover = state.kind === "cover";
+    const isBodyFirst = state.kind === "body-first";
+    const headerVisible =
+      payload.exportConfig.header.enabled &&
+      !isCover &&
+      (!isBodyFirst || payload.exportConfig.header.showOnFirstPage);
+    const footerVisible =
+      payload.exportConfig.footer.enabled &&
+      !isCover &&
+      (!isBodyFirst || payload.exportConfig.footer.showOnFirstPage);
+
+    setMarginBoxesVisible(page, "top", headerVisible);
+    setMarginBoxesVisible(page, "bottom", footerVisible);
+    page.dataset.headerVisible = String(headerVisible);
+    page.dataset.footerVisible = String(footerVisible);
+
+    if (
+      !footerVisible ||
+      state.bodyPageIndex === undefined ||
+      state.pageNumber === undefined
+    ) {
+      continue;
+    }
+
+    const alignment = resolvePageNumberAlignment(
+      pageNumberConfig,
+      state.bodyPageIndex
+    );
+    const content = page.querySelector<HTMLElement>(
+      `.pagedjs_margin-bottom-${alignment} .pagedjs_margin-content`
+    );
+    if (!content) {
+      continue;
+    }
+
+    content.textContent = formatPageNumber(
+      pageNumberConfig,
+      state.bodyPageIndex,
+      sequence.bodyPageCount
+    );
+    content.setAttribute("data-page-number-rendered", "true");
+    content.setAttribute("data-page-number-alignment", alignment);
+  }
+}
@@ -0,0 +1,110 @@
+import type {
+  PagedDocumentPayload,
+  SemanticDocumentSectionIntent
+} from "@md-to-pdf/core";
+
+export type PagedPageKind = "cover" | "body-first" | "body-rest";
+
+export interface PagedPageState {
+  physicalPageIndex: number;
+  kind: PagedPageKind;
+  bodyPageIndex?: number;
+  pageNumber?: number;
+}
+
+export interface PagedPageSequence {
+  pages: PagedPageState[];
+  physicalPageCount: number;
+  bodyPageCount: number;
+  bodyPageNumberStart: number;
+}
+
+function findCoverSectionIntent(
+  payload: Pick<PagedDocumentPayload, "semanticDocument">
+): SemanticDocumentSectionIntent | undefined {
+  return payload.semanticDocument.regions.find(
+    (region) => region.kind === "cover" && region.section
+  )?.section;
+}
+
+export function createPagedPageSequence(
+  physicalPageCount: number,
+  coverPageIndexes: ReadonlySet<number>,
+  bodyPageNumberStart: number
+): PagedPageSequence {
+  const pages: PagedPageState[] = [];
+  let bodyPageIndex = 0;
+
+  for (
+    let physicalPageIndex = 0;
+    physicalPageIndex < physicalPageCount;
+    physicalPageIndex += 1
+  ) {
+    if (coverPageIndexes.has(physicalPageIndex)) {
+      pages.push({ physicalPageIndex, kind: "cover" });
+      continue;
+    }
+
+    pages.push({
+      physicalPageIndex,
+      kind: bodyPageIndex === 0 ? "body-first" : "body-rest",
+      bodyPageIndex,
+      pageNumber: bodyPageNumberStart + bodyPageIndex
+    });
+    bodyPageIndex += 1;
+  }
+
+  return {
+    pages,
+    physicalPageCount,
+    bodyPageCount: bodyPageIndex,
+    bodyPageNumberStart
+  };
+}
+
+export function classifyPagedPages(
+  container: ParentNode,
+  payload: Pick<
+    PagedDocumentPayload,
+    "semanticDocument" | "exportConfig"
+  >
+): PagedPageSequence {
+  const pageElements = Array.from(
+    container.querySelectorAll<HTMLElement>(".pagedjs_page")
+  );
+  const coverIntent = findCoverSectionIntent(payload);
+  const coverPageIndexes = new Set<number>();
+
+  if (coverIntent) {
+    for (const [pageIndex, page] of pageElements.entries()) {
+      if (page.querySelector('[data-semantic-region="cover"]')) {
+        coverPageIndexes.add(pageIndex);
+      }
+    }
+  }
+
+  const sequence = createPagedPageSequence(
+    pageElements.length,
+    coverPageIndexes,
+    coverIntent?.followingPageNumberStart ??
+      payload.exportConfig.footer.startFrom
+  );
+
+  for (const state of sequence.pages) {
+    const page = pageElements[state.physicalPageIndex];
+    if (!page) {
+      continue;
+    }
+    page.dataset.pageKind = state.kind;
+    page.dataset.physicalPageIndex = String(state.physicalPageIndex);
+    if (state.bodyPageIndex === undefined) {
+      delete page.dataset.bodyPageIndex;
+      delete page.dataset.pageNumber;
+    } else {
+      page.dataset.bodyPageIndex = String(state.bodyPageIndex);
+      page.dataset.pageNumber = String(state.pageNumber);
+    }
+  }
+
+  return sequence;
+}
@@ -162,6 +162,16 @@ body,
  background: transparent !important;
 }

+#write [data-semantic-break-after="next-page"] {
+  break-after: page !important;
+  page-break-after: always !important;
+}
+
+#write [data-semantic-region="cover"][data-semantic-break-after="next-page"] {
+  break-inside: avoid !important;
+  page-break-inside: avoid !important;
+}
+
 #write {
  width: 100% !important;
  max-width: none !important;
@@ -283,6 +293,7 @@ function marginBox(
    fontFamily: string;
    fontSize: string;
    height: string;
+    pageMargin: string;
    showDivider: boolean;
  }
 ) {
@@ -293,6 +304,10 @@ function marginBox(
        ? "border-top: 0.2mm solid currentColor;"
        : "";
  const verticalAlignment = position === "top" ? "bottom" : "top";
+  const verticalOffset =
+    position === "top"
+      ? `calc(${options.pageMargin} - ${options.height} - ${options.fontSize})`
+      : `calc(${options.height} - ${options.fontSize})`;

  return `
  @${position}-${alignment} {
@@ -305,6 +320,7 @@ function marginBox(
    line-height: 1.25;
    text-align: ${alignment};
    vertical-align: ${verticalAlignment};
+    transform: translateY(${verticalOffset});
    ${border}
  }`;
 }
@@ -322,6 +338,7 @@ function buildHeaderCss(
    fontFamily: config.header.fontFamily,
    fontSize: config.header.fontSize,
    height: config.header.height,
+    pageMargin: config.paper.margins.top,
    showDivider: config.header.showDivider
  };

@@ -351,6 +368,7 @@ function buildFooterCss(config: ExportConfig) {
    fontFamily: config.footer.fontFamily,
    fontSize: config.footer.fontSize,
    height: config.footer.height,
+    pageMargin: config.paper.margins.bottom,
    showDivider: config.footer.showDivider
  };

@@ -0,0 +1,33 @@
+const COVER_HEIGHT_EPSILON_PX = 0.5;
+
+export const semanticCoverSelector =
+  '[data-semantic-region="cover"][data-semantic-break-after="next-page"]';
+
+export function constrainSemanticCoversToPage(
+  root: ParentNode,
+  pageContentHeightPx: number
+) {
+  if (!Number.isFinite(pageContentHeightPx) || pageContentHeightPx <= 0) {
+    return 0;
+  }
+  let constrainedCount = 0;
+  for (const cover of Array.from(
+    root.querySelectorAll<HTMLElement>(semanticCoverSelector)
+  )) {
+    const height = cover.getBoundingClientRect().height;
+    if (
+      !Number.isFinite(height) ||
+      height <= pageContentHeightPx + COVER_HEIGHT_EPSILON_PX
+    ) {
+      continue;
+    }
+    const constrainedHeight = `${pageContentHeightPx}px`;
+    cover.style.boxSizing = "border-box";
+    cover.style.height = constrainedHeight;
+    cover.style.minHeight = constrainedHeight;
+    cover.style.maxHeight = constrainedHeight;
+    cover.dataset.semanticCoverFit = "constrained";
+    constrainedCount += 1;
+  }
+  return constrainedCount;
+}