---
title: "从零开始到打印就绪：Pages 与 DOCX 导出"
description: "使用 Tiptap、Pages 和 DOCX 导出构建打印就绪编辑器的分步指南。"
canonical_url: "https://tiptap.zhcndoc.com/pages/guides/zero-to-print-ready"
---

# 从零开始到打印就绪：Pages 与 DOCX 导出

使用 Tiptap、Pages 和 DOCX 导出构建打印就绪编辑器的分步指南。

本指南将带你从零开始搭建一个 Tiptap 编辑器，使用 Pages 扩展实现分页、类似印刷的版式，并支持 DOCX 导入导出，以便构建专业、可直接印刷的工作流。

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

---

## 1. 安装 Pages 技术栈

安装这三个始终会一起使用的 Pro 包，当你使用 Pages 构建时需要它们：

```bash
npm install @tiptap-pro/extension-convert-kit \
            @tiptap-pro/extension-pages-tablekit \
            @tiptap-pro/extension-pages
```

> **为什么是这三个包:**
>
> `@tiptap-pro/extension-convert-kit` 提供编辑器的节点和标记 schema（段落、
> 标题、列表、图片、标记）。`@tiptap-pro/extension-pages-tablekit` 提供分页安全
> 的表格，这是必需的，因为 ConvertKit 内置的表格并不是为分页设计的。
> `@tiptap-pro/extension-pages` 提供页面布局本身。请先确保你已经通过身份验证，
> 登录到 Tiptap 私有 npm registry；设置方法请参见 [Pro Extensions 指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md)。

## 2. 使用 Pages 设置你的编辑器

```ts
import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'
import { Pages } from '@tiptap-pro/extension-pages'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({
      pageFormat: 'A4',
      pageGap: 40,
      header: '我的项目',
      footer: '第 {page} 页，共 {total} 页',
      pageGapBackground: '#f8f8f8',
    }),
  ],
})
```

> **最佳实践:**
>
> 尽早在你的设置中添加 Pages，这样文档结构和布局从一开始就是一致的。
> 你之后可以通过命令更改页面格式、页眉和页脚；但如果某个文档在创建时没有考虑分页，
> 再补加 Pages 会更困难。

## 3. 添加 DOCX 导出能力

安装 DOCX 导出扩展：

```bash
npm install @tiptap-pro/extension-export-docx
```

将其添加到你的编辑器：

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

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({
      /* ... */
    }),
    ExportDocx,
  ],
})
```

### 3a. 配置 DOCX 导出

DOCX 导出扩展完全在浏览器中运行：不需要 JWT、不需要 App ID，也不需要服务器调用。你可以通过 `onCompleteExport` 回调进行配置，该回调会接收导出结果：

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

ExportDocx.configure({
  // 必需。导出的文件会通过这个回调传递。
  onCompleteExport: (result) => {
    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 = 'document.docx'
    a.click()
    URL.revokeObjectURL(url)
  },
  // 可选：'blob'（默认）、'buffer'、'string' 等。
  exportType: 'blob',
  // 可选：覆盖段落、标题、表格样式等。
  styleOverrides: {},
  // 可选：为你添加的任何自定义 Tiptap 节点定义 DOCX 序列化。
  customNodes: [],
})
```

> **必需项:**
>
> `onCompleteExport` 是必需的。导出不会直接返回结果；它会把结果交给你的
> 回调，由你来下载、上传或处理。

## 4. 导出你的文档

从编辑器的命令链触发导出：

```ts
editor.commands.exportDocx()
```

> **往返并不完全字节一致:**
>
> DOCX 导出是忠实的，但不是无损的。有少数特性（下标/上标标记、段落
> 行高、浮动表格）在往返转换时并不完美。完整列表请参阅 [功能支持
> 矩阵](https://tiptap.zhcndoc.com/conversion/getting-started/feature-support-matrix.md)。

## 5. 将 DOCX 文件导入到你的编辑器中

添加导入扩展，这样用户就可以把 Word 文档加载到分页编辑器中：

```bash
npm install @tiptap-pro/extension-import-docx
```

```ts
import { ImportDocx } from '@tiptap-pro/extension-import-docx'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({
      /* ... */
    }),
    ExportDocx.configure({
      /* ... */
    }),
    ImportDocx.configure({
      token: 'YOUR_JWT', // 由你的服务器生成的 JWT
      // 可选：导入服务应将从文档中提取的图片上传到哪里
      // imageUploadConfig: { url: 'https://your-server.com/upload-image' },
    }),
  ],
})
```

要触发导入，请从 `<input type="file" />` 传入一个 `File`：

```ts
editor
  .chain()
  .importDocx({
    file,
    onImport(context) {
      if (context.error) {
        // 处理失败（提示、日志、重试等）
        return
      }
      context.setEditorContent(context.content)
    },
  })
  .run()
```

当导入的文档包含页眉和页脚时，Pages 扩展会自动识别它们；它们会在每个渲染页面的顶部和底部显示，无需额外配置。

> **Where to get your token:**
>
> 参见 [Conversion install guide](https://tiptap.zhcndoc.com/conversion/getting-started/install.md) 进行设置，以及
> [Authentication](https://tiptap.zhcndoc.com/authentication.md) 了解如何签名 token。请在服务端签名 token，且永远不要
> 在浏览器中暴露你的签名密钥。

---

## 接下来的步骤

- [Pages 选项](https://tiptap.zhcndoc.com/pages/core-concepts/options.md)：Pages 暴露的每个选项
- [页面页眉和页脚](https://tiptap.zhcndoc.com/pages/core-concepts/page-header-footer.md)：不同的首页、奇偶页、以编程方式打开/关闭编辑器
- [PagesTableKit](https://tiptap.zhcndoc.com/pages/guides/pages-tablekit.md)：详细介绍可分页安全的表格，包括最重要的已知限制
- [限制](https://tiptap.zhcndoc.com/pages/core-concepts/limitations.md)：不可拆分内容、Pages 不做什么，以及如何在每种情况下规避

> **需要帮助吗？:**
>
> 如果你遇到意料之外的问题，请联系支持团队，或者查看文档的其他部分以了解
> 高级工作流。