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
@@ -26,6 +26,7 @@ export interface PagedDocumentPayload {
  articleHtml: string;
  fileName: string;
  metadata: MarkdownDocumentMetadata;
+  semanticDocument: SemanticDocumentModel;
  features: ThemeFeature[];
  themeCss: string;
  exportConfig: ExportConfig;
@@ -48,6 +49,7 @@ export function createPagedDocumentPayload({
    articleHtml: document.articleHtml,
    fileName,
    metadata: document.metadata,
+    semanticDocument: document.semanticDocument,
    features: document.features,
    themeCss,
    exportConfig
@@ -96,6 +96,16 @@ export const docxMediaKindSchema = z.enum([

 export type DocxMediaKind = z.infer<typeof docxMediaKindSchema>;

+export const docxMediaAlignmentSchema = z.enum([
+  "left",
+  "center",
+  "right"
+]);
+
+export type DocxMediaAlignment = z.infer<
+  typeof docxMediaAlignmentSchema
+>;
+
 export const docxMediaCaptureTargetSchema = z.object({
  id: z.string().regex(/^docx-media-\d+$/u),
  kind: docxMediaKindSchema,
@@ -107,6 +117,7 @@ export const docxMediaCaptureTargetSchema = z.object({
    .max(MAXIMUM_DOCX_RESOURCE_COUNT),
  altText: z.string().max(1_000),
  caption: z.string().max(1_000).optional(),
+  alignment: docxMediaAlignmentSchema,
  displayWidthPx: z.number().positive().max(10_000),
  displayHeightPx: z.number().positive().max(10_000),
  captureX: z.number().int().nonnegative().max(100_000),
@@ -51,8 +51,8 @@ export const paperDimensionsMm: Record<
  A3: { width: 297, height: 420 },
  A4: { width: 210, height: 297 },
  A5: { width: 148, height: 210 },
-  Letter: { width: 216, height: 279 },
-  Legal: { width: 216, height: 356 }
+  Letter: { width: 215.9, height: 279.4 },
+  Legal: { width: 215.9, height: 355.6 }
 };

 const lengthSchema = z
@@ -114,6 +114,7 @@ const pageDecorationFontFamilySchema = z
 export const headerSchema = z.object({
  enabled: z.boolean(),
  height: lengthSchema,
+  showOnFirstPage: z.boolean().default(true),
  showDivider: z.boolean(),
  fontSize: lengthSchema,
  fontFamily: pageDecorationFontFamilySchema.default(
@@ -289,6 +290,7 @@ export const defaultExportConfig: ExportConfig = {
  header: {
    enabled: false,
    height: "8mm",
+    showOnFirstPage: true,
    showDivider: false,
    fontSize: "3mm",
    fontFamily: '"Segoe UI", "Microsoft YaHei", sans-serif',
@@ -60,6 +60,7 @@ export interface SemanticDocumentTextNode {
 export interface SemanticDocumentGroupNode {
  kind: "group";
  role: SemanticDocumentRole;
+  layout?: "space-between" | undefined;
  children: SemanticDocumentNode[];
 }

@@ -80,6 +81,7 @@ export const semanticDocumentNodeSchema: z.ZodType<
    z.object({
      kind: z.literal("group"),
      role: semanticDocumentRoleSchema,
+      layout: z.literal("space-between").optional(),
      children: z.array(semanticDocumentNodeSchema).min(1).max(30)
    })
  ])
@@ -41,6 +41,7 @@ describe("分页文档载荷", () => {
      articleHtml: document.articleHtml,
      fileName: "测试.md",
      metadata: document.metadata,
+      semanticDocument: document.semanticDocument,
      features: document.features,
      themeCss: "#write { color: #333; }",
      exportConfig: defaultExportConfig
@@ -129,6 +129,7 @@ describe("DOCX 共享协议", () => {
            kindOrdinal: 1,
            altText: "流程图",
            caption: "处理流程",
+            alignment: "center",
            displayWidthPx: 640,
            displayHeightPx: 320,
            captureX: 20,
@@ -151,6 +152,7 @@ describe("DOCX 共享协议", () => {
            ordinal: 1,
            kindOrdinal: 1,
            altText: "",
+            alignment: "center",
            displayWidthPx: 100,
            displayHeightPx: 100,
            captureX: 0,
@@ -27,8 +27,23 @@ describe("导出配置", () => {
      A3: { width: 297, height: 420 },
      A4: { width: 210, height: 297 },
      A5: { width: 148, height: 210 },
-      Letter: { width: 216, height: 279 },
-      Legal: { width: 216, height: 356 }
+      Letter: { width: 215.9, height: 279.4 },
+      Legal: { width: 215.9, height: 355.6 }
+    });
+  });
+
+  it("保持英制纸张的标准尺寸精度", () => {
+    expect(getPaperDimensionsMm("Letter", "portrait")).toEqual({
+      width: 215.9,
+      height: 279.4
+    });
+    expect(getPaperDimensionsMm("Letter", "landscape")).toEqual({
+      width: 279.4,
+      height: 215.9
+    });
+    expect(getPaperDimensionsMm("Legal", "portrait")).toEqual({
+      width: 215.9,
+      height: 355.6
    });
  });

@@ -51,7 +66,8 @@ describe("导出配置", () => {

  it("提供可由主题推荐的页眉和页码配置", () => {
    expect(defaultExportConfig.header).toMatchObject({
-      fontFamily: '"Segoe UI", "Microsoft YaHei", sans-serif'
+      fontFamily: '"Segoe UI", "Microsoft YaHei", sans-serif',
+      showOnFirstPage: true
    });
    expect(defaultExportConfig.footer).toMatchObject({
      fontFamily: '"Segoe UI", "Microsoft YaHei", sans-serif',
@@ -65,7 +81,8 @@ describe("导出配置", () => {
      pageDecorationsMode: undefined,
      header: {
        ...defaultExportConfig.header,
-        fontFamily: undefined
+        fontFamily: undefined,
+        showOnFirstPage: undefined
      },
      footer: {
        ...defaultExportConfig.footer,
@@ -76,10 +93,29 @@ describe("导出配置", () => {

    expect(parsedLegacyV4.pageDecorationsMode).toBe("theme");
    expect(parsedLegacyV4.header.fontFamily).toContain("Microsoft YaHei");
+    expect(parsedLegacyV4.header.showOnFirstPage).toBe(true);
    expect(parsedLegacyV4.footer.fontFamily).toContain("Microsoft YaHei");
    expect(parsedLegacyV4.footer.showOnFirstPage).toBe(true);
  });

+  it("允许页眉和页码独立控制正文首页可见性", () => {
+    const parsed = exportConfigSchema.parse({
+      ...defaultExportConfig,
+      header: {
+        ...defaultExportConfig.header,
+        enabled: true,
+        showOnFirstPage: false
+      },
+      footer: {
+        ...defaultExportConfig.footer,
+        showOnFirstPage: true
+      }
+    });
+
+    expect(parsed.header.showOnFirstPage).toBe(false);
+    expect(parsed.footer.showOnFirstPage).toBe(true);
+  });
+
  it("支持公文页码格式和奇偶页外侧对齐", () => {
    expect(
      exportConfigSchema.safeParse({
@@ -27,6 +27,7 @@ describe("主题清单", () => {
        header: {
          enabled: false,
          height: "8mm",
+          showOnFirstPage: false,
          showDivider: false,
          fontSize: "4.94mm",
          fontFamily: '"Mdpdf Fandol Song", SimSun, serif',
@@ -56,6 +57,44 @@ describe("主题清单", () => {
      format: "official-page",
      showOnFirstPage: false
    });
+    expect(parsed.pageDefaults?.header.showOnFirstPage).toBe(false);
+  });
+
+  it("为旧主题的页眉首页策略补齐兼容默认值", () => {
+    const parsed = themeManifestSchema.parse({
+      manifestVersion: 1,
+      id: "legacy-header-test",
+      name: "旧主题页眉测试",
+      version: "0.5.1",
+      description: "验证未声明首页策略的旧主题。",
+      author: "md-to-pdf contributors",
+      license: "项目自有",
+      entry: "theme.css",
+      domPreset: "generic",
+      defaultFontSize: "16px",
+      supportedFeatures: [],
+      pageDefaults: {
+        margins: {
+          top: "16mm",
+          right: "16mm",
+          bottom: "16mm",
+          left: "16mm"
+        },
+        header: {
+          enabled: true,
+          height: "8mm",
+          showDivider: false,
+          fontSize: "3mm",
+          color: "#000000",
+          left: { enabled: false, content: "" },
+          center: { enabled: true, content: "${title}" },
+          right: { enabled: false, content: "" }
+        }
+      },
+      bundled: true
+    });
+
+    expect(parsed.pageDefaults?.header?.showOnFirstPage).toBe(true);
  });

  it("允许声明可嵌入的本地 DOCX 字体字形面", () => {