docs/(plugins)/(serializing)/docx-io.cn.mdx
npm install @platejs/docx-io
使用 importDocx 将 DOCX 文件转换为 Plate 节点：
import { importDocx } from '@platejs/docx-io';
const handleFileUpload = async (file: File) => {
const arrayBuffer = await file.arrayBuffer();
const result = await importDocx(editor, arrayBuffer);
// 将节点插入编辑器
editor.tf.insertNodes(result.nodes);
// 处理批注（如需要）
for (const comment of result.comments) {
console.log(`批注 ${comment.id}: ${comment.text}`);
}
// 检查转换警告
if (result.warnings.length > 0) {
console.warn('转换警告:', result.warnings);
}
};
使用 exportToDocx 将 Plate 内容转换为 DOCX 文件：
import { exportToDocx, downloadDocx } from '@platejs/docx-io';
const handleExport = async () => {
const blob = await exportToDocx(editor.children, {
orientation: 'portrait',
margins: { top: 1440, bottom: 1440, left: 1440, right: 1440 },
fontFamily: 'Calibri',
});
downloadDocx(blob, 'document.docx');
};
或使用组合函数：
import { exportEditorToDocx } from '@platejs/docx-io';
await exportEditorToDocx(editor.children, 'document', {
orientation: 'portrait',
});
为确保准确序列化，请提供您的编辑器插件：
import { exportToDocx } from '@platejs/docx-io';
import { BaseEditorKit } from '@/components/editor/editor-base-kit';
import { DocxExportKit } from '@/components/editor/plugins/docx-export-kit';
const blob = await exportToDocx(editor.children, {
editorPlugins: [...BaseEditorKit, ...DocxExportKit],
});
自定义导出样式：
import { exportToDocx, DOCX_EXPORT_STYLES } from '@platejs/docx-io';
const blob = await exportToDocx(editor.children, {
customStyles: `
.custom-highlight { background-color: #ffeb3b; }
h1 { color: #1a1a1a; }
`,
fontFamily: 'Times New Roman',
});
基于插件的 API 访问：
import { DocxExportPlugin } from '@platejs/docx-io';
import { createPlateEditor } from 'platejs/react';
const editor = createPlateEditor({
plugins: [
// ...其他插件,
DocxExportPlugin.configure({
options: {
editorPlugins: myPlugins,
editorStaticComponent: MyEditorStatic,
},
}),
],
});
// 使用插件 API 导出
const blob = await editor.api.docxExport.exportToBlob({
orientation: 'landscape',
});
editor.api.docxExport.download(blob, 'document');
// 或使用 transform 导出并下载
await editor.tf.docxExport.exportAndDownload('document', {
orientation: 'portrait',
});
DocxExportKit 为需要特殊处理的元素提供 DOCX 优化的静态组件：
包含的组件：
提供 DOCX 导出功能和类型化 API 方法的插件。
<API name="DocxExportPlugin"> <APIOptions> <APIItem name="editorPlugins" type="SlatePlugin[]" optional> 用于 HTML 序列化的插件。如未提供，则使用编辑器当前的插件。 </APIItem> <APIItem name="editorStaticComponent" type="React.ComponentType<PlateStaticProps>" optional> 用于静态渲染的 React 组件。 </APIItem> </APIOptions> </API>importDocx导入 DOCX 文件并转换为 Plate 节点。
<API name="importDocx"> <APIParameters> <APIItem name="editor" type="SlateEditor"> Plate 编辑器实例。 </APIItem> <APIItem name="arrayBuffer" type="ArrayBuffer"> DOCX 文件的 ArrayBuffer。 </APIItem> <APIItem name="options" type="ImportDocxOptions" optional> 导入选项。 </APIItem> </APIParameters> <APIOptions type="ImportDocxOptions"> <APIItem name="rtf" type="string" optional> 用于图片提取的 RTF 数据。 </APIItem> </APIOptions> <APIReturns type="Promise<ImportDocxResult>"> <APIItem name="nodes" type="TNode[]"> 反序列化的编辑器节点。 </APIItem> <APIItem name="comments" type="DocxComment[]"> 从 DOCX 文件提取的批注。 </APIItem> <APIItem name="warnings" type="string[]"> mammoth 转换的警告。 </APIItem> </APIReturns> </API>exportToDocx将 Plate 内容转换为 DOCX blob。
<API name="exportToDocx"> <APIParameters> <APIItem name="value" type="Value"> Plate 编辑器值（节点数组）。 </APIItem> <APIItem name="options" type="DocxExportOptions" optional> 导出选项。 </APIItem> </APIParameters> <APIOptions type="DocxExportOptions"> <APIItem name="orientation" type="'portrait' | 'landscape'" optional> 页面方向。'portrait'
</APIItem>
{ top: 1440, bottom: 1440, left: 1440, right: 1440, header: 720, footer: 720, gutter: 0 }
</APIItem>
downloadDocx将 DOCX blob 下载为文件。
<API name="downloadDocx"> <APIParameters> <APIItem name="blob" type="Blob"> 要下载的 DOCX blob。 </APIItem> <APIItem name="filename" type="string"> 文件名（带或不带 .docx 扩展名）。 </APIItem> </APIParameters> </API>exportEditorToDocx一次调用导出并下载编辑器内容为 DOCX 文件。
<API name="exportEditorToDocx"> <APIParameters> <APIItem name="value" type="Value"> Plate 编辑器值。 </APIItem> <APIItem name="filename" type="string"> 下载的文件名。 </APIItem> <APIItem name="options" type="DocxExportOptions" optional> 导出选项（与 `exportToDocx` 相同）。 </APIItem> </APIParameters> </API>使用插件 API 将编辑器内容转换为 DOCX blob。
<API name="api.docxExport.exportToBlob"> <APIOptions type="DocxExportOperationOptions"> <APIItem name="orientation" type="'portrait' | 'landscape'" optional> 页面方向。 </APIItem> <APIItem name="margins" type="DocxExportMargins" optional> 页边距。 </APIItem> <APIItem name="fontFamily" type="string" optional> 字体系列。 </APIItem> <APIItem name="customStyles" type="string" optional> 额外的 CSS 样式。 </APIItem> <APIItem name="title" type="string" optional> 文档标题。 </APIItem> </APIOptions> <APIReturns type="Promise<Blob>"> 包含 DOCX 文件的 Blob。 </APIReturns> </API>将 DOCX blob 下载为文件。
<API name="api.docxExport.download"> <APIParameters> <APIItem name="blob" type="Blob"> DOCX blob。 </APIItem> <APIItem name="filename" type="string"> 文件名。 </APIItem> </APIParameters> </API>导出并下载编辑器内容为 DOCX 文件。
<API name="tf.docxExport.exportAndDownload"> <APIParameters> <APIItem name="filename" type="string"> 下载的文件名。 </APIItem> <APIItem name="options" type="DocxExportOperationOptions" optional> 导出选项。 </APIItem> </APIParameters> </API>type DocxComment = {
id: string;
text: string;
};
type DocxExportMargins = {
top?: number;
bottom?: number;
left?: number;
right?: number;
header?: number;
footer?: number;
gutter?: number;
};
为 Microsoft Word HTML 渲染优化的默认 CSS 样式：