@itshixun/qckeditor-plugin-doc-import

@itshixun/qckeditor-plugin-doc-import

CKEditor 5 插件：Word 文档导入。通过 Dialog 弹窗选择 Word 文档，将文档内容转换为 HTML 后插入编辑器当前光标位置。支持点击选择和拖拽上传，内置文件类型和大小校验。

安装

npm install @itshixun/qckeditor-plugin-doc-import
# 或
pnpm add @itshixun/qckeditor-plugin-doc-import

依赖 ckeditor5（peerDependencies，需自行安装）。

基本使用

1. 引入样式

import '@itshixun/qckeditor-plugin-doc-import/dist/index.css';

2. 注册插件

import { ClassicEditor } from 'ckeditor5';
import { DocImport } from '@itshixun/qckeditor-plugin-doc-import';

const editor = await ClassicEditor.create(element, {
  plugins: [
    // ... 其他插件
    DocImport,
  ],
  toolbar: [
    // ... 其他按钮
    'docImport',  // 工具栏按钮名称：导入 Word
  ],
  docImport: {
    // 必填：异步导入处理方法
    importHandler: async (file: File) => {
      // 将 Word 文档上传/转换，返回 HTML 字符串
      const formData = new FormData();
      formData.append('file', file);

      const response = await fetch('/api/doc/convert', {
        method: 'POST',
        body: formData,
      });

      const result = await response.json();
      return result.html; // 返回转换后的 HTML 字符串
    },
    // 可选配置
    types: ['docx'],
    maxFileSize: 5,
    uploadInfo: '提示：导入时会将整篇 Word 文档的内容插入编辑器。',
  },
});

3. Vue 中使用

<script setup lang="ts">
import { ClassicEditor } from 'ckeditor5';
import { DocImport } from '@itshixun/qckeditor-plugin-doc-import';

const config = {
  editor: ClassicEditor,
  plugins: [/* ... */, DocImport],
  toolbar: ['bold', 'italic', 'docImport'],
  docImport: {
    importHandler: async (file: File) => {
      // 调用后端接口转换文档
      const formData = new FormData();
      formData.append('file', file);
      const res = await fetch('/api/convert-doc', {
        method: 'POST',
        body: formData,
      });
      const data = await res.json();
      return data.html;
    },
    types: ['docx', 'doc'],
    maxFileSize: 10,
  },
};
</script>

<template>
  <ckeditor :editor="config.editor" :config="config" />
</template>

配置项

属性	类型	必填	说明
importHandler	(file: File) => Promise<string>	是	异步导入处理方法，接收文件对象，返回转换后的 HTML 字符串
types	string[]	否	允许导入的文件扩展名列表，默认 ['docx']
maxFileSize	number	否	最大文件大小（MB），默认 5
uploadInfo	string	否	上传区域下方自定义提示文字

importHandler 说明

importHandler 是插件的核心配置，负责将 Word 文档转换为编辑器可识别的 HTML。插件本身不包含文档转换能力，你需要自行实现转换逻辑（通常调用后端服务完成）。

实现示例

const importHandler = async (file: File): Promise<string> => {
  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch('/api/document/convert', {
    method: 'POST',
    body: formData,
  });

  if (!response.ok) {
    throw new Error('文档转换失败');
  }

  const result = await response.json();

  // 必须返回 HTML 字符串
  return result.html;
};

重要：

• importHandler 为必填项，未配置时点击工具栏按钮会提示警告
• 返回的 HTML 字符串会经过 CKEditor 5 的 HTML 处理器转换为模型片段后插入编辑器
• 如果转换过程抛出异常，弹窗会显示错误信息并保持打开状态

命令说明

docImport — 导入 Word 文档

通常由工具栏按钮自动触发，也可手动调用：

// 手动执行导入命令（通常在自定义 UI 中使用）
editor.execute('docImport', {
  file: selectedFile,                          // File 对象
  savedSelection: editor.model.createSelection( // 保存的选区
    editor.model.document.selection
  ),
});

插件行为

1. 点击工具栏按钮打开 Dialog 弹窗
2. 弹窗中显示文件上传区域，支持点击选择和拖拽上传
3. 选中文件后自动校验文件类型和大小
4. 点击"确定"后调用 importHandler 进行异步转换
5. 转换完成后将 HTML 内容插入编辑器当前光标位置
6. 导入过程中显示加载动画，并禁用弹窗按钮

类型支持

导入插件后，EditorConfig 类型自动扩展，TypeScript 可直接识别 docImport 配置：

const config: EditorConfig = {
  // 无类型错误，docImport 已声明
  docImport: {
    types: ['docx'],
    maxFileSize: 10,
    importHandler: async (file) => {
      return '<p>转换后的 HTML</p>';
    },
  },
};

导出 API

import {
  DocImport,           // 主插件（Editing + UI）
  DocImportEditing,    // 编辑插件（注册 docImport 命令）
  DocImportUI,         // UI 插件（工具栏按钮 + Dialog 弹窗）
  DocImportCommand,    // 导入命令
  DocImportView,       // 弹窗内容视图
  type DocImportConfig,
  type DocImportCommandOptions,
} from '@itshixun/qckeditor-plugin-doc-import';