Tiptap 中文文档

DOCX 编辑器

Available in Team plan

DOCX 编辑器模板是一款分页式、类似 Word 的文档编辑器。不同于连续画布编辑器，它将内容渲染在带有真实页边距的独立页面上，支持可编辑的页眉和页脚、脚注、手动分页，以及可配置的页面格式——随后导出忠实的 .docx 文件，并在编辑器旁边渲染实时的 Word 预览。

它建立在 Tiptap Pages 扩展和 Conversion DOCX/PDF 导出器之上，并由 Tiptap Collaboration 提供实时协作功能。

需要 Team 方案

DOCX 编辑器模板在生产环境中使用时，至少需要订阅 Team 方案。你可以在试用期内进行集成和测试。使用此模板需遵守我们的 服务条款 和 Pro 许可证。

概览

该模板将多个 Tiptap Pro 扩展组合成一种统一的文档编辑体验：

  • Pages — 分页、页面格式（尺寸、方向、页边距）、页眉和页脚、脚注，以及缩放。
  • Convert / Export DOCX — 将编辑器文档在浏览器中转换为真实的 Word .docx 文件。
  • Export PDF — 通过 Tiptap Conversion API 生成并排的 Word 预览。
  • Collaboration — 对正文、页眉、页脚和脚注进行实时多人协作编辑。

在此基础上，该模板还添加了类似 Word 的工具栏、文档设置侧边栏、可编辑的页眉/页脚覆盖层，以及一组让 Pages 交互更接近原生体验的小型兼容处理。

安装

你需要一个带有有效订阅或试用的 Tiptap 账户。请前往 cloud.tiptap.dev/register 创建一个。

适用于现有项目 

npx @tiptap/cli@latest add docx

适用于新项目 

npx @tiptap/cli@latest init docx

此模板需要进行样式和配置设置。

样式

我们对样式框架不持特定立场，因此你需要将其集成到你的设置中。请按照 样式设置指南 操作，以确保编辑器正确显示。

该模板附带 SCSS，因此请确保你的项目中已将 sass（以及 sass-embedded）作为开发依赖可用。

环境变量

DOCX 编辑器使用两项云服务：协作（用于实时编辑）和 转换（用于 PDF/Word 预览）。请为以下变量提供值。

协作

  • NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID — 你的协作（文档服务器）App ID。
  • NEXT_PUBLIC_TIPTAP_COLLAB_TOKEN — 用于访问协作服务的 JWT。
  • NEXT_PUBLIC_TIPTAP_COLLAB_DOC_PREFIX — (可选) 追加到每个文档名称前的前缀。
  • NEXT_PUBLIC_USE_JWT_TOKEN_API_ENDPOINT — (生产环境) 一个返回新签名 JWT 的 API 端点，而不是将静态 token 直接发送给客户端。

转换（PDF / Word 预览）

  • NEXT_PUBLIC_TIPTAP_CONVERSION_APP_ID — 你的转换 App ID（在客户端读取并传递给 PDF 导出器）。
  • TIPTAP_CONVERSION_SECRET — (仅服务器端) 用于 /api/convert/token 路由签名短期（10 分钟）JWT 的转换密钥，供预览使用。

以 NEXT_PUBLIC_ 为前缀的变量必须在客户端可用。根据你使用的框架，请使用相应的前缀：

  • Next.js: NEXT_PUBLIC_。例如，NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID。
  • Vite + React: VITE_。例如，VITE_TIPTAP_COLLAB_APP_ID。
  • 其他框架：请遵循你所用框架的规则，并将这些值接入 tiptap-collab-utils.ts。

生成 JWT

为了快速开始，你可以使用 Tiptap Cloud 账户中的示例 JWT，并将其存储 在 token 环境变量中。示例 JWT 仅在短时间内有效，不应在生产环境中使用。 在生产环境中，请实现一个在服务端生成 JWT 的 API 端点。 请参阅 JWT 身份验证 完整指南。

如果未配置协作，编辑器会显示设置提示，要求你设置 App ID 和 token（或 JWT 端点）。你也可以在 URL 后附加 ?noCollab=1，以便在本地测试时禁用协作。

用法

渲染 PageDocxEditor 组件。每个文档都是一个协作房间，因此请为每个文档传入唯一的 room ID。

import { PageDocxEditor } from '@/components/tiptap-templates/page-docx/components/page-docx-editor'
import initialContent from '@/components/tiptap-templates/page-docx/data/content.json'

export default function App() {
  return <PageDocxEditor room="contract-123" initialContent={initialContent} />
}

路由

该模板自带一个页面，其行为与演示完全一致：访问 /docx 会重定向到带有新生成 room ID 的 /docx/<room-id>，而 [slug] 路由会为该房间渲染编辑器，同时预加载字体选择器所使用的 Google Fonts。每个房间都是一个独立、持久化的协作文档。

属性

导出的 PageDocxEditor 组件接受以下属性：

属性类型描述
roomstring协作房间 ID。每个文档都应使用唯一的房间。如果省略，则会创建一个随机房间。
initialContentJSONContent首次打开该房间时注入文档的 Tiptap JSON。模板附带了一个示例 NDA。注入过程有保护机制，因此绝不会重复。
invertMenuboolean将工具栏渲染在屏幕底部而不是顶部。也可以通过 ?menu=invert 查询参数切换。默认为 false。
settingsStorageSettingsStorage用于侧边栏 UI 设置的持久化后端（页面格式、页眉/页脚设置、预览开关）。默认为 localStorage 适配器。参见 设置持久化。

功能

一个带有类似 Word 工具栏、文档设置和实时导出的完整分页文档编辑器。

  • 分页：内容跨真实页面流动，支持可配置的页面尺寸、方向和页边距。
  • 页眉和页脚：可按文档编辑，支持首页不同、奇偶页不同，可调整与页面边缘的距离，并支持动态页码字段。
  • 脚注：类似 Word 的脚注——正文中的引用，内容位于页脚上方的每页专用区域，并在自动编号的覆盖层中编辑。
  • 手动分页符：插入一个会消耗剩余页面空间并将后续内容推到下一页的分页符，行为与 Word 完全一致。
  • 文档设置：页面尺寸（20+ 预设以及自定义）、方向、页边距、单位、页间距和页面背景色。
  • 缩放与适配页面：40%–200% 预设，另有自动适配页面模式，可将页面缩放到可用宽度。
  • 字体族：分类、可搜索的字体选择器。Carlito（与 Calibri 兼容的度量匹配字体）是默认字体，也是嵌入导出的字体。
  • 有序列表编号：八种编号方案（十进制、字母、罗马数字、嵌套等），在屏幕上和导出文档中保持一致。
  • 富文本格式：标题、粗体/斜体/删除线/代码、文本颜色、链接、行内图片、项目符号列表、行距、文本对齐和字体大小。
  • DOCX 导出：一键下载真正的 .docx 文件，完全在浏览器中生成。
  • 实时 Word 预览：并排显示文档按 Word 排版后的 PDF 渲染结果，可按需刷新。
  • 实时协作：正文、页眉、页脚和脚注支持多用户实时编辑，并显示协作光标。
  • 深色和浅色模式：开箱即用的完整主题支持。
  • 响应式设计：支持移动端布局，包含全屏预览模式，以及会将额外控件折叠到菜单中的溢出工具栏。

分页和页面格式

页面几何由 Pages 扩展管理，并从文档设置侧边栏进行配置。你可以设置：

  • 页面尺寸 — A4、A5、A6、JIS B5、US Letter、US Legal、Executive、明信片、信封等，以及带明确宽度和高度的 自定义 尺寸。
  • 方向 — 纵向或横向。
  • 页边距 — 上、下、左、右，并可选“链接页边距”开关，使四边保持同步。
  • 单位 — cm、in、mm 或 px；所有输入都会重新格式化为所选单位。
  • 页间距 — 编辑器画布中页面之间的间距。
  • 页面背景色 — 默认透明，并提供一组预设颜色调色板。

在侧边栏中输入的设置会驱动实时编辑器；反过来，通过 Pages 扩展所做的更改（包括协作者的远程更改）也会回流到侧边栏并持久化保存。

页眉和页脚

双击任意页眉或页脚区域，或在侧边栏中打开 页眉和页脚 选项卡，即可在固定于实时页面上方的覆盖层中编辑它。示例文档附带一个页眉（文档标题 + 标志）和一个页脚（标签、“Confidential”，以及一个 {page} of {pages} 字段），以表格布局呈现。

支持的选项：

  • 首页不同 — 第 1 页使用不同的页眉/页脚。
  • 奇偶页不同 — 书籍式布局中交替显示不同的页眉/页脚。
  • 距页面边缘的距离 — 页眉距顶部的距离和页脚距底部的距离，使用文档单位（会限制在 Word 的范围内，默认约为 1.25 cm）。
  • 页码 — 插入当前页或总页数字段。它们在编辑器中显示为 {page} / {pages} 标记，并在导出时变为实时 Word 字段。

由于 Pages 会为每个变体（默认 / 首页 / 奇数页 / 偶数页）维护一个独立的内部编辑器，侧边栏还包含一个小型分页器，用于在当前文档可访问的变体之间切换。

脚注

脚注是 Pages 扩展的一项功能。从工具栏插入脚注（或使用键盘快捷键）后，正文中会放置一个带编号的引用，而脚注内容会在覆盖层编辑器中打开；渲染后的脚注位于其所在页面页脚上方的专用区域。导出时，DOCX 导出器会自动将这些内容提取为真正的 Word 脚注。

页面分隔符

手动分页符总会在分页符前留下一个空段落，并将光标落到其后的段落中——与 Word 处理手动分页符的方式一致。从尾随空段落中退格时，会先逐个删除相邻的分页符，然后再回到正常编辑。可通过工具栏插入分页符，或使用 Mod-Enter。

缩放

缩放控件提供 40% 到 200% 的预设，以及一个 适配页面 操作。默认情况下，编辑器处于自动模式，会将页面缩小以适应可用列宽，并在视口变大时再放大到 100%；选择预设会切换为固定的手动缩放。缩放通过 --zoom CSS 变量发布，因此通过门户渲染的覆盖层（例如页眉/页脚编辑器）也能一致地缩放。

导出和预览

  • DOCX 导出 会下载一个由 Export DOCX 扩展在浏览器中构建的 .docx 文件——无需与服务器往返。页面尺寸、页边距（包括页眉/页脚扩展）、背景色、有序列表编号和页码字段都会带入文档，Carlito 字体会被嵌入，并且编辑器 CSS 变量颜色会被规范化为固定的十六进制值，以确保文件在任何地方看起来都一样。
  • Word 预览 是同一文档的按需 PDF 渲染结果，显示在编辑器旁边（移动端为全屏）。它通过 Tiptap Conversion API 生成，使用来自 /api/convert/token 路由的短期令牌，然后借助 react-pdf 渲染。打开预览时、页面布局变化时，以及文档有未保存更改时可通过 更新预览 按钮刷新预览。

实时协作

正文绑定到一个 TiptapCollabProvider 文档，而每个页眉/页脚变体以及脚注内容也通过各自的协作字段进行同步。协作光标仅显示在正文中（内部编辑器有意转发内容同步但不转发光标，以避免在共享 provider 上出现重复光标）。默认页眉/页脚外壳和初始正文内容仅在每个房间中注入一次，并以 provider 已同步为前提进行控制，这样返回同一房间时会保留之前编辑的内容。

设置持久化

侧边栏 UI 设置（页面格式、页眉/页脚设置以及预览切换）按房间持久化保存。默认情况下，它们存储在 localStorage 中的房间作用域键下。后端可通过 settingsStorage 属性和 SettingsStorage 适配器接口进行插拔：

interface SettingsStorage {
  get<T = unknown>(key: string): T | null
  set<T = unknown>(key: string, value: T): void
  remove(key: string): void
}

传入 noopStorage 可完全禁用持久化，或者实现该接口以将设置持久化到你自己的后端（例如，以文档为键的数据库）。

组件拆解

该模板由其自身的组件、hooks 和库组成，并建立在一组共享的 Tiptap UI 组件之上。

模板组件

  • page-docx-editor — 根组件：协作设置、编辑器实例、布局和效果。
  • page-docx-main-toolbar — 类似 Word 的工具栏，带有溢出处理。
  • page-docx-header-footer-overlay — 悬停在页眉/页脚区域上方的浮动“编辑”入口。
  • page-docx-pdf-preview — react-pdf 的 Word 预览面板。
  • page-docx-loading-overlay、floating、theme-toggle — 辅助 UI。
  • sidebar/* — 文档和页眉/页脚设置面板、页脚分页，以及设置面板原语。
  • zoom-dropdown-menu、font-family-combobox、numbering-format-dropdown-menu — 专用的工具栏控件。

Hooks

  • use-page-editor-state — 从 Pages 存储中派生页面状态（活动编辑器类型、页数、当前页、页眉/页脚标志）。
  • use-zoom、use-auto-export、use-page-docx-export、use-page-docx-insert-actions — 缩放、脏状态跟踪、DOCX/PDF 导出操作，以及工具栏插入操作（脚注 / 分页符 / 图片）。
  • use-overlay-focus、use-overlay-labels、use-mobile-typography-guard — 覆盖层行为和布局辅助工具。实时元素矩形跟踪来自共享的 use-bounding-rect hook。

Lib

  • page-docx-utils、page-docx-pages — 单位/转换、页面格式辅助工具，以及设置同步。
  • page-docx-export、page-docx-export-colors、page-docx-fonts — 导出布局/样式、颜色归一化，以及字体注册表。
  • settings-storage、settings-storage-context — 可插拔的持久化适配器及其 React 上下文。

扩展和变通方案

  • extensions/extension-page-token-highlight — 行内 {page} / {pages} 页码节点及其 DOCX 适配器。
  • workaround/page-break、workaround/header-footer、workaround/footnote — 一些小而注释充分的补丁，使 Pages 交互（光标定位、覆盖层聚焦与滚动、脚注滚动到视图）表现得像桌面文字处理器一样。

Tiptap Pro 扩展

  • @tiptap-pro/extension-pages
  • @tiptap-pro/extension-convert-kit
  • @tiptap-pro/extension-export-docx
  • @tiptap-pro/extension-export-pdf
  • @tiptap-pro/extension-pagebreak
  • @tiptap-pro/provider

复用的 UI 组件

工具栏和侧边栏复用了开源 UI 组件，包括 mark-button、list-button、heading-button / heading-dropdown-menu、text-button、font-size-dropdown-menu、line-spacing-dropdown-menu、text-align-dropdown-menu、color-text-popover 和 link-popover，以及 button、card、combobox、dropdown-menu、popover、sidebar 和 toolbar 原语。

许可证

DOCX Editor 模板使用 Tiptap Pro 扩展，并且需要有效的 团队方案（或更高级别）订阅。使用须遵守 Tiptap Pro 许可证 和 服务条款。其所依赖的开源 UI 组件仍采用 MIT 许可证。

Previously类 Notion 编辑器