@itshixun/qckeditor-plugin-select-resource

CKEditor 5 插件：资料文件引用。在编辑器中插入资源文件链接（PDF、MP4 等），支持预览或下载。

安装

npm install @itshixun/qckeditor-plugin-select-resource
# 或
pnpm add @itshixun/qckeditor-plugin-select-resource

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

基本使用

1. 引入样式

只需引入插件自身的 CSS，文件链接的基础样式会自动包含：

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

无需单独安装或引入 @itshixun/qckeditor-plugin-file-display。

2. 注册插件

import { ClassicEditor } from 'ckeditor5';
import { SelectResource } from '@itshixun/qckeditor-plugin-select-resource';

const editor = await ClassicEditor.create(element, {
  plugins: [
    // ... 其他插件
    SelectResource,
  ],
  toolbar: [
    // ... 其他按钮
    'selectResource',  // 工具栏按钮名称
  ],
  selectResource: {
    resources: [
      {
        name: '示例文档.pdf',
        value: 'https://example.com/files/doc.pdf',
        filetype: 'pdf',
        attachmentId: 'att-001',
      },
      {
        name: '示例视频.mp4',
        value: 'https://example.com/files/video.mp4',
        filetype: 'mp4',
        src: 'https://example.com/files/video.mp4',
        attachmentId: 'att-002',
      },
    ],
    previewTypes: ['pdf', 'image'],
  },
});

3. Vue 中使用

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

const config = {
  editor: ClassicEditor,
  plugins: [/* ... */, SelectResource],
  toolbar: ['bold', 'italic', 'selectResource'],
  selectResource: {
    resources: [
      { name: '文件1.pdf', value: '/f1.pdf', filetype: 'pdf' },
      { name: '视频.mp4', value: '/v1.mp4', filetype: 'mp4', src: '/v1.mp4' },
    ],
    previewTypes: ['pdf'],
  },
};
</script>

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

配置项

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | resources | ResourceItem[] | 是 | 资源文件列表，用于弹窗选择 | | previewTypes | string[] | 否 | 可预览文件类型，在新窗口打开。默认空数组（全部下载） |

ResourceItem

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | 是 | 显示名称 | | value | string | 是 | 文件 URL；预览类型用作 href，非预览类型显示文件名并作为回退 | | filetype | string | 是 | 文件类型标识，如 pdf、mp4、image | | src | string | 否 | 视频源地址（仅 mp4 类型需要） | | attachmentId | string | 否 | 附件唯一标识 | | attachmentUrl | string | 否 | 附件下载链接，非预览类型优先使用该地址 |

输出 HTML

插件根据 filetype 输出不同的 HTML：

非 MP4 文件（如 PDF、图片等）

<!-- 预览类型（previewTypes 包含该类型） -->
<a class="ck-qst-file ck-qst-file--resource ck-qst-file-pdf ck-qst-file--has-icon"
   href="https://example.com/files/doc.pdf"
   title="示例文档.pdf"
   data-filetype="pdf"
   attachmentid="att-001"
   target="_blank">
  <span class="ck-qst-file-icon"><svg>...</svg></span>
  示例文档.pdf
</a>

<!-- 非预览类型且有 attachmentUrl：点击下载 -->
<a class="ck-qst-file ck-qst-file--resource ck-qst-file-doc ck-qst-file--has-icon"
   href="https://example.com/api/download/att-002"
   title="文档.doc"
   data-filetype="doc"
   attachmentid="att-002"
   data-attachmenturl="https://example.com/api/download/att-002"
   download="download">
  <span class="ck-qst-file-icon"><svg>...</svg></span>
  文档.doc
</a>

<!-- 非预览类型且无 attachmentUrl：不可点击 -->
<a class="ck-qst-file ck-qst-file--resource ck-qst-file-doc ck-qst-file--has-icon"
   title="文档.doc"
   data-filetype="doc"
   attachmentid="att-002">
  <span class="ck-qst-file-icon"><svg>...</svg></span>
  文档.doc
</a>

MP4 文件

<iframe class="ck-select-resource ck-select-resource-iframe"
        title="示例视频.mp4"
        href="https://example.com/files/video.mp4"
        src="https://example.com/files/video.mp4"
        data-filetype="mp4">
</iframe>

数据兼容性

插件在 upcast（粘贴/加载 HTML）时兼容以下格式：

| 当前输出 | 历史兼容 | |--------|--------| | <a class="ck-qst-file ck-qst-file--resource"> | <a class="ck-select-resource"> | | <a class="ck-qst-file ck-qst-file--resource"> | <a class="ckedit-file"> | | <iframe class="ck-select-resource ck-select-resource-iframe"> | <iframe class="ckedit-file ckedit-file-iframe"> |

旧版 HTML 会被自动转换为新版数据模型，保存时输出新版格式。

注：从 v1.1.0 起，非 MP4 资源在编辑器中复用 @itshixun/qckeditor-plugin-file-display 的显示样式，data downcast 输出类名由 ck-select-resource 统一为 ck-qst-file ck-qst-file--resource。upcast 同时兼容新版输出与旧版 ck-select-resource / ckedit-file，已有内容可正常渲染和编辑。

类型支持

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

const config: EditorConfig = {
  // 无类型错误，selectResource 已声明
  selectResource: { resources: [...] },
};

导出 API

import {
  SelectResource,        // 主插件（Editing + UI）
  SelectResourceEditing, // 编辑插件（Schema + Conversion + Command）
  SelectResourceUI,      // UI 插件（工具栏按钮 + 弹窗）
  SelectResourceCommand, // 命令
  ResourceFormView,      // 弹窗视图
  insertResource,        // 工具函数：插入资源元素
  isResourceAllowed,     // 工具函数：检查是否允许插入
  type ResourceItem,
  type SelectResourceConfig,
  type SelectResourceCommandOptions,
} from '@itshixun/qckeditor-plugin-select-resource';