簡(jiǎn)介圍繞 Tinymce 富文本編輯器的使用與配置整理而成的示例資源面向需要在 Web 項(xiàng)目中集成所見即所得編輯能力的前端開發(fā)者重點(diǎn)解決 Tinymce 的安裝引入、語言包國際化以及工具欄與工具欄組自定義等常見問題也適合剛接觸編輯器二次開發(fā)的學(xué)習(xí)者參考。資源共 758 個(gè)文件大小約 2.9MB以 PNG 圖片、JS 腳本、CSS 樣式為主附帶 Vue 組件、HTML 頁面、JSON 配置與少量字體文件目錄結(jié)構(gòu)貼近真實(shí)項(xiàng)目便于按模塊查找。已有 119 人瀏覽學(xué)習(xí)。從 tinymce-demo 項(xiàng)目骨架中可查看完整的編輯器初始化與銷毀、皮膚樣式定制、語言包資源配置、工具欄組按鈕排序方式等關(guān)鍵實(shí)現(xiàn)同時(shí)還能了解轉(zhuǎn)譯、依賴管理、說明文檔等配置文件在項(xiàng)目中的作用以及各類靜態(tài)資源在編輯器皮膚和界面展示中的分工。整體適合直接復(fù)用或按需調(diào)整。 最近給公司的后臺(tái)管理系統(tǒng)換編輯器在Tinymce上折騰了整整兩天。從安裝、初始化到語言包配置再到工具欄定制一路踩坑一路填坑。趁熱把整個(gè)實(shí)踐過程整理出來給正在用或者準(zhǔn)備用Tinymce的同行做個(gè)參考。之所以選Tinymce主要是因?yàn)樗诟晃谋揪庉嬈骼飳儆诶吓七x手功能扎實(shí)、插件生態(tài)完整表格、圖片、鏈接、代碼塊這些高頻功能開箱即用不需要像某些輕量編輯器那樣到處拼輪子。而且它的定制能力很強(qiáng)從工具欄按鈕到插件擴(kuò)展都有完善的API。當(dāng)然代價(jià)就是配置項(xiàng)多第一次接觸容易懵尤其是語言包和工具欄這塊官方文檔寫得比較散網(wǎng)上資料又新舊混雜照著抄經(jīng)常踩坑。這篇文章我會(huì)從三個(gè)核心主題展開Tinymce的基本使用和初始化、語言包配置的原理與實(shí)操、工具欄與工具欄組的定制方法。每一部分都會(huì)給出完整的代碼示例和我在實(shí)際項(xiàng)目中踩過的坑希望能幫你少走些彎路。1. Tinymce快速上手與初始化先說結(jié)論Tinymce的初始化和使用沒有想象中復(fù)雜核心就是一個(gè)tinymce.init()方法關(guān)鍵是把selector、plugins、toolbar這幾個(gè)配置項(xiàng)搞明白編輯器就能跑起來。但這里面有不少容易忽略的細(xì)節(jié)比如資源文件路徑、主題皮膚加載、內(nèi)容樣式隔離等我會(huì)逐個(gè)說明。1.1 環(huán)境準(zhǔn)備與安裝方式Tinymce目前主流的接入方式有兩種通過npm包管理依賴或者通過CDN直接引入。如果你用的是Vue、React這類工程化項(xiàng)目建議走npm方便版本管理和后續(xù)定制。以npm方式舉例核心依賴就兩個(gè)npm install tinymce如果是Vue3項(xiàng)目還需要安裝官方的封裝組件npm install tinymce/tinymce-vue這里有一個(gè)關(guān)鍵點(diǎn)安裝完成后僅僅import tinymce是不夠的。Tinymce的運(yùn)行依賴它的靜態(tài)資源文件themes、skins、plugins這些目錄npm包默認(rèn)不會(huì)自動(dòng)暴露這些文件需要手動(dòng)把它們拷貝到項(xiàng)目的靜態(tài)資源目錄。在Vue3 Vite項(xiàng)目里我一般這樣做// vite.config.js 或者在 main.js 里設(shè)置 import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], assetsInclude: [**/*.js], })更通用的做法是在public目錄下建一個(gè)tinymce文件夾然后把node_modules里的核心目錄拷進(jìn)去cp -r node_modules/tinymce/themes public/tinymce/ cp -r node_modules/tinymce/skins public/tinymce/ cp -r node_modules/tinymce/plugins public/tinymce/如果漏掉這步編輯器能初始化但界面會(huì)丟失樣式甚至插件按鈕全部失效。我在第一次接入時(shí)就漏了皮膚文件折騰了好久才發(fā)現(xiàn)是這個(gè)問題。1.2 初始化配置的核心參數(shù)Tinymce的所有配置都在tinymce.init()里完成下面是我在實(shí)際項(xiàng)目中總結(jié)的一套最小可用配置tinymce.init({ selector: #editor, height: 500, menubar: true, plugins: [ advlist, autolink, lists, link, image, charmap, preview, anchor, searchreplace, visualblocks, code, fullscreen, insertdatetime, media, table, help, wordcount ], toolbar: undo redo | blocks | bold italic forecolor | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | removeformat | help, content_style: body { font-family:Helvetica,Arial,sans-serif; font-size:16px } })幾個(gè)關(guān)鍵配置項(xiàng)說明selectorCSS選擇器指定哪個(gè)元素被替換為編輯器。一般是一個(gè)textarea的id。plugins插件數(shù)組決定編輯器支持哪些擴(kuò)展能力。注意如果某個(gè)插件沒在plugins里聲明即便你在toolbar里寫了對(duì)應(yīng)按鈕也不會(huì)生效。toolbar工具欄按鈕配置用空格分隔按鈕用豎線|做分組。content_style編輯區(qū)域的樣式。這里有個(gè)小細(xì)節(jié)Tinymce編輯區(qū)域是iframe隔離的外部樣式不會(huì)作用于編輯區(qū)域所以需要在這里定義內(nèi)容的基礎(chǔ)字體和行距。menubar是否顯示頂部菜單欄。如果設(shè)為false工具欄就只剩一行按鈕界面更簡(jiǎn)潔但會(huì)失去一些高級(jí)功能入口。這里特別提醒一下init方法執(zhí)行后返回一個(gè)Promise如果配置出錯(cuò)Promise會(huì)reject但很多時(shí)候錯(cuò)誤信息并不直觀。如果編輯器一直不出現(xiàn)優(yōu)先打開瀏覽器的Network面板看看有沒有404請(qǐng)求這是最快定位問題的手段。1.3 組件的封裝思路直接用原生tinymce.init()也沒有問題但在現(xiàn)代前端框架里我更推薦封裝成一個(gè)獨(dú)立的Editor組件。這樣做的好處是生命周期可以自動(dòng)管理組件銷毀時(shí)能調(diào)用tinymce.remove()清理實(shí)例避免內(nèi)存泄漏多個(gè)頁面復(fù)用編輯器時(shí)只需要通過props傳遞配置即可。以Vue3為例封裝思路大致是template textarea refeditorRef/textarea /template script setup import { onMounted, onBeforeUnmount, ref, watch } from vue import tinymce from tinymce const props defineProps({ modelValue: String, apiKey: String, toolbar: String, plugins: Array }) const editorRef ref(null) let editor null onMounted(async () { editor await tinymce.init({ selector: #${editorRef.value.id}, value: props.modelValue, plugins: props.plugins, toolbar: props.toolbar, setup(ed) { ed.on(input change undo redo, () { const content ed.getContent() emit(update:modelValue, content) }) } }) }) onBeforeUnmount(() { tinymce.remove(editor) }) /script這種封裝模式我已經(jīng)用了很久穩(wěn)定性很好。唯一的坑是tinymce.remove()如果傳了實(shí)例對(duì)象部分老版本可能識(shí)別不了建議直接傳selector字符串tinymce.remove(#editor)。2. 語言包配置詳解從原理到實(shí)操語言包配置是很多人第一次用Tinymce時(shí)最容易卡住的地方。默認(rèn)情況下Tinymce界面是英文的如果你直接設(shè)置language: zh_CN但沒加載對(duì)應(yīng)語言包編輯器會(huì)加載失敗或報(bào)錯(cuò)這個(gè)坑我見過太多次了。2.1 語言包的加載機(jī)制首先理解Tinymce的語言包機(jī)制Tinymce本身不內(nèi)置任何語言文件它會(huì)在初始化時(shí)根據(jù)language配置項(xiàng)去請(qǐng)求一個(gè)對(duì)應(yīng)的語言代碼.js文件。比如設(shè)置language: zh_CN它就會(huì)嘗試加載zh_CN.js這個(gè)文件。這個(gè)文件默認(rèn)從CDN加載官方CDN地址是https://cdn.tiny.cloud/1/{apiKey}/tinymce/langs/zh_CN.js注意這個(gè)CDN地址帶了apiKey參數(shù)這是Tinymce 5以后的規(guī)定。如果你沒有申請(qǐng)Tiny Cloud的API Key瀏覽器會(huì)返回403錯(cuò)誤語言包自然加載失敗編輯器初始化也會(huì)中斷。解決思路有兩個(gè)第一種是申請(qǐng)Tiny Cloud的免費(fèi)API Key官方以key區(qū)分是否免費(fèi)賬戶個(gè)人項(xiàng)目用免費(fèi)額度足夠了。但企業(yè)內(nèi)部項(xiàng)目尤其是內(nèi)網(wǎng)部署的場(chǎng)景CDN可能根本訪問不到這就得用第二種方案。第二種是下載語言包并放到本地通過language_url配置項(xiàng)指定本地路徑。這也是我推薦的做法。官方GitHub倉庫tinymce-langs里有所有語言包的文件直接下載zh_CN.js放到項(xiàng)目的public/tinymce/langs/目錄即可。2.2 中文語言包配置實(shí)操完整的本地化配置需要三個(gè)配置項(xiàng)配合tinymce.init({ selector: #editor, language: zh_CN, language_url: /tinymce/langs/zh_CN.js, // 其他配置 })language指定語言代碼中文填zh_CN。language_url語言包文件的本地地址。這個(gè)配置項(xiàng)如果沒有設(shè)置Tinymce才回去請(qǐng)求CDN設(shè)置了就用本地文件。如果你使用的是npm包方式還有一種更干凈的做法直接通過import引入語言包文件。在main.js或組件入口處引入import tinymce/langs/zh_CN這樣語言包會(huì)被打包進(jìn)最終的構(gòu)建產(chǎn)物不需要手動(dòng)拷貝文件到靜態(tài)目錄也不會(huì)有路徑問題。但要注意這種方式要求語言包文件就在tinymce/langs/下npm包默認(rèn)是不帶語言包的需要自己去官方倉庫下載后放到該目錄或者直接用CDN版本的語言包覆蓋。實(shí)際測(cè)試下來官方CDN的語言包和本地文件在格式上沒有差異都是向tinymce.addI18n()注冊(cè)翻譯字典。如果你有自己的翻譯需求直接改這個(gè)js文件里的字典即可不需要額外寫插件。2.3 語言包加載失敗的定位與解決我總結(jié)了三種最常見的語言包加載失敗場(chǎng)景現(xiàn)象原因解決方案控制臺(tái)顯示zh_CN.js 404本地目錄沒有該文件或路徑寫錯(cuò)檢查public下文件路徑確保language_url相對(duì)路徑正確控制臺(tái)顯示403走了官方CDN但沒有API Key設(shè)置language_url使用本地文件界面顯示中文但部分按鈕還是英文插件語言包未加載檢查插件對(duì)應(yīng)語言文件部分第三方插件需要單獨(dú)引入語言文件其中第三種情況比較容易忽略。比如table插件的中文翻譯在核心語言包里就有但如果你用了a11ychecker這種高級(jí)插件它自己還有一套語言文件。遇到這種情況直接在插件初始化時(shí)傳入tinymce實(shí)例的language即可不用額外處理。另外一個(gè)細(xì)節(jié)如果頁面里有多個(gè)編輯器實(shí)例每個(gè)實(shí)例都要單獨(dú)配置language嗎答案是可以在全局統(tǒng)一處理。在tinymce.init()之前調(diào)用tinymce.addI18n()手動(dòng)注冊(cè)語言包然后所有實(shí)例就都能共享了。3. 工具欄與工具欄組定制全解等你把編輯器和語言包都跑通了接下來做得最多的就是按照業(yè)務(wù)需求調(diào)整工具欄。這塊初看簡(jiǎn)單無非就是增刪按鈕但深入進(jìn)去會(huì)發(fā)現(xiàn)有很多組合技巧包括按鈕分組、多行排列、下拉菜單嵌套、自定義按鈕等。3.1 工具欄配置基礎(chǔ)按鈕、分組與排列工具欄配置使用toolbar字段它是一個(gè)字符串由按鈕名稱button name和分隔符組成空格表示按鈕間隔豎線|表示分組。toolbar: undo redo | bold italic underline | bullist numlist這個(gè)配置會(huì)產(chǎn)生三個(gè)區(qū)域左側(cè)撤銷/重做中間文字加粗/斜體/下劃線右側(cè)有序/無序列表。組與組之間會(huì)出現(xiàn)一條豎直分隔線視覺上更清晰也方便用戶按功能區(qū)域?qū)ふ野粹o。如果你需要配置多行工具欄Tinymce 5以后支持在toolbar字符串里用||分隔不同行toolbar: undo redo | styles | bullist numlist | alignleft aligncenter alignright | link image | table | fullscreen || bold italic underline strikethrough | forecolor backcolor | removeformat | code兩行工具欄會(huì)自動(dòng)換行顯示第一行放高頻操作和需要視覺寬度的控件第二行放字符格式類操作。實(shí)際布局時(shí)要注意如果你的編輯器容器寬度有限多行工具欄會(huì)把編輯區(qū)域壓縮得很矮此時(shí)需要適當(dāng)增加編輯器的整體高度。工具欄是否換行還和toolbar_mode配置有關(guān)。默認(rèn)是scrolling模式按鈕超出寬度時(shí)會(huì)出現(xiàn)小箭頭展開更多如果你希望按鈕自動(dòng)換行而不是收縮改成toolbar_mode: wrap這樣工具欄按鈕會(huì)像文本一樣自動(dòng)換行不會(huì)藏起來。3.2 工具欄組的自定義與嵌套除了基礎(chǔ)的單按鈕排列Tinymce還支持上拉菜單和嵌套分組。最常用的場(chǎng)景是把一類功能收進(jìn)一個(gè)下拉按鈕里比如“插入”功能下掛圖片、媒體、表格、文件等。實(shí)現(xiàn)方式有兩種。一種是直接使用Tinymce預(yù)置的按鈕比如insert就是一個(gè)包含多項(xiàng)插入功能的按鈕組toolbar: insert | undo redo | ...另一種是使用setup配置項(xiàng)通過editor.ui.registry.addGroupToolbar創(chuàng)建自定義分組。這個(gè)方法在Tinymce 5.2以后可用使用場(chǎng)景相對(duì)高級(jí)一般項(xiàng)目中用預(yù)置按鈕組就夠用了。如果是更復(fù)雜的嵌套下拉菜單可以使用addMenuItem配合addContextToolbar。例如給選中圖片時(shí)單獨(dú)彈出一條格式工具欄setup(editor) { editor.ui.registry.addContextToolbar(imageToolbar, { predicate: (node) node.nodeName IMG, items: alignleft aligncenter alignright | image tooltip }) }這個(gè)配置的效果是鼠標(biāo)選中圖片時(shí)編輯器會(huì)對(duì)當(dāng)前選區(qū)上下文自動(dòng)彈出工具欄方便快速調(diào)整圖片位置和樣式。這種體驗(yàn)很順手很多成熟產(chǎn)品都在用。3.3 常用工具欄配置速查與排列建議下面是一套我整理的中文后臺(tái)系統(tǒng)常用的配置模板覆蓋了內(nèi)容編輯、排版、插入對(duì)象、協(xié)作代碼等場(chǎng)景toolbar: undo redo | blocks fontfamily fontsize | bold italic underline strikethrough | forecolor backcolor | alignleft aligncenter alignright alignjustify | lineheight | bullist numlist outdent indent | table link image media | removeformat fullscreen preview code對(duì)應(yīng)的插件配置plugins: [ advlist, autolink, lists, link, image, charmap, preview, anchor, searchreplace, visualblocks, code, fullscreen, insertdatetime, media, table, wordcount ]這套配置有幾點(diǎn)考慮blocks按鈕用來切換段落、標(biāo)題1到標(biāo)題6是文章排版最常用的按鈕。forecolor和backcolor分別控制文字顏色和背景高亮做文章標(biāo)注很實(shí)用。lineheight是行高插件按鈕需要配合插件才能出現(xiàn)如果你沒有裝對(duì)應(yīng)插件寫了也不會(huì)生效。fullscreen對(duì)后臺(tái)內(nèi)容管理特別重要編輯長(zhǎng)文章時(shí)全屏模式能大幅提升體驗(yàn)。code按鈕可以讓用戶直接查看和編輯HTML源碼這是很多業(yè)務(wù)場(chǎng)景的硬需求。值得注意的是Tinymce不同版本對(duì)同一功能的按鈕命名可能有差異。比如hr插入水平線按鈕Tinymce 5里面要用hr插件Tinymce 6里可能需要額外注意命名。遇到按鈕不顯示時(shí)先確認(rèn)插件是否加載再確認(rèn)按鈕名稱是否準(zhǔn)確不要盲目改配置。3.4 加載插件與自定義按鈕的補(bǔ)充玩法如果你不想滿足于系統(tǒng)預(yù)置的按鈕Tinymce也支持自定義工具欄按鈕。方法就是在setup里通過editor.ui.registry.addButton注冊(cè)一個(gè)新按鈕然后在toolbar字符串里直接使用按鈕idsetup(editor) { editor.ui.registry.addButton(myExportWord, { text: 導(dǎo)出Word, onAction: () { // 在這里調(diào)用導(dǎo)出邏輯 console.log(導(dǎo)出Word) } }) }, toolbar: undo redo | myExportWord這里有一個(gè)小建議自定義按鈕的功能邏輯不要直接寫在組件里而是盡量抽成獨(dú)立的工具函數(shù)或模塊。因?yàn)榫庉嬈骺赡軙?huì)在多個(gè)頁面復(fù)用寫在組件里會(huì)導(dǎo)致功能重復(fù)且難以維護(hù)。關(guān)于熱搜詞里提到的tinymce export to word插件下載我說下我的理解。官方插件里并沒有一個(gè)直接的Export to Word按鈕但可以通過引入powerpaste插件配合服務(wù)端轉(zhuǎn)換實(shí)現(xiàn)類似效果或者簡(jiǎn)單點(diǎn)直接獲取編輯器內(nèi)容后由后端生成Word。我自己的項(xiàng)目里是先獲取HTML內(nèi)容再通過后端服務(wù)轉(zhuǎn)換前端只做一個(gè)按鈕觸發(fā)這樣最省事。4. 常見問題與排查技巧實(shí)錄最后這部分我整理一下實(shí)際使用中遇到的高頻問題和排查思路有些是我自己踩過的坑有些是幫同事排查時(shí)積累的按照從簡(jiǎn)單到復(fù)雜的順序排列。4.1 初始化失敗與界面顯示異常編輯器完全沒渲染出來。優(yōu)先看控制臺(tái)有沒有報(bào)錯(cuò)。如果報(bào)錯(cuò)信息是tinymce is not defined說明腳本沒加載成功檢查靜態(tài)資源路徑。如果控制臺(tái)無聲無息但頁面空白多半是selector選錯(cuò)了元素常見于用className而不是id或者元素在編輯器初始化后才掛載到DOM上。編輯器渲染出來了但沒有樣式。這是皮膚文件沒加載導(dǎo)致的。確認(rèn)skins目錄已經(jīng)拷貝到靜態(tài)目錄并且在init里設(shè)置了skin: oxide。Tinymce 5/6默認(rèn)主題皮膚是oxide暗色主題是oxide-dark如果你自定義了皮膚名一定要確保對(duì)應(yīng)目錄存在。編輯器高度異?；騼?nèi)容區(qū)空白。優(yōu)先檢查是不是初始化時(shí)容器還沒渲染完畢。特別是在彈窗、抽屜這類動(dòng)態(tài)渲染的組件里需要等DOM掛載完成后再調(diào)用init或者用setTimeout延后執(zhí)行。4.2 內(nèi)容提交與展示時(shí)的常見問題編輯器內(nèi)容提交后前端展示出來樣式不對(duì)。這個(gè)問題的根源在于Tinymce編輯區(qū)域是iframe隔離的內(nèi)部有一套默認(rèn)樣式但提交到業(yè)務(wù)頁面后這層隔離就沒有了內(nèi)容直接由業(yè)務(wù)頁面的全局樣式渲染。解決方案是在業(yè)務(wù)展示端引入一份和編輯區(qū)域一致的內(nèi)容樣式或者使用content_css配置項(xiàng)指定編輯區(qū)域的樣式文件。我的做法是維護(hù)一個(gè)editor-content.css里面定義.ql-editor相關(guān)的樣式然后同時(shí)用于編輯器的content_css和業(yè)務(wù)展示頁的樣式引入保證WYSIWYG。提交后HTML里有大量多余標(biāo)簽。Tinymce默認(rèn)會(huì)保留很多語義化標(biāo)簽比如p、span等如果業(yè)務(wù)方不想要這些冗余代碼可以在init里配置forced_root_block: p或者在提交時(shí)通過getContent({ format: text })只提取純文本。多語言站點(diǎn)中語言包混亂。如果站點(diǎn)本身支持多語言切換需要在切換時(shí)動(dòng)態(tài)重新初始化編輯器。簡(jiǎn)單做法是銷毀現(xiàn)有實(shí)例再重新init復(fù)雜一點(diǎn)可以用tinymce.activeEditor.setLanguage()動(dòng)態(tài)切換。4.3 性能與體驗(yàn)優(yōu)化心得在低配置機(jī)器比如一些老的辦公電腦上Tinymce初始化會(huì)有明顯的卡頓感。我的經(jīng)驗(yàn)是通過plugins精簡(jiǎn)插件列表把用不到的插件全部移除尤其是powerpaste、spellchecker這種重量級(jí)插件能明顯縮短初始化時(shí)間。對(duì)于內(nèi)容特別長(zhǎng)的文章編輯和提交時(shí)都會(huì)比較吃力?？梢钥紤]配置autosave插件自動(dòng)保存草稿避免瀏覽器崩潰導(dǎo)致內(nèi)容丟失。再把編輯器的branding: false關(guān)掉頁面底部就不會(huì)顯示官方Logo了界面清爽不少。最后分享一個(gè)小經(jīng)驗(yàn)不管怎么定制工具欄都要保證核心編輯功能優(yōu)先。富文本編輯器最重要的是“能寫、能存、不丟內(nèi)容”工具欄花里胡哨是錦上添花千萬別本末倒置。我見過有同事寫了滿滿四大行工具欄結(jié)果整個(gè)編輯區(qū)域只剩巴掌大這種配置再炫也沒意義。Tinymce 6相關(guān)文檔比5清楚不少但實(shí)際上手時(shí)依然會(huì)有很多細(xì)枝末節(jié)的問題。這篇整理出來的內(nèi)容都是實(shí)打?qū)嵦幚磉^的坑照著配置能省下不少排查時(shí)間。如果你在接入過程中有別的問題也歡迎在評(píng)論區(qū)一起交流。本文還有配套的精品資源點(diǎn)擊獲取