pretty-tables

在 Word 文档中创建美观的表格，确保其在 Microsoft Word 和 Google Docs 中均能一致、稳定地渲染。

⚠️ 五大关键规则

经过大量测试验证，以下模式是实现跨平台（Word / Google Docs）正确渲染表格的必备条件：

1. 双重宽度设置（最重要）

每个表格必须在两个位置同时设置宽度：表格层级本身，以及每个独立单元格：

// 表格层级
new Table({
  width: { size: 9360, type: WidthType.DXA },  // 总宽度
  columnWidths: [1872, 7488],                   // 各列宽度
  rows: [...]
})

// 单元格层级 — 每个单元格都必须设置！
new TableCell({
  width: { size: 1872, type: WidthType.DXA },   // 该单元格的宽度
  children: [...]
})

若任一位置缺失宽度定义，表格将在部分平台中渲染异常。

2. 仅使用 DXA，禁用百分比

百分比单位在 Google Docs 中不被支持。请始终使用 DXA（twips）单位：

• 1 英寸 = 1440 DXA
• US Letter 纸张（8.5 英寸宽），页边距为 1 英寸时，内容区可用宽度为 9360 DXA

// ❌ 错误 — 在 Google Docs 中失效
width: { size: 100, type: WidthType.PERCENTAGE }

// ✅ 正确
width: { size: 9360, type: WidthType.DXA }

3. 使用 ShadingType.CLEAR，而非 SOLID

这是一个细微但极其关键的陷阱：

const { ShadingType } = require('docx');

// ❌ 错误 — 将导致黑色背景
shading: { type: ShadingType.SOLID, fill: "E0F2F1" }

// ✅ 正确 — 可正常应用填充色
shading: { type: ShadingType.CLEAR, fill: "E0F2F1" }

4. 设置单元格内边距（Margins）

避免文字紧贴边框，提升可读性：

const cellMargins = { top: 80, bottom: 80, left: 120, right: 120 };

new TableCell({
  children: [...],
  margins: cellMargins
})

5. 列宽总和必须精确匹配

对于 US Letter 纸张 + 1 英寸页边距：总宽度必须为 9360 DXA

// 2 列：20% + 80%
columnWidths: [1872, 7488]  // = 9360 ✓

// 3 列：等宽
columnWidths: [3120, 3120, 3120]  // = 9360 ✓

// 3 列：25% + 25% + 50%
columnWidths: [2340, 2340, 4680]  // = 9360 ✓

完整可运行示例

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, 
         WidthType, AlignmentType, BorderStyle, TableLayoutType, ShadingType } = require('docx');
const fs = require('fs');

// 常量定义
const TOTAL_WIDTH = 9360;  // US Letter，1 英寸页边距下的内容区宽度
const TIME_COL = 1872;     // 20%
const CONTENT_COL = 7488;  // 80%

// 浅灰色边框
const cellBorders = {
  top: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" },
  bottom: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" },
  left: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" },
  right: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" }
};

// 单元格内边距
const cellMargins = { top: 80, bottom: 80, left: 120, right: 120 };

// 表格构造辅助函数
function table(columnWidths, rows) {
  return new Table({
    layout: TableLayoutType.FIXED,
    width: { size: columnWidths.reduce((a, b) => a + b, 0), type: WidthType.DXA },
    columnWidths: columnWidths,
    rows: rows
  });
}

// 表头行
function headerRow(text, color) {
  return new TableRow({
    children: [
      new TableCell({
        children: [new Paragraph({ 
          children: [new TextRun({ text, bold: true, size: 32, color: "FFFFFF" })],
          alignment: AlignmentType.CENTER
        })],
        width: { size: TIME_COL + CONTENT_COL, type: WidthType.DXA },
        columnSpan: 2,
        shading: { type: ShadingType.CLEAR, fill: color },
        borders: cellBorders,
        margins: cellMargins
      })
    ]
  });
}

// 数据行
function dataRow(time, activity, color) {
  return new TableRow({
    children: [
      new TableCell({
        children: [new Paragraph({ 
          children: [new TextRun({ text: time, bold: true, size: 26, color })],
          alignment: AlignmentType.CENTER
        })],
        width: { size: TIME_COL, type: WidthType.DXA },
        borders: cellBorders,
        margins: cellMargins
      }),
      new TableCell({
        children: [new Paragraph({ 
          children: [new TextRun({ text: activity, size: 26 })]
        })],
        width: { size: CONTENT_COL, type: WidthType.DXA },
        borders: cellBorders,
        margins: cellMargins
      })
    ]
  });
}

// 构建文档
const doc = new Document({
  sections: [{
    properties: { 
      page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } }
    },
    children: [
      table([TIME_COL, CONTENT_COL], [
        headerRow("SCHEDULE", "1565C0"),
        dataRow("9:00 AM", "Arrive at destination", "1565C0"),
        dataRow("10:00 AM", "Morning activity", "1565C0"),
        dataRow("12:00 PM", "Lunch break", "1565C0"),
      ])
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync('output.docx', buffer);
});

列宽速查表

针对 US Letter（8.5 英寸），1 英寸页边距 → 总宽度 = 9360 DXA：

常见错误

❌ 遗漏单元格宽度：

new TableCell({ children: [...] })  // 未设置 width！

❌ 使用百分比单位：

width: { size: 100, type: WidthType.PERCENTAGE }  // 在 Google Docs 中失效

❌ 错误的阴影类型：

shading: { type: ShadingType.SOLID, fill: "E0F2F1" }  // 导致黑色背景！

❌ 列宽总和不匹配：

columnWidths: [2000, 7000]  // = 9000，非 9360

✅ 正确写法：

new TableCell({
  width: { size: 1872, type: WidthType.DXA },
  shading: { type: ShadingType.CLEAR, fill: "E0F2F1" },
  margins: { top: 80, bottom: 80, left: 120, right: 120 },
  borders: cellBorders,
  children: [...]
})

配色方案

表头颜色：

浅色背景：

原理说明

以下四要素协同作用：

1. 表格与单元格均采用精确 DXA 宽度
2. 使用 ShadingType.CLEAR 实现正确着色
3. 统一的内边距设置保障可读性
4. 列宽总和严格等于表格总宽度

……即可确保表格在 Microsoft Word、Google Docs 及其他 DOCX 查看器中均能正确渲染。

问题排查

Q：表格在 Google Docs 中显示过窄

• 确认使用的是 WidthType.DXA，而非 PERCENTAGE
• 检查每个 TableCell 是否均已设置 width 属性

Q：单元格背景为黑色

• 将 ShadingType.SOLID 改为 ShadingType.CLEAR

Q：文字紧贴边框

• 为每个单元格添加 margins: { top: 80, bottom: 80, left: 120, right: 120 }

Q：列宽不均匀

• 验证各列宽度之和是否严格等于表格总宽度（1 英寸页边距下为 9360）