---
title: "DOCX 中的自定义页面布局"
description: "了解如何使用导出扩展来自定义您的 DOCX（Word）页面和页边距大小。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/export/docx/page-layout"
---

# DOCX 中的自定义页面布局

了解如何使用导出扩展来自定义您的 DOCX（Word）页面和页边距大小。

- **1. 激活试用或订阅**

  在您的账户中开始 [免费试用](https://cloud.tiptap.dev/v2?trial=true) 或 [订阅 Start
  套餐](https://cloud.tiptap.dev/v2/billing)。
- **2. 从私有注册表安装**

  要安装此前端扩展，请按照 [设置指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md) 通过身份验证访问 Tiptap 的私有 npm 注册表。

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

> **Interactive demo:** [ExportDocxCustomPageSize](https://embed-pro.tiptap.dev/preview/Extensions/ExportDocxCustomPageSize)

## 页面尺寸配置

使用 `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`）。

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

```js
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）。

```js
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 扩展](https://tiptap.zhcndoc.com/editor/extensions/functionality/pages.md) 与 `ExportDocx` 一同配置时，
> `header` 和 `footer` 偏移量会根据 Pages 存储中的 `headerTopMargin` 和 `footerBottomMargin`
> 自动推导。您传递给 `pageMargins` 的值始终具有优先级；如需覆盖自动推导的值，请显式设置 `header` 或
> `footer`。

## 页面背景颜色

使用 `pageColor` 选项为导出文档中的每一页设置背景颜色。

### 接受的格式

| 格式        | 示例                                         |
| --------- | ------------------------------------------ |
| 十六进制（6 位） | `"#ff0000"`、`"FF0000"`                     |
| 十六进制（3 位） | `"#f00"`                                   |
| `rgb()`   | `"rgb(255, 0, 0)"`                         |
| `rgba()`  | `"rgba(255, 0, 0, 0.5)"`                   |
| 命名颜色      | 常见的 CSS 命名颜色（`"red"`、`"blue"`、`"green"` 等） |

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

```js
ExportDocx.configure({
  onCompleteExport: (result) => {
    // 处理导出的文件
  },
  pageColor: '#fff8dc', // 玉米丝风格的奶油色页面
})
```

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

## 完整示例

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

```js
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',
      },
      // 页面背景颜色
      pageColor: '#fff8dc',
    }),
    // 其他扩展...
  ],
})
```

## 常用页面尺寸

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

| 格式          | 宽度       | 高度       |
| ----------- | -------- | -------- |
| **A4**      | `21.0cm` | `29.7cm` |
| **A5**      | `14.8cm` | `21.0cm` |
| **Letter**  | `8.5in`  | `11in`   |
| **Legal**   | `8.5in`  | `14in`   |
| **Tabloid** | `11in`   | `17in`   |

## 不同的测量单位

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

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

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

## 运行时配置

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

```js
// 使用不同的页面布局设置导出
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',
  },
  pageColor: 'gray', // 覆盖此次导出的已配置页面颜色
})
```

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