SuperDoc DOCX编辑器5分钟快速上手:3行代码实现Word在线编辑与导出
SuperDoc DOCX编辑器5分钟快速上手:3行代码实现Word在线编辑与导出
SuperDoc DOCX 编辑器是一款开源的浏览器端 DOCX 在线编辑引擎:无需后端服务,只需 3 行代码即可在网页中打开 Word 文档,编辑完成后再一键导出 DOCX 文件。本文带你用 5 分钟走完完整上手流程——安装、打开文档、在线编辑、导出 Word 文件,并附官方示例项目与进阶玩法。
SuperDoc 是什么:一个 DOCX 原生的 Word 在线编辑器
SuperDoc 是一个直接构建在 OOXML 标准之上的文档引擎,核心理念是 "DOCX 原生":分页、节、页眉页脚、表格在浏览器里都保持 Word 文档的原始结构,编辑结果直接写回 XML,不经过 HTML 转换,所以格式不会"跑版"。
| 能力 | 说明 |
|---|---|
| 📄 浏览器打开 DOCX | 视图、编辑、建议、批注、修订跟踪一应俱全 |
| 🌐 零服务端依赖 | 编辑器直接在浏览器运行,无需自建服务器 |
| ⚡ 同一套 Document API | 浏览器端与 Node.js SDK、CLI、MCP 服务器共用一套接口 |
| 🤖 Agent 友好 | AI 智能体可调用标准文档操作,无需手工拼接 XML |
一键安装步骤:3 步装好 SuperDoc
第 1 步:准备 Node.js 22.12 或更高版本。
第 2 步:在你的前端项目(如 Vite)中安装核心包:
npm install superdoc
第 3 步:在页面准备两个容器,一个放工具栏、一个放编辑器:
<div id="superdoc-toolbar"></div>
<div id="superdoc"></div>
3 行核心代码:打开 Word 在线编辑
安装完成后,打开文档只需这几行 JavaScript:
import 'superdoc/style.css';
import { SuperDoc } from 'superdoc';
const superdoc = new SuperDoc({
selector: '#superdoc',
toolbar: '#superdoc-toolbar',
document: '/sample.docx',
documentMode: 'editing',
});
核心参数速查:
| 参数 | 作用 |
|---|---|
selector |
编辑器挂载的容器选择器 |
toolbar |
工具栏挂载的容器选择器 |
document |
文档 URL、File 或 Blob;省略则创建空白 DOCX |
documentMode |
文档模式,如 editing(编辑)、查看、建议 |
文档打开后即可直接在浏览器中打字、调整格式——这就是完整的 Word 在线编辑体验。完整示例可参考 examples/vanilla/src/main.ts。
一键导出 DOCX:拿回编辑后的 Word 文件
编辑完成后,调用 export() 即可把结果保存为标准 Word 文件:
await superdoc.export({ exportType: ['docx'], exportedName: 'sample-edited' });
两个细节值得注意:
export()会下载一个全新的 DOCX 文件,不会覆盖原文件,也不会把内容上传到任何服务器;- 由于编辑直接写回 OOXML,导出的文档在 Word 中打开时,标题、表格、签名栏等格式原样保留。
导出逻辑参考 examples/vanilla/src/main.ts,更多导出选项见 apps/docs/content/docs/editor/export-options.mdx。
5 分钟上手:跑一个官方示例项目
仓库内置了一批开箱即用的示例(目录总览见 examples/README.md),每个都是可独立运行的小项目。最快的体验路径是 vanilla 快速上手示例:
cd examples/vanilla
pnpm install
pnpm dev
浏览器打开后,文档就绪即可编辑文字,点击 Export DOCX 按钮,下载得到 sample-edited.docx,用 Word 打开验证修改与格式即可。
如果你更习惯 React 生态,examples/react/src/App.tsx 展示了如何用 <SuperDocEditor> 组件接管编辑器生命周期,封装源码在 packages/react/src/SuperDocEditor.tsx。
👉 官方图文版快速上手指南:apps/docs/content/docs/editor/quickstart.mdx
进阶玩法:在 VS Code 里直接编辑 Word
仓库还内置了一个 VS Code 扩展(apps/vscode-ext/README.md):点击任意 .docx 文件,即可在 IDE 中获得完整的 DOCX 渲染——分页、修订、批注、自动保存,全部可用,且文档不离开本机。
下一步学什么
- 编辑器配置(用户信息、文档模式等):apps/docs/content/docs/editor/configuration.mdx
- 文档模式切换(查看 / 编辑 / 建议):apps/docs/content/docs/editor/document-modes.mdx
- 多人实时协作示例:examples/collaboration/
- 更多示例(搜索、内容控件、版本历史、自定义 UI 等):examples/
- 获取完整开源代码:
git clone https://gitcode.com/gh_mirrors/sup/docx-editor
常见问题
Q:样式不生效、工具栏是"裸"的?
A:确认已 import 'superdoc/style.css',并且页面中存在工具栏与编辑器的两个容器。
Q:能打开用户本地选择的 .docx 吗?
A:可以,document 参数除了 URL 也接受 File 或 Blob,接一个 <input type="file"> 就能实现"本地文件在线编辑"。
Q:导出的是 Word 格式吗? A:是标准 DOCX(OOXML),可直接用 Microsoft Word 打开,格式与编辑前一致。
