DOCX 导入/导出

导入 DOCX 文件并将 Plate 内容导出为 Word 文档。

功能特性

导入 DOCX 文件 到 Plate 格式，支持完整内容和批注提取
导出为 DOCX 支持所有常见格式、表格、列表和图片
支持页眉、页脚、页面方向和边距
可配置导出的 CSS 样式和字体

需要从 Word 粘贴支持？请参阅 DOCX 粘贴。

安装

pnpm add @platejs/docx-io

pnpm add @platejs/docx-io

导入 DOCX

导入 DOCX 文件

使用 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);
  }
};

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);
  }
};

导出 DOCX

基本导出

使用 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 { 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 { 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 } 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',
});

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',
});

使用 DocxExportPlugin

基于插件的 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',
});

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',
});

DOCX 导出套件

DocxExportKit 为需要特殊处理的元素提供 DOCX 优化的静态组件：

/**
 * Editor kit optimized for DOCX export.
 *
 * Uses docx-specific static components for elements that require
 * inline styles instead of Tailwind classes (which don't work in DOCX):
 * - Code blocks: Need inline syntax highlighting colors and line breaks
 * - Columns: Need table layout instead of flexbox
 * - Equations: Need inline font styling (KaTeX doesn't work in DOCX)
 * - Callouts: Need table layout for icon + content
 * - TOC: Need anchor links with proper paragraph breaks
 *
 * Tables use base version with juice CSS inlining.
 */
 
import { CalloutElementDocx } from '@/components/ui/callout-node-static';
import {
  CodeBlockElementDocx,
  CodeLineElementDocx,
  CodeSyntaxLeafDocx,
} from '@/components/ui/code-block-node-static';
import {
  ColumnElementDocx,
  ColumnGroupElementDocx,
} from '@/components/ui/column-node-static';
import {
  EquationElementDocx,
  InlineEquationElementDocx,
} from '@/components/ui/equation-node-static';
import { TocElementDocx } from '@/components/ui/toc-node-static';
import { DocxExportPlugin } from '@platejs/docx-io';
import { KEYS } from 'platejs';
 
/**
 * Editor kit for DOCX export.
 *
 * Uses standard static components for most elements (with juice CSS inlining),
 * but uses docx-specific components for elements that need special handling:
 * - Code blocks (syntax highlighting, line breaks)
 * - Columns (table layout instead of flexbox)
 * - Equations (inline font instead of KaTeX)
 * - Callouts (table layout for icon placement)
 * - TOC (anchor links with paragraph breaks)
 *
 * Tables use base version with juice CSS inlining.
 */
export const DocxExportKit = [
  DocxExportPlugin.configure({
    override: {
      components: {
        [KEYS.codeBlock]: CodeBlockElementDocx,
        [KEYS.codeLine]: CodeLineElementDocx,
        [KEYS.codeSyntax]: CodeSyntaxLeafDocx,
        [KEYS.column]: ColumnElementDocx,
        [KEYS.columnGroup]: ColumnGroupElementDocx,
        [KEYS.equation]: EquationElementDocx,
        [KEYS.inlineEquation]: InlineEquationElementDocx,
        [KEYS.callout]: CalloutElementDocx,
        [KEYS.toc]: TocElementDocx,
      },
    },
  }),
];

/**
 * Editor kit optimized for DOCX export.
 *
 * Uses docx-specific static components for elements that require
 * inline styles instead of Tailwind classes (which don't work in DOCX):
 * - Code blocks: Need inline syntax highlighting colors and line breaks
 * - Columns: Need table layout instead of flexbox
 * - Equations: Need inline font styling (KaTeX doesn't work in DOCX)
 * - Callouts: Need table layout for icon + content
 * - TOC: Need anchor links with proper paragraph breaks
 *
 * Tables use base version with juice CSS inlining.
 */
 
import { CalloutElementDocx } from '@/components/ui/callout-node-static';
import {
  CodeBlockElementDocx,
  CodeLineElementDocx,
  CodeSyntaxLeafDocx,
} from '@/components/ui/code-block-node-static';
import {
  ColumnElementDocx,
  ColumnGroupElementDocx,
} from '@/components/ui/column-node-static';
import {
  EquationElementDocx,
  InlineEquationElementDocx,
} from '@/components/ui/equation-node-static';
import { TocElementDocx } from '@/components/ui/toc-node-static';
import { DocxExportPlugin } from '@platejs/docx-io';
import { KEYS } from 'platejs';
 
/**
 * Editor kit for DOCX export.
 *
 * Uses standard static components for most elements (with juice CSS inlining),
 * but uses docx-specific components for elements that need special handling:
 * - Code blocks (syntax highlighting, line breaks)
 * - Columns (table layout instead of flexbox)
 * - Equations (inline font instead of KaTeX)
 * - Callouts (table layout for icon placement)
 * - TOC (anchor links with paragraph breaks)
 *
 * Tables use base version with juice CSS inlining.
 */
export const DocxExportKit = [
  DocxExportPlugin.configure({
    override: {
      components: {
        [KEYS.codeBlock]: CodeBlockElementDocx,
        [KEYS.codeLine]: CodeLineElementDocx,
        [KEYS.codeSyntax]: CodeSyntaxLeafDocx,
        [KEYS.column]: ColumnElementDocx,
        [KEYS.columnGroup]: ColumnGroupElementDocx,
        [KEYS.equation]: EquationElementDocx,
        [KEYS.inlineEquation]: InlineEquationElementDocx,
        [KEYS.callout]: CalloutElementDocx,
        [KEYS.toc]: TocElementDocx,
      },
    },
  }),
];

包含的组件：

代码块: 带换行的内联语法高亮
多列: 使用表格布局代替 flexbox
公式: 内联字体样式（KaTeX 在 DOCX 中不工作）
标注: 图标+内容的表格布局
目录: 带正确段落分隔的锚点链接

插件

DocxExportPlugin

提供 DOCX 导出功能和类型化 API 方法的插件。

Options

用于 HTML 序列化的插件。如未提供，则使用编辑器当前的插件。

用于静态渲染的 React 组件。

API

`importDocx`

导入 DOCX 文件并转换为 Plate 节点。

Parameters

Plate 编辑器实例。

DOCX 文件的 ArrayBuffer。

导入选项。

OptionsImportDocxOptions

用于图片提取的 RTF 数据。

ReturnsPromise<ImportDocxResult>

反序列化的编辑器节点。

从 DOCX 文件提取的批注。

mammoth 转换的警告。

`exportToDocx`

将 Plate 内容转换为 DOCX blob。

Parameters

Plate 编辑器值（节点数组）。

导出选项。

OptionsDocxExportOptions

页面方向。

默认值: 'portrait'

页边距，单位为二十分之一点（1英寸 = 1440）。

默认值: { top: 1440, bottom: 1440, left: 1440, right: 1440, header: 720, footer: 720, gutter: 0 }

文档正文的字体系列。覆盖默认的 Calibri 字体。

要包含的额外 CSS 样式。附加在默认 DOCX_EXPORT_STYLES 之后。

用于元数据的文档标题。

用于 HTML 序列化的插件。

用于静态渲染的组件。

ReturnsPromise<Blob>

包含 DOCX 文件的 Blob。

`downloadDocx`

将 DOCX blob 下载为文件。

Parameters

要下载的 DOCX blob。

文件名（带或不带 .docx 扩展名）。

`exportEditorToDocx`

一次调用导出并下载编辑器内容为 DOCX 文件。

Parameters

Plate 编辑器值。

下载的文件名。

导出选项（与 exportToDocx 相同）。

api.docxExport.exportToBlob

使用插件 API 将编辑器内容转换为 DOCX blob。

OptionsDocxExportOperationOptions

页面方向。

页边距。

字体系列。

额外的 CSS 样式。

文档标题。

ReturnsPromise<Blob>

包含 DOCX 文件的 Blob。

api.docxExport.download

将 DOCX blob 下载为文件。

Parameters

DOCX blob。

文件名。

Transforms

tf.docxExport.exportAndDownload

导出并下载编辑器内容为 DOCX 文件。

Parameters

下载的文件名。

导出选项。

类型

DocxComment

type DocxComment = {
  id: string;
  text: string;
};

type DocxComment = {
  id: string;
  text: string;
};

DocxExportMargins

type DocxExportMargins = {
  top?: number;
  bottom?: number;
  left?: number;
  right?: number;
  header?: number;
  footer?: number;
  gutter?: number;
};

type DocxExportMargins = {
  top?: number;
  bottom?: number;
  left?: number;
  right?: number;
  header?: number;
  footer?: number;
  gutter?: number;
};

常量

DOCX_EXPORT_STYLES

为 Microsoft Word HTML 渲染优化的默认 CSS 样式：

Calibri 字体（Microsoft Office 默认）
11pt 字号，1.5 行高
标题层级（24pt 到 10pt）
带边框的表格样式
Courier New 代码块样式
带左边框的引用样式

已知限制

移动浏览器: 由于 blob 处理和下载的限制，导出在移动浏览器上可能不可靠。
复杂布局: 某些复杂的 CSS 布局（flexbox、grid）会转换为基于表格的布局以兼容 Word。
自定义字体: 只有 Word 中可用的系统字体才能正确渲染。

DOCX Changelog

构建你的编辑器

生产就绪的 AI 模板和可重用的组件。

DOCX 导入/导出

功能特性

安装

导入 DOCX

导入 DOCX 文件

导出 DOCX

基本导出

使用编辑器插件

自定义样式

使用 DocxExportPlugin

DOCX 导出套件

插件

DocxExportPlugin

Options

editorPlugins optional SlatePlugin[]

editorPlugins optional SlatePlugin[]

editorStaticComponent optional React.ComponentType<PlateStaticProps>

editorStaticComponent optional React.ComponentType<PlateStaticProps>

API

importDocx

Parameters

editor SlateEditor

editor SlateEditor

arrayBuffer ArrayBuffer

arrayBuffer ArrayBuffer

options optional ImportDocxOptions

options optional ImportDocxOptions

OptionsImportDocxOptions

rtf optional string

rtf optional string

ReturnsPromise<ImportDocxResult>

nodes TNode[]

nodes TNode[]

comments DocxComment[]

comments DocxComment[]

warnings string[]

warnings string[]

exportToDocx

Parameters

value Value

value Value

options optional DocxExportOptions

options optional DocxExportOptions

OptionsDocxExportOptions

orientation optional 'portrait' | 'landscape'

orientation optional 'portrait' | 'landscape'

margins optional DocxExportMargins

margins optional DocxExportMargins

fontFamily optional string

fontFamily optional string

customStyles optional string

customStyles optional string

title optional string

title optional string

editorPlugins optional SlatePlugin[]

editorPlugins optional SlatePlugin[]

editorStaticComponent optional React.ComponentType

editorStaticComponent optional React.ComponentType

ReturnsPromise<Blob>

downloadDocx

Parameters

blob Blob

blob Blob

filename string

filename string

exportEditorToDocx

Parameters

value Value

value Value

filename string

filename string

options optional DocxExportOptions

options optional DocxExportOptions

api.docxExport.exportToBlob

OptionsDocxExportOperationOptions

orientation optional 'portrait' | 'landscape'

orientation optional 'portrait' | 'landscape'

margins optional DocxExportMargins

margins optional DocxExportMargins

fontFamily optional string

`importDocx`

`exportToDocx`

`downloadDocx`

`exportEditorToDocx`