@itshixun/qckeditor-vue2

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

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

安装

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

使用

引入样式

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

import 'ckeditor5/ckeditor5.css';
import '@itshixun/qckeditor-vue2/dist/style.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 'ckeditor5/ckeditor5.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>

经典编辑器（QCKClassic）

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

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

<script>
import { QCKClassic } from '@itshixun/qckeditor-vue2';
import 'ckeditor5/ckeditor5.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 'ckeditor5/ckeditor5.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 'ckeditor5/ckeditor5.css';

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

Props

CKEditor

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | editor | Function | 必填 | CKEditor 构建类 | | config | Object | {} | 编辑器配置 | | tagName | String | 'div' | 渲染标签 | | disabled | Boolean | false | 是否禁用 | | disableTwoWayDataBinding | Boolean | false | 禁用双向绑定 | | value / v-model | String | '' | 编辑器内容 |

QCKClassic

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | config | Object | {} | 编辑器配置 | | tagName | String | 'div' | 渲染标签 | | disabled | Boolean | false | 是否禁用 | | disableTwoWayDataBinding | Boolean | false | 禁用双向绑定 | | value / v-model | String | '' | 编辑器内容 |

QCKEditorPro

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | config | Object | {} | 编辑器配置 | | content | String | - | 初始内容 | | placeholder | String | '点击编辑内容' | 占位文本 | | minHeight | Number | 95 | 最小高度(px) | | height | Number | 0 | 固定高度(px) | | fitHeight | Boolean | false | 适应父容器高度 | | contentBgColor | String | 'rgb(0 0 0 / 2%)' | 背景色 | | contentBgHoverColor | String | 'rgb(0 0 0 / 4%)' | 悬停背景色 | | borderRadius | Number | 4 | 圆角大小 | | sanitize | Boolean | true | 是否清洗 HTML | | value / v-model | String | '' | 编辑器内容 |

QCKContent

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | content | String | - | HTML 内容 | | containerClass | String | '' | 容器类名 | | sanitize | Boolean | true | 是否清洗 HTML | | value / v-model | String | '' | 内容 |

事件

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

| 事件 | 参数 | 说明 | |------|------|------| | ready | (editor) | 编辑器就绪 | | destroy | - | 编辑器销毁 | | blur | (event, editor) | 失去焦点 | | focus | (event, editor) | 获得焦点 | | input | (data, event, editor) | 内容变化 |

上传适配器

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

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

类型导出

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

注意事项

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

2. 样式文件：必须导入 ckeditor5/ckeditor5.css 以确保编辑器样式正确。

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

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

License

MIT