@itshixun/qckeditor-vue2

@itshixun/qckeditor-vue2

Vue 2 组件库，用于 CKEditor 5 富文本编辑器。

注意：这是 Vue 2 版本。如果你使用 Vue 3，请使用 @itshixun/qckeditor-vue3。

本次更新为文档补充：将 v1.1.1 ~ v1.1.4 期间已发布的能力完整收录进 README，便于查阅。

已收录的近期能力：

• QCKEditor 组件，支持 classic / inline / document 三种编辑器类型（v1.1.3）
• locale 属性，透传 CKEditor / QCKEditor / QCKClassic / QCKEditorPro，按语言动态加载 CKEditor 5 官方语言包，支持运行时切换
• dataNormalizer 属性，透传 CKEditor / QCKEditor / QCKClassic / QCKEditorPro，用于格式化初始值与外部 value / modelValue 变更（v1.1.1 / v1.1.2）
• CKEditor 与 QCKContent 的 fontSize 属性（px），通过 CSS 变量 --ck-content-font-size 应用
• QCKEditor 默认合并「段落 + 标题 1~5」的标题配置与「标记（marker）」高亮配置，与历史版本行为保持一致
• QCKEditorPro 透传外部 value / modelValue 变更（v1.1.4）
• QCKEditorPro 的 disableExit 属性与 exit-blocked 事件，用于在编辑器内部异步操作（PendingActions）期间控制是否退出编辑模式
• QCKContent 的 enableCodeHidden / codeHiddenText 属性，把 qckeditor-code-block 插件标记为"预览时隐藏"的代码块替换为占位提示
• QCKContent 的 copyCode / copySuccessDuration / locale 属性，hover 代码块显示复制按钮，复制成功显示绿色文案，按钮文案支持 i18n

安装

npm install @itshixun/qckeditor-vue2
# 或
pnpm add @itshixun/qckeditor-vue2
# 或
yarn add @itshixun/qckeditor-vue2

对等依赖

本库需要以下对等依赖：

npm install vue@^2.6.0 ckeditor5@>=42.0.0

使用

引入样式

在使用组件前，需要引入本库的样式文件：

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

本样式文件已内置 CKEditor 5 官方样式，无需再单独引入 ckeditor5/ckeditor5.css。

基础编辑器（CKEditor）

底层 CKEditor 封装组件，支持任意 CKEditor 构建：

<template>
  <CKEditor
    v-model="content"
    :editor="ClassicEditor"
    :config="editorConfig"
    @ready="onReady"
    @input="onInput"
  />
</template>

<script>
import { ClassicEditor } from 'ckeditor5';
import { CKEditor } from '@itshixun/qckeditor-vue2';
import '@itshixun/qckeditor-vue2/dist/index.css';

export default {
  components: {
    CKEditor,
  },
  data() {
    return {
      content: '',
      ClassicEditor,
      editorConfig: {
        toolbar: ['bold', 'italic', 'link', 'bulletedList', 'numberedList'],
      },
    };
  },
  methods: {
    onReady(editor) {
      console.log('Editor ready:', editor);
    },
    onInput(data, event, editor) {
      console.log('Content changed:', data);
    },
  },
};
</script>

通用编辑器（QCKEditor）

支持三种编辑器类型，由 type prop 切换：

• classic（默认）：经典编辑器，工具栏固定在顶部
• inline：行内编辑器，工具栏在选中内容时浮动显示
• document：文档编辑器（基于 DecoupledEditor），工具栏与编辑区分离挂载，高度自适应容器

QCKEditor 在用户传入 config 之上，预设了与历史版本一致的默认配置：

• 标题：在官方「段落 + 标题 13」基础上扩展支持「标题 4 / 标题 5」（heading4 / heading5），并通过 src/styles/index.css 统一定义了 h1h5 字号样式
• 高亮（Highlight）：仅提供「标记（marker）」一项，配套样式 .marker-default

用户 config 中显式提供的同名字段会覆盖默认配置（深度合并）。

<template>
  <!-- 经典编辑器（默认） -->
  <QCKEditor v-model="content" :config="editorConfig" />

  <!-- 行内编辑器 -->
  <QCKEditor v-model="content" type="inline" :config="editorConfig" />

  <!-- 文档编辑器（工具栏与编辑区独立容器） -->
  <QCKEditor v-model="content" type="document" :config="editorConfig" />
</template>

<script>
import { QCKEditor } from '@itshixun/qckeditor-vue2';
import '@itshixun/qckeditor-vue2/dist/index.css';

export default {
  components: { QCKEditor },
  data() {
    return {
      content: '',
      editorConfig: {
        toolbar: ['bold', 'italic', 'link'],
      },
    };
  },
};
</script>

经典编辑器（QCKClassic）

预配置的经典编辑器组件：

<template>
  <QCKClassic v-model="content" :config="editorConfig" @ready="onReady" />
</template>

<script>
import { QCKClassic } from '@itshixun/qckeditor-vue2';
import '@itshixun/qckeditor-vue2/dist/index.css';

export default {
  components: {
    QCKClassic,
  },
  data() {
    return {
      content: '',
      editorConfig: {
        toolbar: ['bold', 'italic', 'link'],
      },
    };
  },
  methods: {
    onReady(editor) {
      console.log('Editor ready:', editor);
    },
  },
};
</script>

专业版编辑器（QCKEditorPro）

点击激活的编辑器，提升页面性能：

<template>
  <QCKEditorPro
    v-model="content"
    :config="editorConfig"
    placeholder="点击编辑内容"
    :min-height="100"
    @ready="onReady"
  />
</template>

<script>
import { QCKEditorPro } from '@itshixun/qckeditor-vue2';
import '@itshixun/qckeditor-vue2/dist/index.css';

export default {
  components: {
    QCKEditorPro,
  },
  data() {
    return {
      content: '',
      editorConfig: {
        toolbar: ['bold', 'italic'],
      },
    };
  },
  methods: {
    onReady(editor) {
      console.log('Editor ready:', editor);
    },
  },
};
</script>

内容展示（QCKContent）

安全渲染编辑器内容：

<template>
  <QCKContent :content="htmlContent" />
</template>

<script>
import { QCKContent } from '@itshixun/qckeditor-vue2';
import '@itshixun/qckeditor-vue2/dist/index.css';

export default {
  components: {
    QCKContent,
  },
  data() {
    return {
      htmlContent: '<p>Hello <strong>World</strong></p>',
    };
  },
};
</script>

图片预览（imagePreview）

默认关闭。开启后，点击内容中的图片会打开内置轻量预览弹层（QCKImageViewer），支持关闭（遮罩/×/Esc）、左右切换（按钮/方向键）、计数、缩放（按钮/滚轮）、拖拽平移、双击复位、全屏与底部缩略图栏：

<template>
  <!-- 布尔用法：全部默认配置 -->
  <QCKContent :content="htmlContent" :image-preview="true" />

  <!-- 对象用法：覆盖配置 -->
  <QCKContent :content="htmlContent" :image-preview="{ zIndex: 3000, navbar: false }" />
</template>

imagePreview 对象形式支持的选项（QCKImagePreviewOptions）：

QCKEditorPro 同样支持 imagePreview，会透传给预览态的内容区（预览态点击图片只打开预览，不会激活编辑器）。

已知限制：Vue 2 版本无内置 Teleport，预览弹层使用 position: fixed 内联渲染。若组件祖先存在 transform/filter/perspective 样式，弹层定位会相对该祖先而非视口。

图片加载失败重试（imageRetry）

默认开启。适用于新生成的富文本内容中，图片资源正在服务端上传、尚未存储到对象存储的场景：图片加载失败后按固定间隔自动重试，直到成功或达到最大次数。重试通过重设相同 src 触发重新请求，不追加额外参数，不会破坏签名 URL：

<template>
  <!-- 布尔用法：全部默认配置（可省略） -->
  <QCKContent :content="htmlContent" :image-retry="true" />

  <!-- 对象用法：覆盖配置 -->
  <QCKContent :content="htmlContent" :image-retry="{ maxRetries: 20, interval: 1000 }" />

  <!-- 关闭重试 -->
  <QCKContent :content="htmlContent" :image-retry="false" />
</template>

imageRetry 对象形式支持的选项（QCKImageRetryOptions）：

QCKEditorPro / QCKEditor / QCKClassic 同样支持 imageRetry：预览态（QCKContent）与编辑态（编辑区 DOM）均生效。

代码块预览隐藏（enableCodeHidden）

默认关闭。开启后，把 qckeditor-code-block 插件标记为"预览时隐藏"的代码块（pre[data-hide-in-preview="true"]）替换为占位提示，占位文案经 textContent 写入，无 XSS 风险：

<template>
  <!-- 默认占位文案"代码已隐藏" -->
  <QCKContent :content="htmlContent" :enable-code-hidden="true" />

  <!-- 自定义占位文案 -->
  <QCKContent
    :content="htmlContent"
    :enable-code-hidden="true"
    code-hidden-text="这段代码已被作者隐藏"
  />
</template>

代码块复制（copyCode）

默认关闭。开启后，鼠标 hover 到代码块（pre > code）时，代码块右上角显示"复制"按钮；点击复制代码文本，成功后按钮变为绿色的"复制成功"文案，超时后自动恢复为"复制"：

<template>
  <!-- 开启复制功能（成功文案默认 5 秒后恢复） -->
  <QCKContent :content="htmlContent" :copy-code="true" />

  <!-- 自定义"复制成功"文案显示时长为 2 秒 -->
  <QCKContent :content="htmlContent" :copy-code="true" :copy-success-duration="2000" />

  <!-- 指定按钮文案语言 -->
  <QCKContent :content="htmlContent" :copy-code="true" locale="en" />
</template>

• i18n：按钮文案（"复制" / "复制成功"）由 locale 属性控制，默认 'zh-cn'，覆盖 CKEditor 5 官方全部语言码（70+），写法兼容 'zhCN' / 'zh_CN' 等，未收录的语种回退为英文。该 locale 仅作用于复制按钮文案，基于内置翻译表实现，不涉及 CKEditor 5 语言包的动态加载
• 复制实现：优先使用 navigator.clipboard（需安全上下文），非安全上下文（如 http 环境）自动回退为隐藏 textarea + document.execCommand('copy')
• 动态内容：内容更新（content / v-model 变更）后按钮自动重新注入；运行时把 copyCode 置为 false 会移除全部已注入的按钮

界面语言（locale）

所有编辑器组件（CKEditor / QCKEditor / QCKClassic / QCKEditorPro）支持 locale 属性，默认 'zh-cn'。组件会按 locale 动态加载对应的 CKEditor 5 官方语言包（构建为独立的懒加载 chunk，不增加首屏体积），并写入编辑器配置的 language 与 translations 字段：

<template>
  <!-- 简体中文（默认） -->
  <QCKEditor v-model="content" locale="zh-cn" />

  <!-- 英文 / 日文 / 繁体中文 -->
  <QCKEditor v-model="content" locale="en" />
  <QCKEditorPro v-model="content" locale="ja" />
  <QCKClassic v-model="content" locale="zh" />
</template>

• 写法兼容：'zhCN' / 'zh-CN' / 'zh_CN' / 'ZH-CN' 等写法均可，内部统一规范化为 CKEditor 5 语言包格式（小写 + 连字符）
• 支持语言：覆盖 CKEditor 5 官方全部语言包（zh-cn、zh、en、en-gb、ja、ko、de、fr、pt-br 等 70+）；传入不支持的语言时会输出警告并回退为默认语言
• 动态变更：运行时修改 locale 会销毁并以当前内容重建编辑器实例（CKEditor 5 不支持运行时原地切换语言）；重建对外只触发一次新的 ready 事件，不会触发 destroy
• 优先级：config 中显式传入的 language / translations 优先于 locale 的派生值

QCKContent 也提供 locale 属性，但语义不同：仅用于 copyCode 复制按钮的文案（内置翻译表，不涉及语言包动态加载），见「代码块复制」说明。

export default {
  data() {
    return {
      content: '',
      locale: 'zh-cn',
    };
  },
  methods: {
    switchToEnglish() {
      // 运行时切换：编辑器保留内容重建，界面语言变为英文
      this.locale = 'en';
    },
  },
};

Props

CKEditor

QCKEditor

默认配置说明：QCKEditor 预置了「段落 + 标题 1~5」的标题选项，以及「标记（marker）」高亮选项，与历史版本编辑器一致。用户 config 中显式提供同名字段会覆盖默认值。

QCKEditor 在 ready 等事件中传入的编辑器实例类型为 ClassicEditor | InlineEditor | DecoupledEditor（即 QEditorInstance 联合类型）。

QCKClassic

QCKEditorPro

QCKContent

事件

所有编辑器组件都支持以下事件：

QCKEditorPro 还会发出：

类型导出

import type {
  Props,
  ExtractEditorType,
  QCKImagePreviewOptions,
  QCKImageRetryOptions,
  QEditorType,
  QEditorInstance,
} from '@itshixun/qckeditor-vue2';

上传适配器

本库提供了三种上传适配器，用于处理编辑器中的文件上传（图片、音视频等）：

1. XHR 上传适配器（createXHRUploadAdapter）

基于 XMLHttpRequest 的标准上传方式，适用于大多数后端直传场景：

import { FileRepository } from 'ckeditor5';
import { createXHRUploadAdapter } from '@itshixun/qckeditor-vue2';

export default {
  data() {
    return {
      content: '',
      editorConfig: {
        // ...其他配置
        extraPlugins: [
          function CustomUploadAdapterPlugin(editor) {
            editor.plugins.get(FileRepository).createUploadAdapter = (loader) => {
              return createXHRUploadAdapter(loader, {
                uploadUrl: 'https://api.example.com/upload',
                headers: { Authorization: 'Bearer token' },
                withCredentials: true,
                fieldName: 'file',
                extraFormData: { category: 'images' },
              });
            };
          },
        ],
      },
    };
  },
};

2. 自定义异步上传适配器（createAsyncUploadAdapter）

支持自定义异步上传流程，适用于 S3、华为云 OBS 等需要多步上传的场景：

import { FileRepository } from 'ckeditor5';
import { createAsyncUploadAdapter } from '@itshixun/qckeditor-vue2';

export default {
  data() {
    return {
      content: '',
      editorConfig: {
        extraPlugins: [
          function CustomUploadAdapterPlugin(editor) {
            editor.plugins.get(FileRepository).createUploadAdapter = (loader) => {
              return createAsyncUploadAdapter(loader, async (file, updateProgress) => {
                // 示例：上传到对象存储（预签名 URL 模式）

                // 第1步：从后端获取预签名上传 URL
                const presignRes = await fetch('/api/presign-upload', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: JSON.stringify({ filename: file.name, contentType: file.type }),
                });
                const { uploadUrl, finalUrl } = await presignRes.json();

                // 第2步：直传到对象存储（使用 XMLHttpRequest 以便监听进度）
                await new Promise((resolve, reject) => {
                  const xhr = new XMLHttpRequest();
                  xhr.open('PUT', uploadUrl, true);
                  xhr.setRequestHeader('Content-Type', file.type);

                  xhr.upload.addEventListener('progress', (evt) => {
                    if (evt.lengthComputable && updateProgress) {
                      updateProgress(Math.round((evt.loaded / evt.total) * 100));
                    }
                  });
                  xhr.addEventListener('load', () => {
                    xhr.status >= 200 && xhr.status < 300 ? resolve() : reject('上传失败');
                  });
                  xhr.addEventListener('error', () => reject('上传出错'));
                  xhr.send(file);
                });

                // 第3步：返回最终访问 URL
                return finalUrl;
              });
            };
          },
        ],
      },
    };
  },
};

也可以返回 UploadResponse 对象：

createAsyncUploadAdapter(loader, async (file, updateProgress) => {
  // ...上传逻辑

  return {
    default: 'https://cdn.example.com/image.jpg',  // 默认 URL（必须）
    url: 'https://cdn.example.com/image.jpg',      // 可选
    // 还可以返回其他字段
  };
});

3. Mock 上传适配器（createMockUploadAdapter）

用于演示环境，模拟上传过程和进度更新：

import { FileRepository } from 'ckeditor5';
import { createMockUploadAdapter } from '@itshixun/qckeditor-vue2';

export default {
  data() {
    return {
      content: '',
      editorConfig: {
        extraPlugins: [
          function CustomUploadAdapterPlugin(editor) {
            editor.plugins.get(FileRepository).createUploadAdapter = (loader) => {
              return createMockUploadAdapter(loader);
            };
          },
        ],
      },
    };
  },
};

与 Vue 3 版本的区别

1. 组件注册：Vue 2 需要手动在 components 选项中注册
2. v-model：Vue 2 使用 value prop 和 input 事件
3. 生命周期：使用 beforeDestroy 替代 beforeUnmount

注意事项

1. CKEditor 授权：本库使用 CKEditor 5 的 GPL 授权。如需商业使用，请购买 CKEditor 商业授权。

2. 样式文件：导入 @itshixun/qckeditor-vue2/dist/index.css 即可，该文件已内置 CKEditor 5 官方样式。

3. HTML 清洗：QCKContent 和 QCKEditorPro 默认开启 XSS 防护，会自动过滤危险标签和属性。

4. Vue 版本：本库支持 Vue 2.6+ 和 Vue 2.7。

5. QCKEditor 默认配置：QCKEditor 会自动合并「段落 + 标题 1~5」的标题选项与「标记（marker）」高亮选项。覆盖方式：在 config.heading.options 或 config.highlight.options 中提供完整数组（lodash merge 按索引合并）。

6. dataNormalizer：用于在写入编辑器前格式化内容（初始值与外部 value / modelValue 变更都会经过此函数）。返回值为字符串；常见用途：清理历史版本遗留的脏标签、统一空白与编码。

7. 异步操作与退出编辑：QCKEditorPro 在 PendingActions 仍有任务时（即文件上传、撤销恢复队列非空等）会阻止退出编辑模式，并通过 exit-blocked 事件通知业务方。可结合 disableExit 强制阻止。

8. locale 与动态切换：语言包按需懒加载，仅使用到的语言会进入运行时加载。修改 locale 会重建编辑器实例（内容保留），频繁切换有性能开销；若 config 中已显式配置 language / translations，则以 config 为准。

License

MIT