DOC 中的自定义页面布局

Available in Start planBetav0.6.1

DOC 导出扩展支持自定义页面尺寸和边距，允许您创建符合需求的精确布局文档。无论您需要 A5 页面、自定义纸张大小，还是特定的边距配置，都可以直接在扩展中进行设置。

建议改用 DOCX

DOC 格式是 Microsoft Word 97-2003 的一种旧式格式。对于现代使用场景，我们建议改为导出为 DOCX。只有在与旧系统的兼容性要求下，才使用 DOC。

页面尺寸配置

使用 pageSize 选项为导出的 DOC 文件定义自定义页面尺寸。页面尺寸配置接受多种度量单位的宽度和高度值。

支持的单位

所有页面尺寸和边距的度量单位支持以下单位：

单位	描述
`cm`	厘米（默认）
`in`	英寸
`pt`	磅
`pc`	派卡
`mm`	毫米
`px`	像素

配置选项

属性	类型	描述	默认值
`width`	`string`	页面宽度。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"21cm"`
`height`	`string`	页面高度。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"29.7cm"`

import { ExportDoc } from '@tiptap-pro/extension-export-doc'

ExportDoc.configure({
  token: 'YOUR_TOKEN',
  pageSize: {
    width: '14.8cm', // A5 宽度
    height: '21cm', // A5 高度
  },
})

页面边距配置

pageMargins 选项允许您为文档页面的所有边距设置自定义值。与页面尺寸不同，顶部和底部边距可以是负值。

配置选项

Property	Type	Description	Default
`top`	`string`	页面顶部边距。可以为负值。必须是一个数值，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`bottom`	`string`	页面底部边距。可以为负值。必须是一个数值，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`left`	`string`	页面左边距。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`right`	`string`	页面右边距。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`header`	`string`	从页面上边缘到页眉顶部的距离。应小于 `top`。必须是一个带单位的正数。	`"1.25cm"`
`footer`	`string`	从页面下边缘到页脚底部的距离。应小于 `bottom`。必须是一个带单位的正数。	`"1.25cm"`

import { ExportDoc } from '@tiptap-pro/extension-export-doc'

ExportDoc.configure({
  token: 'YOUR_TOKEN',
  pageMargins: {
    top: '2cm',
    bottom: '2cm',
    left: '1.5cm',
    right: '1.5cm',
    // 从页面边缘到页眉/页脚的距离
    header: '1cm',
    footer: '1cm',
  },
})

由 Pages 扩展自动推导

当 Pages 扩展与 ExportDoc 一同配置时，header 和 footer 偏移量会自动根据 Pages 存储中的 headerTopMargin 和 footerBottomMargin 值推导得出。你传递给 pageMargins 的值始终具有优先级。

转换服务要求

对 pageMargins.header 和 pageMargins.footer 的端到端支持，要求 Tiptap convert 服务版本能够接受这些字段，并且提供更新后的 @tiptap-pro/extension-export-docx。在较旧的 convert 服务版本中，这些值会被忽略，并使用 Word 的默认值。

页面背景色

使用 pageColor 选项为导出的 DOC 的每一页设置背景色。

支持的格式

格式	示例
Hex（6 位）	`"#ff0000"`
Hex（3 位）	`"#f00"`
`rgb()`	`"rgb(255, 0, 0)"`
`rgba()`	`"rgba(255, 0, 0, 0.5)"`
命名颜色	常见的 CSS 命名颜色（`"red"`、`"blue"`、`"green"`、…）

传入 "transparent"，或将 pageColor 留空以省略页面颜色。

ExportDoc.configure({
  token: 'YOUR_TOKEN',
  pageColor: '#fff8dc',
})

Word 默认不会打印页面背景

在 Microsoft Word 中，页面背景会显示在屏幕上，但在打印或导出为 PDF 时不会包含在内。要使其在打印输出或 PDF 导出时可见，读者必须在 Word 中启用 文件 → 选项 → 显示 → 打印背景色和图像。

完整示例

以下是一个完整示例，展示如何使用 DOC 导出扩展配置自定义页面布局：

import { ExportDoc } from '@tiptap-pro/extension-export-doc'

const editor = new Editor({
  extensions: [
    // 其他扩展...
    ExportDoc.configure({
      token: 'YOUR_TOKEN',
      // A5 页面大小
      pageSize: {
        width: '14.8cm',
        height: '21cm',
      },
      // 自定义边距
      pageMargins: {
        top: '2cm',
        bottom: '2cm',
        left: '2cm',
        right: '2cm',
      },
      // 页面背景色
      pageColor: '#fff8dc',
    }),
    // 其他扩展...
  ],
})

// 使用自定义布局导出
editor
  .chain()
  .exportDoc({
    onCompleteExport(result) {
      const url = URL.createObjectURL(result)
      const a = document.createElement('a')

      a.href = url
      a.download = 'custom-layout.doc'
      a.click()

      URL.revokeObjectURL(url)
    },
  })
  .run()

常见页面尺寸

以下是一些常用页面尺寸供参考：

格式	宽度	高度
A4	`21cm`	`29.7cm`
A5	`14.8cm`	`21cm`
Letter	`8.5in`	`11in`
Legal	`8.5in`	`14in`
Tabloid	`11in`	`17in`

不同的度量单位

你可以根据喜好混合使用不同的单位：

ExportDoc.configure({
  token: 'YOUR_TOKEN',
  // US Letter size in inches
  pageSize: {
    width: '8.5in',
    height: '11in',
  },
  // 边距使用不同单位
  pageMargins: {
    top: '0.75in', // 英寸
    bottom: '72pt', // 磅（1 英寸 = 72 磅）
    left: '2cm', // 厘米
    right: '20mm', // 毫米
  },
})

单位一致性

虽然你可以混合使用不同的单位，但通常建议在整个配置中保持单位一致，以便更好地维护和提高清晰度。