DOCX 中的自定义页面布局

Available in Start planBetav0.13.0

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

页面尺寸配置

使用 pageSize 选项定义导出 DOCX 文件的自定义页面尺寸。页面尺寸配置支持带有各种度量单位的宽度和高度值。

支持的单位

所有页面尺寸和边距测量均支持以下通用单位：

Unit	Description
`cm`	厘米（默认）
`in`	英寸
`pt`	磅
`pc`	皮卡
`mm`	毫米
`px`	像素

配置选项

Property	Type	Description	Default
`width`	`PositiveUniversalMeasure`	页面宽度。必须为正值	`"21.0cm"`（A4 宽度）
`height`	`PositiveUniversalMeasure`	页面高度。必须为正值	`"29.7cm"`（A4 高度）

PositiveUniversalMeasure

PositiveUniversalMeasure 是一个表示带单位的正长度的字符串，例如 "21cm"、"8.5in"、"148mm"、"595pt"、"50pc" 或 "800px"。支持的单位包括厘米（cm）、毫米（mm）、英寸（in）、磅（pt）、皮卡（pc）和像素（px）。该值必须大于零。如果您提供的值不带单位，默认会使用厘米（cm）。

ExportDocx.configure({
  onCompleteExport: (result) => {
    // 处理导出的文件
  },
  pageSize: {
    width: '14.8cm', // A5 宽度
    height: '21cm', // A5 高度
  },
})

页面边距配置

pageMargins 选项允许您为文档页面的各个边设置自定义边距。与页面尺寸不同，边距可以接受负值（如有需要）。

配置选项

Property	Type	Description	Default
`top`	`UniversalMeasure`	页面顶部边距。可以为负值。	`"1.0cm"`
`bottom`	`UniversalMeasure`	页面底部边距。可以为负值。	`"1.0cm"`
`left`	`PositiveUniversalMeasure`	页面左边距。必须为正值。	`"1.0cm"`
`right`	`PositiveUniversalMeasure`	页面右边距。必须为正值。	`"1.0cm"`
`header`	`PositiveUniversalMeasure`	从页面顶部边缘到页眉顶部的距离。应小于 `top`，这样页眉才能位于正文内容上方。	Word 默认值 `"1.25cm"`
`footer`	`PositiveUniversalMeasure`	从页面底部边缘到底部页脚的距离。应小于 `bottom`，这样页脚才能位于正文内容下方。	Word 默认值 `"1.25cm"`

UniversalMeasure

UniversalMeasure 是一个表示带单位长度的字符串，例如 "21cm"、"8.5in"、 "148mm"、"595pt"、"50pc" 或 "800px"。支持的单位包括厘米（cm）、毫米（mm）、英寸（in）、磅（pt）、皮卡（pc）和像素（px）。该值可以为正或负。如果您提供的值不带单位，默认会使用厘米（cm）。

PositiveUniversalMeasure

ExportDocx.configure({
  onCompleteExport: (result) => {
    // 处理导出的文件
  },
  pageMargins: {
    top: '2cm',
    bottom: '2cm',
    left: '1.5cm',
    right: '1.5cm',
    // 页面边缘到页眉/页脚的距离
    header: '1cm',
    footer: '1cm',
  },
})

页眉和页脚偏移

pageMargins 上的 header 和 footer 属性控制页眉和页脚距离页面顶部和底部边缘的距离。它们会直接映射到 Word 的“页面设置 → 布局”中的“页眉距顶端”和“页脚距底端”设置。

为了让页眉显示在正文上方，header 应小于 top。footer 与 bottom 之间也适用同样的关系。若未指定，Word 将使用其默认值 1.25cm（约 0.5in）。

ExportDocx.configure({
  onCompleteExport: (result) => {
    // 处理导出的文件
  },
  pageMargins: {
    top: '2.5cm',
    bottom: '2.5cm',
    left: '2cm',
    right: '2cm',
    // 页眉距离页面顶部 1cm（位于 2.5cm 的上边距之上）
    header: '1cm',
    // 页脚距离页面底部 1cm（位于 2.5cm 的下边距之下）
    footer: '1cm',
  },
})

由 Pages 扩展自动推导

当 Pages 扩展与 ExportDocx 一起配置时，header 和 footer 偏移会自动根据 Pages 存储中的 headerTopMargin 和 footerBottomMargin 推导得出。您传递给 pageMargins 的值始终具有优先级——如需覆盖自动推导的值，请显式设置 header 或 footer。

完整示例

以下为一个完整示例，演示如何使用 DOCX Export 扩展配置自定义页面布局：

import { ExportDocx } from '@tiptap-pro/extension-export-docx'

const editor = new Editor({
  extensions: [
    // 其他扩展...
    ExportDocx.configure({
      onCompleteExport: (result) => {
        // 创建并下载 DOCX 文件
        const blob = new Blob([result], {
          type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
        })
        const url = URL.createObjectURL(blob)
        const a = document.createElement('a')

        a.href = url
        a.download = 'custom-layout.docx'
        a.click()
        URL.revokeObjectURL(url)
      },
      // A5 页面尺寸
      pageSize: {
        width: '14.8cm',
        height: '21cm',
      },
      // 自定义边距
      pageMargins: {
        top: '2cm',
        bottom: '2cm',
        left: '2cm',
        right: '2cm',
      },
    }),
    // 其他扩展...
  ],
})

常用页面尺寸

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

Format	Width	Height
A4	`21.0cm`	`29.7cm`
A5	`14.8cm`	`21.0cm`
Letter	`8.5in`	`11in`
Legal	`8.5in`	`14in`
Tabloid	`11in`	`17in`

不同的测量单位

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

ExportDocx.configure({
  onCompleteExport: (result) => {
    // 处理导出的文件
  },
  // 美式 Letter 尺寸，单位为英寸
  pageSize: {
    width: '8.5in',
    height: '11in',
  },
  // 混合单位的边距
  pageMargins: {
    top: '0.75in', // 英寸
    bottom: '72pt', // 磅（1 英寸 = 72 磅）
    left: '2cm', // 厘米
    right: '20mm', // 毫米
  },
})

单位一致性

虽然您可以混合使用不同单位，但通常建议在整个配置中使用一致的单位，以便更易于维护和理解。

运行时配置

您还可以在直接调用导出命令时覆盖页面布局设置：

// 使用不同的页面布局设置导出
editor.commands.exportDocx({
  onCompleteExport: (result) => {
    // 处理导出的文件
  },
  pageSize: {
    width: '11in', // Tabloid 宽度
    height: '17in', // Tabloid 高度
  },
  pageMargins: {
    top: '0.5in',
    bottom: '0.5in',
    left: '0.75in',
    right: '0.75in',
  },
})

这可以让您针对不同场景创建不同的导出配置，无需重新配置整个扩展。

Previously分页符

Next upPDF