自定义TinyMCE按钮未在Publii编辑器显示的问题排查

问题 #

开发Publii自定义主题时，尝试为TinyMCE编辑器添加三个自定义按钮（Margin Note、Sidenote、Epigraph），控制台日志显示按钮已成功添加，但按钮未出现在编辑器UI中。

已执行操作 #

• 在主题根目录创建tinymce.script.js并编写按钮注册代码
• 更新config.json启用自定义TinyMCE配置：设置postEditorConfigOverride和postEditorCustomScript为true
• 修改tinymce.override.json定义包含自定义按钮的工具栏布局
• 验证脚本加载正常，控制台日志输出完整的初始化流程

核心问题与解决方案 #

核心原因 #

自定义脚本中直接调用tinymce.init()会与Publii预先初始化的编辑器实例冲突，导致按钮注册到了错误的实例上，无法在实际使用的编辑器UI中显示。

修复步骤 #

1. 修正tinymce.script.js代码
   移除独立的tinymce.init()调用，改用Publii提供的publiiEditorCallbacks钩子注册按钮，确保挂载到正确的编辑器实例：

   (function () {
       console.log("Custom TinyMCE script loaded.");
   
       window.publiiEditorCallbacks = window.publiiEditorCallbacks || [];
       window.publiiEditorCallbacks.push(function(editor) {
           console.log("Adding custom TinyMCE buttons to Publii editor.");
   
           // Margin Note Button
           editor.ui.registry.addButton('margin_note', {
               text: 'Margin Note',
               icon: 'comment',
               tooltip: 'Insert a margin note',
               onAction: function () {
                   let note = prompt("Enter margin note text:");
                   if (note) {
                       editor.insertContent(`<span class="marginnote">${note}</span>`);
                   }
               }
           });
   
           // Sidenote Button（优化：动态生成唯一ID避免重复）
           editor.ui.registry.addButton('sidenote', {
               text: 'Sidenote',
               icon: 'comment',
               tooltip: 'Insert a sidenote with automatic numbering',
               onAction: function () {
                   let note = prompt("Enter sidenote text:");
                   if (note) {
                       let sidenoteId = 'sn-' + Date.now();
                       editor.insertContent(`<label for="${sidenoteId}" class="margin-toggle sidenote-number"></label><input type="checkbox" id="${sidenoteId}" class="margin-toggle"/><span class="sidenote">${note}</span>`);
                   }
               }
           });
   
           // Epigraph Button
           editor.ui.registry.addButton('epigraph', {
               text: 'Epigraph',
               icon: 'quote',
               tooltip: 'Format as an epigraph',
               onAction: function () {
                   let selectedText = editor.selection.getContent();
                   if (selectedText) {
                       editor.insertContent(`<blockquote class="epigraph">${selectedText}</blockquote>`);
                   } else {
                       alert("Please select text for the epigraph.");
                   }
               }
           });
   
           console.log("Buttons added: Margin Note, Sidenote, Epigraph.");
       });
   })();
   

2. 验证配置文件一致性

   • 确保tinymce.override.json中的toolbar字段包含所有自定义按钮的key（margin_note、sidenote、epigraph），拼写完全一致：

     {
         "toolbar": "undo redo | bold italic | margin_note sidenote epigraph",
         "plugins": "lists link image table code"
     }
     

   • 确认config.json的extensions配置正确：

     "extensions": {
         "postEditorConfigOverride": true,
         "postEditorCustomScript": true
     }
     

3. 清除缓存并重启
   进入Publii设置→高级→清除缓存，然后完全关闭并重启Publii应用，确保新配置生效。

4. 排查额外问题

   • 如果按钮仍不显示，可暂时移除icon属性，只保留text属性，排除图标加载失败的问题
   • 检查浏览器控制台是否有未捕获的错误，比如DOM操作异常或脚本冲突

内容的提问来源于stack exchange，提问作者Anurag