Vue3 怎么整合 TinyMCE？从基础配置到进阶玩法一次讲透

terry 3小时前阅读数 4 #Vue

文章标签 Vue3；TinyMCE

做Vue3项目时，富文本编辑器是绕不开的需求，从简单的“写段带格式的文字”到复杂的“插入表格、上传图片、自定义样式”，TinyMCE 凭借强大功能和灵活性成了很多团队的选择，但刚接触时，“怎么装？怎么改工具栏？图片咋上传？”这些问题能把人搞懵，这篇用问答形式，把 Vue3 + TinyMCE 从基础到进阶的知识点拆碎了讲,新手也能跟着走通。

为啥在 Vue3 项目里优先选 TinyMCE？

先看需求：富文本要支持“格式刷、多级列表、表格合并、代码块、媒体嵌入”这些功能，还要能自定义 UI、对接后端上传，甚至做企业级权限控制，TinyMCE 刚好能覆盖这些场景——

功能完整性：官方自带 50+ 插件，从“粘贴时自动清理格式”到“AI 辅助写作”（需付费插件）都能扩展,基础版免费功能也够日常用。
框架友好度：有官方维护的 @tinymce/tinymce-vue 包，对 Vue3 的 Composition API、双向绑定做了适配,不用自己折腾指令或组件封装。
定制灵活性：工具栏、菜单栏、弹窗样式都能通过配置项改，还支持注入自定义按钮、插件，比如给编辑器加个“插入商品卡片”的业务按钮。
企业级支持：如果项目需要合规性、SLA 服务，TinyMCE 有商业版可选，小团队用免费版也能满足 80% 场景。

对比其他编辑器，Quill 轻量但扩展插件少，CKEditor 5 配置复杂且免费版功能受限，TinyMCE 属于“全能型选手”,适合需求多变的中大型项目。

Vue3 整合 TinyMCE 第一步：环境准备和安装

先把依赖装对，否则启动就报错,操作分两步：

（1）安装核心依赖

用 npm 安装官方 Vue 组件和 TinyMCE 核心包：

npm install @tinymce/tinymce-vue tinymce

@tinymce/tinymce-vue 是 Vue 封装的组件，负责和 Vue3 生态（比如响应式、组件生命周期）对接；
tinymce 是编辑器核心脚本，包含基础功能和默认插件。

（2）处理资源加载（关键！否则编辑器不显示）

TinyMCE 运行需要加载皮肤（skins）、插件（plugins）等静态资源，有两种方式：

方式 A：用官方 CDN（适合快速试玩）

在 index.html 里引入 CDN 资源，同时配置 apiKey（去 TinyMCE 官网免费申请，否则会有加载延迟提示）：

<head>  
  <script src="https://cdn.tiny.cloud/1/你的apiKey/tinymce/6/tinymce.min.js" referrerpolicy="origin"></script>  
</head>

然后在组件里用 Editor 时，TinyMCE 会从 CDN 拉取资源。

方式 B：自托管资源（适合国内项目，避免 CDN 不稳定）

把 node_modules/tinymce 里的 skins、plugins、tinymce.min.js 复制到项目的 public/tinymce 目录，然后在组件里配置 base_url，告诉编辑器去哪找资源：

import { Editor } from '@tinymce/tinymce-vue'  
const init = {  
  base_url: '/tinymce/', // 对应 public/tinymce 目录  
  suffix: '.min', // 加载压缩版脚本  
  // 其他配置...  
}

基础配置：写个最简单的富文本编辑器组件

先实现“能输入、能加粗、能改字号”的基础功能,步骤如下：

（1）创建 Vue 组件（单文件组件示例）

<template>  
  <div class="editor-wrap">  
    <Editor  
      :init="init"  
      v-model="content"  
    />  
  </div>  
</template>  
<script setup>  
import { ref } from 'vue'  
import Editor from '@tinymce/tinymce-vue' // 引入封装好的组件  
const content = ref('') // 绑定编辑器内容  
const init = {  
  // 配置编辑器核心功能  
  plugins: 'lists bold italic', // 启用的插件：列表、加粗、斜体  
  toolbar: 'undo redo | bold italic | bullist numlist', // 工具栏按钮分组  
  menubar: false, // 隐藏顶部菜单栏（简化界面）  
  content_style: 'body { font-size: 14px; line-height: 1.6; }', // 编辑器内样式，和页面统一  
}  
</script>  
<style scoped>  
.editor-wrap {  
  width: 800px;  
  margin: 20px auto;  
}  
</style>

（2）关键配置项解释

plugins：要启用的插件名，image（图片上传）、table（表格）、code（代码块）都需要在这里声明，否则功能按钮点了没反应。
toolbar：用空格分隔按钮，用来分组。undo redo 是撤销/重做，bold italic 是加粗/斜体。
content_style：设置编辑器内部的样式，避免和页面样式冲突（比如页面字体是 14px，编辑器里默认是 16px，就会不协调）。

自定义工具栏：让编辑器更贴合业务

产品经理说“要加个‘插入优惠券’按钮”“工具栏要分成‘格式区’和‘业务区’”,这时候得自定义工具栏和按钮。

（1）工具栏分组与精简

比如把“撤销/重做”“格式刷”“对齐方式”分成三组：

toolbar: 'undo redo | formatpainter | alignleft aligncenter alignright',

（2）添加自定义按钮

假设要加个“插入公司标语”的按钮，点击后自动插入一段文字，步骤：

在 init 里用 setup 函数注册按钮：

const init = {  
  setup(editor) {  
    // 注册自定义按钮  
    editor.ui.registry.addButton('custom标语', {  
      text: '插入标语',  
      icon: 'heart', // 用内置图标（可选），也可以自定义图片  
      onAction() {  
        editor.insertContent('【本活动最终解释权归公司所有】')  
      }  
    })  
  },  
  toolbar: 'undo redo | custom标语 | bold', // 把自定义按钮加到工具栏  
  // 其他配置...  
}

（3）隐藏多余元素（菜单栏、状态栏）

如果做“极简编辑器”，可以把顶部菜单栏和底部状态栏隐藏：

menubar: false, // 隐藏顶部菜单（File、Edit 那些）  
statusbar: false, // 隐藏底部状态栏（字数统计等）

图片上传：把编辑器里的图片传到自己服务器

默认情况下，TinyMCE 插入图片是“转成 base64 存在内容里”，但图片大了会让内容体积爆炸，必须改成“上传到后端服务器，存 URL”。

（1）配置 `images_upload_handler`

在 init 里加上传逻辑：

const init = {  
  plugins: 'image', // 先启用 image 插件  
  toolbar: 'image', // 工具栏显示“插入图片”按钮  
  images_upload_handler: (blobInfo, progress) => {  
    // blobInfo 包含图片文件信息，progress 是上传进度回调（可选）  
    return new Promise((resolve, reject) => {  
      const formData = new FormData()  
      formData.append('file', blobInfo.blob(), blobInfo.filename())  
      // 用 axios 发请求到后端接口  
      axios.post('/api/upload-image', formData, {  
        onUploadProgress: (e) => {  
          progress(e.loaded / e.total * 100) // 通知编辑器上传进度  
        }  
      }).then(res => {  
        if (res.data.code === 200) {  
          // 后端返回图片的 URL，res.data.data.url  
          resolve(res.data.data.url)  
        } else {  
          reject('上传失败')  
        }  
      }).catch(err => {  
        reject(err.message)  
      })  
    })  
  },  
  images_upload_credentials: true, // 跨域请求时带 cookie（如果需要）  
}

（2）后端需要做什么？

后端接口要接收 multipart/form-data 格式的文件，保存到服务器或云存储，然后返回图片的访问 URL，示例（Node.js + Express）：

app.post('/api/upload-image', (req, res) => {  
  const file = req.files.file  
  const filename = Date.now() + '-' + file.name  
  // 保存到本地或OSS等  
  file.mv(`./uploads/${filename}`, (err) => {  
    if (err) return res.status(500).send(err)  
    res.send({ code: 200, data: { url: `http://你的域名/uploads/${filename}` } })  
  })  
})

（3）额外优化：图片预览和 alt 文本

让用户上传前能预览，且必须填 alt 文本（ accessibility 友好）：

images_preview_max_width: 200, // 上传前预览图最大宽度  
images_alt_source: true, // 允许用户编辑 alt 文本  
images_upload_tab: true, // 显示“上传”标签页（默认是“插入图片URL”和“上传”两个标签）

和 Vue3 生态深度整合：结合 Pinia、路由场景

实际项目里，编辑器内容要存到状态管理工具（Pinia），或者路由切换时保存草稿，这些场景得结合 Vue3 生态处理。

（1）和 Pinia 双向绑定

假设用 Pinia 管理文章内容：

<template>  
  <Editor :init="init" v-model="articleStore.content" />  
</template>  
<script setup>  
import { useArticleStore } from '@/stores/article'  
const articleStore = useArticleStore()  
const init = { /* 配置 */ }  
</script>

Pinia 的 content 状态变化时，编辑器会自动更新；编辑器内容变化时，也会同步到 Pinia。

（2）路由切换时保存内容

用 Vue Router 的导航守卫，离开页面时把编辑器内容存到 Pinia 或 localStorage：

import { onBeforeRouteLeave } from 'vue-router'  
onBeforeRouteLeave((to, from, next) => {  
  // 假设 content 是编辑器绑定的响应式变量  
  articleStore.saveContent(content.value)  
  next()  
})

（3）用 Teleport 解决弹窗被遮挡

TinyMCE 的“图片上传弹窗”“链接插入弹窗”可能被父元素的 overflow: hidden 挡住，用 Vue3 的 Teleport 把弹窗移到 body 下：

<template>  
  <Teleport to="body">  
    <Editor :init="init" v-model="content" />  
  </Teleport>  
</template>

性能优化：页面加载快，编辑器不卡顿

如果页面有多个编辑器，或者 TinyMCE 加载慢,得做性能优化。

（1）静态资源本地化（提速 50%+）

前面提到的“自托管资源”能避免 CDN 延迟，把 node_modules/tinymce 里的 skins、plugins 复制到 public/tinymce，然后配置：

init: {  
  base_url: '/tinymce/',  
  suffix: '.min',  
  // 只加载需要的插件，减少体积  
  plugins: 'bold image lists',  
}

（2）组件懒加载（首屏更快）

如果编辑器不在首屏，用 defineAsyncComponent 延迟加载：

import { defineAsyncComponent } from 'vue'  
const Editor = defineAsyncComponent(() => import('@tinymce/tinymce-vue'))

（3）销毁实例（避免内存泄漏）

多个页面切换时，旧页面的编辑器实例没销毁，会占内存，在组件卸载时销毁：

import { onUnmounted } from 'vue'  
let editorInstance = null  
const init = {  
  setup(editor) {  
    editorInstance = editor  
  }  
}  
onUnmounted(() => {  
  if (editorInstance) {  
    editorInstance.destroy()  
    editorInstance = null  
  }  
})

常见坑点排查：这些问题你遇到过吗？

整合过程中容易踩坑,提前避坑能省几小时debug时间。

（1）编辑器加载慢，一直显示“Loading...”

原因：没配置 apiKey 且用了官方 CDN，TinyMCE 会延迟加载；或者自托管资源路径配错。
解决：去官网申请免费 apiKey，或检查 base_url 是否指向正确的静态资源目录。

（2）v-model 双向绑定失效

原因：@tinymce/tinymce-vue 对 Vue3 的 v-model 支持是通过 model-value 和 update:model-value 实现的，旧版本可能有兼容问题。

解决：确保依赖版本最新，或者手动绑定：

<Editor  
  :model-value="content"  
  @update:model-value="content = $event"  
  :init="init"  
/>

（3）自定义插件/按钮不生效

原因：plugins 没包含对应插件，或自定义按钮注册时 ID 冲突。
解决：检查 plugins 配置，确保自定义按钮的 ID（如 custom标语）没被官方按钮占用。

（4）图片上传返回 403/跨域错误

原因：后端没配置 CORS，或 images_upload_credentials 没设为 true（跨域带 cookie 时需要）。
解决：后端添加 CORS 响应头（如 Access-Control-Allow-Origin: *），前端设置 images_upload_credentials: true。

（5）编辑器样式和页面冲突

原因：页面的全局样式（如 body {} .container {} ）影响了编辑器内部。

解决：在 content_style 里重置样式，

content_style: `  
  body { margin: 0; padding: 0; }  
  p { margin: 10px 0; }  
`

从基础安装到图片上传，再到和 Vue3 生态深度结合，TinyMCE 能满足大多数富文本场景，但整合时要注意资源加载、配置项细节、性能优化这些点，如果是团队协作项目，建议把编辑器封装成通用组件，把 init 配置、上传逻辑抽成可配置参数，这样不同页面复用更方便，后续如果要做“多人协作编辑”“版本回溯”这类高级功能，TinyMCE 也有对应的商业插件或开源社区方案,值得继续探索～

版权声明

本文仅代表作者观点，不代表Code前端网立场。
本文系作者Code前端网发表，如需转载，请注明页面地址。

上一篇：Vue3 里怎么实现页面跳转？不同场景下有哪些方法？

发表评论:取消回复

◎欢迎参与讨论，请在这里发表您的看法、交流您的观点。