OpenProject 富文本 WYSIWYG 編輯器完整指南CKEditor5 格式化、宏指令與資源鏈接實(shí)戰(zhàn)【免費(fèi)下載鏈接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ? Star us on GitHub項(xiàng)目地址: https://gitcode.com/GitHub_Trending/op/openprojectOpenProject 內(nèi)置了一套基于 CKSource CKEditor5 的準(zhǔn)所見即所得WYSIWYG富文本編輯器底層存儲(chǔ)格式為 GitHub 風(fēng)格的 CommonMarkGFM并擴(kuò)展了提及mentions、圖片尺寸調(diào)整等 HTML 能力。本文以 docs/user-guide/wysiwyg/README.md 為骨架結(jié)合倉庫前端編輯器配置源碼與后端文本格式化解析器系統(tǒng)講解格式化、圖片處理、鍵盤快捷鍵、宏指令、資源鏈接以及工作包/項(xiàng)目屬性嵌入等完整能力幫助你在一篇文章內(nèi)掌握 OpenProject 富文本編輯器的全部實(shí)戰(zhàn)用法。編輯器概覽GFM HTML 擴(kuò)展OpenProject 的編輯器基于 CKEditor5 構(gòu)建其內(nèi)容格式是 GitHub 風(fēng)格的 CommonMarkGFM。這意味著你在編輯器中看到的內(nèi)容與最終渲染結(jié)果基本一致同時(shí)編輯器支持在 Markdown 之上疊加額外的 HTML 能力例如提及mentions通過提及用戶圖片尺寸調(diào)整直接用鼠標(biāo)拖拽調(diào)整圖片大小。[!NOTE] 并非所有場景都提供完整功能。在工作包work package或評(píng)論等受限編輯器中宏指令、圖片上傳等功能會(huì)被裁剪在工作包分屏視圖詳情視圖中可能需要點(diǎn)擊編輯器右上角的三個(gè)豎點(diǎn)更多操作菜單才能訪問附加功能。從源碼結(jié)構(gòu)看這一完整版 vs 受限版的設(shè)計(jì)在前端有明確實(shí)現(xiàn)ckeditor-setup.service.ts 定義了ICKEditorType full|constrained兩種編輯器類型并分別掛載到window.OPClassicEditor與window.OPConstrainedEditor兩個(gè)構(gòu)建產(chǎn)物上ckeditor-setup.service.ts。創(chuàng)建編輯器實(shí)例時(shí)服務(wù)會(huì)根據(jù)上下文中的type選擇對應(yīng)的構(gòu)建const editorClass type constrained ? window.OPConstrainedEditor : window.OPClassicEditor;編輯器功能定位能力完整編輯器wiki 頁面、會(huì)議等受限編輯器工作包、評(píng)論等基礎(chǔ)格式化加粗、斜體、標(biāo)題、引用、行內(nèi)代碼??圖片上傳 / 粘貼 / 拖拽?視資源而定宏指令Macros?默認(rèn)不顯示可按需啟用代碼塊編輯通過 CodeMirror 模態(tài)框通過 CodeMirror 模態(tài)框關(guān)于受限編輯器的宏指令ckeditor-setup.service.ts 顯示受限編輯器默認(rèn)沒有宏下拉按鈕只有在上下文中顯式傳入宏列表Array.isArray(resolvedContext.macros)時(shí)才會(huì)通過constrainedToolbarWithMacroList()把macroList按鈕動(dòng)態(tài)插入到blockQuote之后ckeditor-setup.service.ts。基本格式化CKEditor5 構(gòu)建支持基礎(chǔ)文本樣式加粗、斜體、各級(jí)標(biāo)題、刪除線、行內(nèi)代碼、引用以及行內(nèi)圖片處理。從外部粘貼內(nèi)容圖片或富文本同樣支持未被支持的樣式會(huì)被編輯器自動(dòng)剝離保證輸出格式的干凈一致。換行按Enter會(huì)創(chuàng)建新段落若只想換行而不新建段落請按SHIFTEnter。鏈接創(chuàng)建超鏈接有兩種方式點(diǎn)擊工具欄的鏈接按鈕可先選中部分文本再點(diǎn)擊直接按CTRLKMac 為CMDK彈出鏈接輸入彈窗。Widget 與換行操作CKEditor 使用 Widget 來展示圖片、表格等塊級(jí)元素非行內(nèi)元素。絕大多數(shù) Widget 點(diǎn)擊即可選中唯一例外是表格 Widget需要點(diǎn)擊左上角的選擇柄才能選中整張表格。當(dāng) Widget 處于選中狀態(tài)時(shí)你可以刪除或剪切它還可以快速在其上方或下方插入新行在 Widget下方新建一行選中 Widget 后按ENTER或↓下箭頭在 Widget上方新建一行按SHIFTENTER或↑上箭頭。當(dāng) Widget 恰好位于頁面開頭或結(jié)尾時(shí)這一操作尤其必要——它是唯一能在 Widget 外圍插入空白行的方法。代碼塊由于 CKEditor5 目前不原生支持代碼塊編輯OpenProject 采取顯示與編輯分離的策略顯示代碼塊可以在 CKEditor 實(shí)例中正常展示編輯雙擊代碼塊會(huì)打開一個(gè)模態(tài)窗口在其中使用CodeMirror編輯器實(shí)例進(jìn)行編輯。CodeMirror 方案的優(yōu)勢是自帶語法高亮與代碼提示針對受支持的語言。從源碼看這一交互由 editor-macros.service.ts 的editCodeBlock(content, languageClass)驅(qū)動(dòng)最終渲染CodeBlockMacroModalComponent見 macro-code-block-modal/code-block-macro.modal.ts。表格GFM 規(guī)范為 CommonMark 增加了表格語法擴(kuò)展OpenProject 的 CKEditor 支持該擴(kuò)展。一個(gè)關(guān)鍵約束是所有 GFM 表格必須包含表頭行。對于在 CKEditor 中創(chuàng)建的、不含表頭行的表格編輯器會(huì)輸出為 HTMLtable而非 GFM 表格——這與 GitHub 的行為一致。Emojis在所有文本編輯器中都可以插入 emoji輸入一個(gè)冒號(hào)加一個(gè)字母例如:a編輯器會(huì)彈出可用的 emoji 建議列表供選擇。自動(dòng)格式化AutoformattingCKEditor5 支持類 CommonMark 的鍵盤自動(dòng)格式化輸入輸入**will become bold**生成加粗輸入_will become italic_生成斜體輸入#、##、###…… 生成不同層級(jí)的標(biāo)題行首輸入*或-加一個(gè)空格生成無序列表行首輸入1.或1)加一個(gè)空格生成有序列表。圖片處理在允許附件的資源中可以通過以下三種方式添加圖片使用工具欄的圖片按鈕從剪貼板直接粘貼圖片將圖片拖拽到編輯器上。圖片會(huì)被自動(dòng)上傳并保存為附件attachment。上傳完成后你可以用鼠標(biāo)在編輯器中直接拖拽調(diào)整圖片尺寸。需要說明的是在受限編輯器中例如部分工作包或評(píng)論場景圖片上傳能力可能不可用這由編輯器上下文決定。鍵盤快捷鍵CKEditor 本身提供了大量快捷鍵官方鍵盤支持文檔列出了全部內(nèi)容。在此基礎(chǔ)上OpenProject 額外增加了一條全局快捷鍵快捷鍵Windows / Linux快捷鍵Mac功能CTRL ENTERCMD ENTER保存更改對行內(nèi)可編輯字段保存并關(guān)閉該字段對帶完整 WYSIWYG 的頁面會(huì)議、wiki 頁面提交整個(gè)表單前端源碼也在編輯器包裝元素上注冊了自定義事件以支撐此類交互例如op:ckeditor:autosave、op:ckeditor:getData、op:ckeditor:setData等ckeditor-setup.service.ts方便宿主頁面以編程方式觸發(fā)自動(dòng)保存或讀寫編輯器內(nèi)容。宏指令MacrosOpenProject 在舊的 Textile 格式化時(shí)代就支持宏WYSIWYG 編輯器沿用了這一能力。需要注意編輯頁面時(shí)宏不會(huì)被展開而是顯示為占位符placeholder只有在渲染/預(yù)覽時(shí)才被解析執(zhí)行。從后端實(shí)現(xiàn)看宏的解析發(fā)生在文本格式化管線中位于 lib/open_project/text_formatting/filters/macro_filter.rb各宏分別實(shí)現(xiàn)于 lib/open_project/text_formatting/filters/macros/ 目錄下如toc.rb、embedded_table.rb、create_work_package_link.rb、include_wiki_page.rb、child_pages.rb等。前端則通過 editor-macros.service.ts 提供對應(yīng)的配置模態(tài)框。完整版 vs 受限版編輯器部分資源工作包、評(píng)論等使用受限編輯器并不展示全部宏能力例如宏或圖片上傳會(huì)被隱藏。前端 ckeditor-setup.service.ts 定義了宏的分級(jí)配置none/false不啟用任何宏自定義字段、只讀編輯器使用resource啟用目錄ToC、嵌入表格、工作包按鈕/快速信息 可用時(shí)的 wiki 鏈接wiki僅啟用 wiki 鏈接宏true啟用構(gòu)建中包含的全部宏string[]精確指定啟用的宏插件名。resolveMacros()ckeditor-setup.service.ts還會(huì)根據(jù)實(shí)例是否配置了 wiki 提供器configurationService.wikisAvailable自動(dòng)追加或過濾掉兩個(gè) wiki 頁面鏈接宏OpMacroWikiPageLinkAddExisting、OpMacroWikiPageLinkCreateNew。目錄Table of contents在適用的場景中TOC 宏會(huì)在頁面當(dāng)前位置輸出當(dāng)前頁面所有標(biāo)題的列表方便長文檔導(dǎo)航。其渲染邏輯位于 lib/open_project/text_formatting/filters/macros/toc.rb。工作包按鈕Work package button配置一個(gè)按鈕或鏈接指向當(dāng)前項(xiàng)目中創(chuàng)建工作包的頁面。你可以預(yù)選工作包類型從而引導(dǎo)用戶直達(dá)對應(yīng)的工作包創(chuàng)建表單。該宏的前端配置模態(tài)框見 macro-wp-button-modal/wp-button-macro.modal.ts配置邏輯由 editor-macros.service.ts 的configureWorkPackageButton()提供。包含 wiki 頁面Include wiki page在當(dāng)前項(xiàng)目或其他可見項(xiàng)目中引用一個(gè) wiki 頁面并將其內(nèi)容嵌入到當(dāng)前文檔。配置模態(tài)框?qū)?yīng) macro-wiki-include-page-modal/wiki-include-page-macro.modal.ts。嵌入工作包表格與甘特圖Embed work package table and Gantt chart這是最靈活的宏提供了與常規(guī)工作包表格同等的完整配置能力通過工具欄插入嵌入工作包表格宏后可在彈窗中配置表格視圖列、分組、過濾器及其他屬性渲染時(shí)頁面會(huì)動(dòng)態(tài)獲取工作包表格結(jié)果并針對每個(gè)用戶校驗(yàn)可見性/權(quán)限確保不同用戶看到各自有權(quán)限的數(shù)據(jù)典型用途在其他頁面嵌入視圖、構(gòu)建多結(jié)果報(bào)表、嵌入甘特圖視圖。后端對嵌入表格的解析見 lib/open_project/text_formatting/filters/macros/embedded_table.rb。鏈接到 OpenProject 資源延續(xù) Textile 時(shí)代的語法WYSIWYG 編輯器中可以使用相同的快捷語法鏈接到 OpenProject 內(nèi)的各類資源鏈接目標(biāo)用法示例Wiki 頁面[[Wiki page]]帶獨(dú)立鏈接名稱的 Wiki 頁面[[Wiki page\|The text of the link]]Sandbox 項(xiàng)目中的 Wiki 頁面[[Sandbox:Wiki page]]ID 為 12 的工作包#12帶主題與類型的工作包ID 12##12帶主題、類型與狀態(tài)的工作包ID 12###12按 ID 或名稱引用版本version#3、version:Release 1.0.0按 ID/名稱引用項(xiàng)目project#12、project:My project name按文件名引用附件attachment:filename.zip按 ID/名稱引用會(huì)議meeting#12、meeting:My meeting name按 ID/名稱引用文檔document#12、document:My document name按 ID 或登錄名引用用戶user#4、user:johndoe按 ID 引用論壇消息message#1218倉庫修訂版本 43r43按哈希引用提交commit:f30e13e4倉庫中的源文件source:some/file避免解析在這些標(biāo)記前加一個(gè)嘆號(hào)!例如!#12將不會(huì)鏈接到 ID 為 12 的工作包。[!NOTE] 所有這些宏必須以一個(gè)獨(dú)立的新詞形式書寫即前面至少有一個(gè)空格或位于段落/句子的開頭。包含在單詞內(nèi)部的宏如somethingmeeting#4不會(huì)被解析。從后端實(shí)現(xiàn)看這些鏈接處理由 lib/open_project/text_formatting/matchers/resource_links_matcher.rb 與 lib/open_project/text_formatting/matchers/link_handlers/ 目錄下的處理器如 work_packages.rb完成——每個(gè)處理器通過allowed_prefixes聲明自己能處理的資源前綴并負(fù)責(zé)把匹配到的鏈接解析為真實(shí)資源并渲染成帶正確鏈接與無障礙標(biāo)簽accessible link label的 HTML。工作包與用戶的自動(dòng)補(bǔ)全對于工作包和用戶輸入#或會(huì)分別彈出下拉菜單自動(dòng)補(bǔ)全當(dāng)前用戶可見的工作包或用戶。[!TIP] 鏈接工作包時(shí)想展示更多詳情可以輸入##或###后跟工作包 ID、主題、類型或關(guān)鍵字。嵌入工作包屬性與項(xiàng)目屬性O(shè)penProject 提供了一套強(qiáng)大的屬性嵌入宏允許在富文本中動(dòng)態(tài)引用工作包或項(xiàng)目的屬性值適合在 wiki、會(huì)議紀(jì)要、工作包描述等場景構(gòu)建活文檔。[!NOTE] 這些宏只在前端展開。對每個(gè)用戶都會(huì)校驗(yàn)相應(yīng)權(quán)限若用戶無權(quán)查看對應(yīng)資源宏會(huì)渲染為錯(cuò)誤提示。在 PDF 導(dǎo)出 中富文本屬性如工作包描述的嵌入在某些情況下受限簡單文本格式化或表格單元之外的嵌入是受支持的。按工作包 ID 嵌入值使用workPackageValue:ID:attribute語法按 工作包 ID 嵌入其屬性可用屬性見下方表格。示例嵌入 ID 為 1234 的工作包的主題workPackageValue:1234:subject按工作包主題嵌入值使用workPackageValue:Project name:attribute語法按工作包主題嵌入屬性。示例嵌入主題為 Project start 的工作包的負(fù)責(zé)人workPackageValue:Project start:assignee[!IMPORTANT] 按主題引用時(shí)只在當(dāng)前項(xiàng)目中查找具有該主題的工作包。需要跨項(xiàng)目引用時(shí)請使用 ID 精確定位。官方建議不要使用主題作為引用依據(jù)——因?yàn)橹黝}改變時(shí)引用不會(huì)自動(dòng)更新。相對嵌入當(dāng)前工作包的值使用workPackageValue:attribute語法嵌入當(dāng)前工作包的屬性編輯工作包描述或?qū)儆诠ぷ靼母晃谋咀远x字段時(shí)可以省略 ID編輯 wiki 頁面、會(huì)議描述等非工作包上下文時(shí)必須帶上工作包 ID。示例嵌入當(dāng)前工作包的負(fù)責(zé)人workPackageValue:assignee按項(xiàng)目 ID 嵌入值使用projectValue:ID:attribute語法按項(xiàng)目 ID 嵌入項(xiàng)目屬性。示例嵌入 ID 為 1234 的項(xiàng)目狀態(tài)projectValue:1234:status相對嵌入當(dāng)前項(xiàng)目的值使用projectValue:attribute語法嵌入當(dāng)前項(xiàng)目屬性。示例嵌入當(dāng)前項(xiàng)目的狀態(tài)projectValue:status控制多值屬性的顯示方式某些屬性包含多個(gè)值例如目標(biāo)版本Target versions或多選自定義字段。應(yīng)用中默認(rèn)每個(gè)值一行顯示PDF 導(dǎo)出時(shí)則以逗號(hào)分隔。在 CKEditor 中你可以通過布局參數(shù)layout控制其顯示方式workPackageValue:1234:targetVersions:multiline每個(gè)值單獨(dú)一行workPackageValue:1234:targetVersions:singleline所有值在一行內(nèi)以逗號(hào)分隔。布局參數(shù)同樣適用于自定義字段如workPackageValue:1234:My custom field:singleline、項(xiàng)目屬性projectValue:...以及相對引用workPackageValue:targetVersions:singleline。注意布局參數(shù)僅對可包含多個(gè)值的屬性生效對subject這類單值屬性無效。[!NOTE] 已廢棄的version屬性默認(rèn)按單行顯示工作包的目標(biāo)版本。后端解析器 attribute_macros.rb 對此有精確實(shí)現(xiàn)它定義了LAYOUTS %w[multiline singleline]作為保留關(guān)鍵字并在正則中捕獲可選的布局參數(shù)同時(shí)reinterpret_as_relative_embed()attribute_macros.rb會(huì)把裸屬性恰好命中保留關(guān)鍵字的相對形式如workPackageValue:multiline正確重解釋為相對嵌入而帶引號(hào)的屬性名則可以原樣引用同名的自定義字段。相對嵌入時(shí)relative_id()attribute_macros.rb會(huì)從渲染上下文中取出當(dāng)前工作包或項(xiàng)目 ID。嵌入屬性幫助文本Attribute help texts你還可以使用workPackageLabel或projectLabel嵌入屬性值以及對應(yīng)的幫助文本。例如workPackageLabel:1234:status會(huì)輸出 Status 的翻譯后的標(biāo)簽并在存在幫助文本時(shí)附帶顯示對應(yīng)的幫助文本。支持的屬性一覽以下兩張表列出了workPackageValue/workPackageLabel與projectValue/projectLabel宏支持的全部屬性名其中1234代表工作包 ID。[!NOTE] 若實(shí)例使用非英語語言只有在實(shí)例內(nèi)所有用戶語言一致例如都是德語時(shí)才能在文本編輯器中使用翻譯后的命令名如workPackageValue:1234:translated attribute且僅命令所指向的屬性被翻譯。官方建議避免使用翻譯后的屬性名——它們可能因未來版本修復(fù)或文案變更而失效。工作包可用屬性屬性用法示例%完成%CompleteworkPackageValue:8415:percentageDone負(fù)責(zé)人AccountableworkPackageValue:1234:responsible受理人AssigneeworkPackageValue:1234:assignee作者AuthorworkPackageValue:1234:author類別CategoryworkPackageValue:1234:category創(chuàng)建日期Creation dateworkPackageValue:1234:createdAt自定義字段Custom FieldsworkPackageValue:1234:Name of the work package custom field最后更新日期Date of last updateworkPackageValue:1234:updatedAt描述DescriptionworkPackageValue:1234:description預(yù)估工時(shí)Estimated timeworkPackageValue:1234:estimatedTime結(jié)束日期Finish dateworkPackageValue:1234:dueDate父工作包Parent work packageworkPackageValue:1234:parent優(yōu)先級(jí)PriorityworkPackageValue:1234:priority所屬項(xiàng)目ProjectworkPackageValue:1234:project項(xiàng)目階段Project phaseworkPackageValue:1234:projectPhase剩余工時(shí)Remaining hoursworkPackageValue:1234:remainingTime剩余工作量Remaining workworkPackageValue:8415:remainingTime已耗工時(shí)Spent timeworkPackageValue:1234:spentTime開始日期Start dateworkPackageValue:1234:startDate狀態(tài)StatusworkPackageValue:1234:status主題/標(biāo)題Subject / TitleworkPackageValue:1234:subject目標(biāo)版本Target versionsworkPackageValue:1234:targetVersions版本Version已廢棄workPackageValue:1234:version工作量WorkworkPackageValue:8415:estimatedTime工作包類型Work package typeworkPackageValue:1234:type[!NOTE]不支持富文本的遞歸嵌入。例如你不能用workPackageValue:description在自己的描述中嵌入自身。項(xiàng)目可用屬性以下示例均引用當(dāng)前文檔所在的項(xiàng)目也可以使用projectValue:Identifier of the project:attribute引用其他項(xiàng)目。屬性用法示例自定義字段Custom FieldsprojectValue:Name of the project custom field項(xiàng)目是否激活布爾projectValue:active描述DescriptionprojectValue:description項(xiàng)目標(biāo)識(shí)IdentifierprojectValue:identifier項(xiàng)目名稱NameprojectValue:name狀態(tài)StatusprojectValue:status狀態(tài)說明Status descriptionprojectValue:statusExplanation父項(xiàng)目Parent projectprojectValue:parent項(xiàng)目是否公開布爾projectValue:public小結(jié)從編輯器到渲染的完整鏈路綜合文檔與源碼OpenProject 富文本體系的核心鏈路可以概括為編輯端前端 ckeditor-setup.service.ts 按上下文創(chuàng)建full或constrained兩種 CKEditor 實(shí)例并按資源類型none/resource/wiki/true/string[]決定啟用的宏集合宏配置editor-macros.service.ts 通過模態(tài)框完成代碼塊、工作包按鈕、wiki 包含頁、子頁面等宏的參數(shù)配置保存與解析后端 lib/open_project/text_formatting/ 中的過濾器與匹配器接管內(nèi)容——macro_filter.rb 展開各類宏resource_links_matcher.rb 處理資源鏈接attribute_macros.rb 解析workPackageValue/projectValue/workPackageLabel/projectLabel屬性嵌入渲染端屬性宏在前端按用戶權(quán)限動(dòng)態(tài)加載并展示opce-macro-attribute-value/opce-macro-attribute-label自定義元素嵌入的工作包表格與甘特圖則在每次頁面加載時(shí)動(dòng)態(tài)獲取結(jié)果。掌握這套編輯器的格式化語法、宏指令與屬性嵌入能力你可以在 OpenProject 的 wiki、工作包描述、會(huì)議紀(jì)要等幾乎所有富文本場景中構(gòu)建出動(dòng)態(tài)、可復(fù)用、權(quán)限安全的內(nèi)容頁面?！久赓M(fèi)下載鏈接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ? Star us on GitHub項(xiàng)目地址: https://gitcode.com/GitHub_Trending/op/openproject創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考