@ulearning/vue3-editor

基于 TinyMCE 5.8.2 的 Vue 3 富文本编辑器组件，内置常用工具栏、语言包、图片上传和 TypeScript 类型声明。

• Vue：^3.3.0
• Node.js：>=20.19.0
• TinyMCE 5 官方文档：https://www.tiny.cloud/docs/tinymce/5/

安装

npm install @ulearning/vue3-editor

组件样式已打包，无需额外引入 TinyMCE CSS。

基本使用

<template>
  <UlEditor
    ref="editorRef"
    v-model="content"
    language="zh"
    :height="460"
    :options="editorOptions"
    :uploader-config="uploaderConfig"
    @ready="handleReady"
    @change="handleChange"
    @upload-error="handleUploadError"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import {
  UlEditor,
  type RawEditorOptions,
  type TinyMCEEditor,
  type UlEditorExpose,
  type UploaderConfig,
} from '@ulearning/vue3-editor'

const editorRef = ref<UlEditorExpose | null>(null)
const content = ref('<p>编辑器初始内容</p>')
const editorOptions: RawEditorOptions = { add_unload_trigger: false }
const uploaderConfig: UploaderConfig = {
  mode: 'huawei',
  uptokenHost: 'https://your-api.example.com',
  authorization: 'your-login-token',
}

function handleReady(editor: TinyMCEEditor) {
  console.log('editor ready', editor)
}

function handleChange(html: string) {
  console.log('content changed', html)
}

function handleUploadError(message: string) {
  console.error(message)
}

function readContent() {
  return editorRef.value?.getContent() || ''
}
</script>

也可以全局注册：

import { createApp } from 'vue'
import UlEditor from '@ulearning/vue3-editor'
import App from './App.vue'

createApp(App).use(UlEditor).mount('#app')

图片上传

华为 OBS

不传 uploadHandler 时，组件使用 ulearning-obs 上传。当前示例需要以下配置：

const uploaderConfig: UploaderConfig = {
  mode: 'huawei',
  uptokenHost: 'https://your-api.example.com',
  authorization: loginToken,
}

永久 AK/SK 不应写入前端。authorization 应使用登录态或后端签发的短期凭证。

自定义上传

传入 uploadHandler 后将完全接管图片上传，返回值必须是可持久访问的图片 URL，不能返回 Base64 或 blob: 临时地址。

async function uploadImage(file: Blob) {
  const form = new FormData()
  form.append('file', file, (file as File).name || `image-${Date.now()}.png`)

  const response = await fetch('/api/uploads/images', {
    method: 'POST',
    body: form,
  })
  if (!response.ok) throw new Error('图片上传失败')

  const result = await response.json()
  return result.url
}

<UlEditor v-model="content" :upload-handler="uploadImage" />

默认图片大小上限为 5 MB，可通过 maxImageSize 修改。图片类型通过 options.fileTypeLimit.image 配置：

const editorOptions: RawEditorOptions = {
  fileTypeLimit: {
    image: '.png,.jpg,.jpeg,.gif,.bmp',
  },
}

工具栏和插件

默认工具栏：

undo redo | fontselect | fontsizeselect | bold italic underline forecolor removeformat | numlist bullist indentgroup aligngroup | table imageupload

使用 toolbarOptions 自定义工具栏：

<UlEditor
  v-model="content"
  toolbar-options="undo redo | bold italic | searchreplace link formula"
  formula-url="https://your-formula-page.example.com"
/>

searchreplace、link 和 formula 会根据工具栏配置按需加载。使用 formula 时必须同时提供可访问的 formulaUrl。

视频或音频按钮需要在 toolbarOptions 中加入 videoupload 或 audioupload，并传入 uploadFile(file, type, editor)。

语言

通过 language 传入 TinyMCE 语言代码。英语使用 TinyMCE 默认文本，不需要额外语言文件。

| 语言 | language | | --- | --- | | English | en | | 中文 | zh | | 繁體中文 | tw | | Indonesia | id | | ไทย | th | | español | es | | العربية | ar | | français | fr | | português | pt | | русский | ru | | o'zbek | uz | | አማርኛ | am | | italiano | it | | Kiswahili | sw |

Props

| Prop | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | modelValue | string | '' | v-model 内容 | | value | string | undefined | 兼容旧版内容属性 | | height | number \| string | 500 | 编辑器高度 | | width | number \| string | '100%' | 编辑器宽度 | | allowPaste | boolean | true | 是否允许粘贴 | | autoFocus | boolean | false | 初始化后是否聚焦 | | toolbarOptions | string | 默认工具栏 | TinyMCE 工具栏配置 | | options | RawEditorOptions | {} | 其他 TinyMCE 配置 | | uploaderConfig | UploaderConfig | {} | ulearning-obs 配置 | | uploadHandler | ImageUploadHandler | null | 自定义图片上传方法 | | uploadFile | FileUploadHandler | null | 视频或音频上传方法 | | maxImageSize | number | 5 * 1024 * 1024 | 图片大小上限，单位为字节 | | language | string | 'en' | 编辑器语言代码 | | formulaUrl | string | '' | 公式编辑页面地址 |

options 会合并到默认 TinyMCE 配置中。默认已设置 add_unload_trigger: false，组件卸载时会调用 TinyMCE 实例的 remove()。

事件

| 事件 | 参数 | 说明 | | --- | --- | --- | | update:modelValue | html: string | 内容变化时更新 v-model | | change | html: string | TinyMCE change 事件 | | onChange | html: string | 兼容旧版事件名 | | ready | editor: TinyMCEEditor | 编辑器初始化完成 | | uploadError | message: string | 图片上传失败 |

公开方法

通过组件 ref 调用：

editorRef.value?.getEditor()
editorRef.value?.getContent()
editorRef.value?.setContent('<p>新内容</p>')

| 属性或方法 | 说明 | | --- | --- | | editor | 当前 TinyMCE 实例 | | editorComponent | 编辑器宿主 textarea | | getEditor() | 返回 TinyMCE 实例 | | getContent() | 返回当前 HTML | | setContent(html) | 替换内容并重置撤销记录 |

本地开发

npm install
npm run dev

运行完整检查：

npm run check

该命令依次执行 Vue/TypeScript 类型检查、发布类型检查、生产构建和包测试。源码示例位于 examples/。