---
title: "页面结构"
description: "在整个 DOCX 转换流程中，如何处理分页、分节、页面大小、页边距和页码。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/content-types/page-layout/page-structure"
---

# 页面结构

在整个 DOCX 转换流程中，如何处理分页、分节、页面大小、页边距和页码。

页面结构涵盖控制内容如何跨页面流动的元素：分页符、节、页面大小、页边距和页码。分页符可在管道中完整往返。其他页面结构属性仅部分支持。

## 你需要了解的内容

- **扩展：** `@tiptap-pro/extension-pagebreak`（不在 StarterKit 中）以及用于分页布局的 [`Pages`](https://tiptap.zhcndoc.com/pages/getting-started/overview.md)
- **导出选项：** 导出扩展或 REST API 上的 `pageSize` 和 `pageMargins`
- **集成路径：** 通过 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md) 和 [REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md) 导入与导出都以相同方式工作。两种导出路径都接受 `pageSize` 和 `pageMargins`。

## 支持概览

| 功能   | 导入                                                                | 编辑器                                                                       | 导出                                                                                 |
| ---- | ----------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| 分页符  | 支持                                                                | 支持（PageBreak）                                                             | 支持                                                                                 |
| 页面大小 | 不支持                                                               | 支持（[Pages](https://tiptap.zhcndoc.com/pages/getting-started/overview.md)） | 支持（可配置）                                                                            |
| 页边距  | 不支持                                                               | 支持（Pages）                                                                 | 支持（可配置）                                                                            |
| 节    | 部分支持（会提取并应用栏配置）                                                   | 不支持                                                                       | 仅单节                                                                                |
| 页码   | 支持（PAGE/NUMPAGES → `{page}`/`{numpages}` 标记，见[下文](#page-numbers)） | 支持（通过页眉/页脚）                                                               | 仅编辑器扩展：页眉/页脚中的 `{page}`/`{total}` 标记会输出实时的 `PAGE`/`NUMPAGES` 域。REST API 导出会输出字面文本。 |
| 栏    | 导入时支持（会创建 columns/column 节点）                                      | 不支持                                                                       | 不支持                                                                                |

## 分页符

分页符可在管道中完整往返。详见专门的[分页符](https://tiptap.zhcndoc.com/conversion/content-types/page-layout/page-breaks.md)页面。

## 页面大小和页边距

DOCX 中的页面大小和页边距不会被导入。解析器会从节属性中读取它们，但 Tiptap 渲染器会丢弃这些信息。

[Pages 扩展](https://tiptap.zhcndoc.com/pages/getting-started/overview.md)提供带可配置页面大小和页边距的分页布局。配置详情请参见[页面格式指南](https://tiptap.zhcndoc.com/pages/core-concepts/page-format.md)。

导出扩展接受 `pageSize` 和 `pageMargins` 选项：

```ts
ExportDocx.configure({
  pageSize: {
    width: '21.0cm',
    height: '29.7cm',
  },
  pageMargins: {
    top: '2.54cm',
    bottom: '2.54cm',
    left: '3.17cm',
    right: '3.17cm',
  },
})
```

这些值支持 CSS 风格单位：`cm`、`in`、`pt`、`pc`、`mm`、`px`。默认值会生成带标准 Word 页边距的 A4 页面。

> **Pages 与导出之间不会自动同步:**
>
> 导出扩展不会自动从 Pages 扩展读取页面大小或页边距。如果你的编辑器使用自定义页面格式，请在导出配置中传入匹配的值。

## 节

Word 文档可以有多个节，每个节都有自己的页面布局属性（大小、方向、页边距、栏、页眉/页脚）。转换管道对节的支持是部分的：

- **导入：** 节边界用于检测多栏布局。多栏节会被包装为 `columns`/`column` Tiptap 节点。其他节级属性（大小、方向、页边距）会被解析，但不会应用。
- **编辑器：** Tiptap 没有节的概念，但栏节点可以原生渲染。
- **导出：** 生成单个节。无法创建纵向/横向混排或多节文档。

## 页码

Word 中的页码是页眉和页脚里的域代码（`PAGE`、`NUMPAGES`）。当安装了 Pages 扩展时（或者你显式启用它：在 [编辑器命令](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md#page-number-fields) 中设置 `placeholders: true`（或 `{ page?, total? }`），或者在 [REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md#page-number-fields) 中使用 `placeholders={}` 表单字段），导入会将它们转换为规范文本标记（`PAGE` 对应 `{page}`，`NUMPAGES` 对应 `{numpages}`）。导出时，[编辑器扩展](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) 会在页眉/页脚内容中输出 `{page}` / `{total}` 标记，并将其作为实时的 `PAGE` / `NUMPAGES` 域，这样 Word 就会在打印或重新分页时重新计算它们。REST API 导出也会进行同样的转换；传入 `placeholders: false` 可将这些标记保留为字面文本。

Pages 扩展默认识别 `{page}` 和 `{total}`；它**不**识别 `{numpages}`。若要让 Word 的 `NUMPAGES` 域在导入后于编辑器预览中实时渲染，请配置 `Pages.configure({ placeholders: { total: 'numpages' } })`。参见 [DOCX 导入 → page-number fields](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md#page-number-fields)。

## 可往返内容

| 功能   | 可往返？       | 说明                                                                                                                                                                 |
| ---- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 分页符  | 是          | 需要 `@tiptap-pro/extension-pagebreak`                                                                                                                               |
| 页面大小 | 否          | 编辑器（Pages）和导出需分别配置                                                                                                                                                 |
| 页面边距 | 否          | 编辑器（Pages）和导出需分别配置                                                                                                                                                 |
| 节    | 部分         | 列配置会保留；其他节属性不会保留                                                                                                                                                   |
| 页码   | 是（编辑器扩展导出） | Word `PAGE` / `NUMPAGES` ↔ `{page}` / `{numpages}`（Pages 中总页数的规范名称是 `{total}`；配置 `placeholders: { total: 'numpages' }` 以实现映射）。通过 REST API 重新导出不会转换这些标记；往返请使用编辑器扩展。 |
| 栏    | 部分         | 导入会创建栏节点；导出目前尚不会将其写回                                                                                                                                               |