萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

CKEditor 4 外掛開發入門:自定義按鈕插入帶參數超連結圖示完整步驟

需求

編輯器中選取文字 → 點擊工具列自定義按鈕 → 在文字後插入圖示連結,連結網址帶入選取文字作為查詢參數:/map_index.html?ad=選取文字。

目錄結構

ckeditor/
  plugins/
    addmap/
      plugin.js      # 外掛邏輯
      map.gif        # 工具列圖示 (16x16 或 24x24)

plugin.js 完整代碼

(function() {
    // 1. 定義按鈕點擊執行邏輯
    var cmd = {
        exec: function(editor) {
            var selectedText = '';
            var sel = editor.getSelection();

            // 相容 IE 與標準瀏覽器取得選取文字
            if (CKEDITOR.env.ie) {
                sel.unlock(true);
                selectedText = sel.getNative().createRange().text;
            } else {
                selectedText = sel.getNative().toString();
            }

            if (selectedText) {
                var html = selectedText +
                    '<a href="/map_index.html?ad=' + encodeURIComponent(selectedText) + '">' +
                    '<img border="0" height="24" src="/images/map_icon.gif" width="24" />' +
                    '</a>';
                editor.insertHtml(html);
            }
        }
    };

    // 2. 註冊外掛
    var pluginName = 'addmap';
    CKEDITOR.plugins.add(pluginName, {
        init: function(editor) {
            // 註冊命令
            editor.addCommand(pluginName, cmd);
            // 加入工具列按鈕
            editor.ui.addButton('addmap', {
                label: '插入地圖連結',
                command: pluginName,
                icon: this.path + 'map.gif' // 相對 plugin.js 路徑
            });
        }
    });
})();

config.js 啟用外掛

CKEDITOR.editorConfig = function(config) {
    config.language = 'zh-cn';
    config.font_names = '新細明體;微軟正黑體;Arial;Verdana;...';
    config.toolbar = [
        ['Source', '-', 'Preview'],
        ['Cut', 'Copy', 'Paste', 'PasteText', 'PasteFromWord', '-', 'Print', 'Link', 'Unlink', 'Anchor'],
        ['Undo', 'Redo', '-', 'Find', 'Replace', '-', 'SelectAll', 'RemoveFormat'],
        ['addmap']  // ← 將自定義按鈕加入工具列
    ];
    config.extraPlugins = 'addmap'; // ← 關鍵:載入外掛
};

關鍵 API 對照表

API用途
editor.getSelection()取得 Selection 物件
selection.getNative()取得原生 DOM Selection/Range
selection.unlock(true)IE 專用:解除選取鎖定
editor.insertHtml(html)在游標處插入 HTML 片段
editor.addCommand(name, cmdDef)註冊命令
editor.ui.addButton(name, btnDef)加入工具列按鈕
config.extraPlugins載入外部外掛 (逗號分隔多個)

進階擴充方向

  • 對話框模式:editor.addCommand(name, CKEDITOR.dialogCommand('dialogName')),彈出視窗輸入更多參數。
  • 狀態刷新:editor.on('selectionChange', ...) 依選取內容啟用/停用按鈕。
  • 多語系:plugin.js 同層建立 lang/zh-tw.js、lang/en.js。
  • 圖示最佳化:使用 SVG 或 Base64 Data URI 內嵌圖示,減少 HTTP 請求。

常見坑點

  • ❌ 忘記 config.extraPlugins → 外掛不載入。
  • ❌ icon 路徑錯誤 → 按鈕顯示空白,用 this.path 取得外掛目錄絕對路徑。
  • ❌ 未 encodeURIComponent 選取文字 → URL 參數注入風險。
  • ❌ IE 選取處理漏寫 unlock(true) → 取得空字串。

CKEditor 5 遷移提示

CKEditor 5 架構全面重寫 (ES6 模組、虛擬 DOM、紅黑樹模型),外掛開發方式完全不同。維舊專案續用 CKEditor 4;新專案建議直接採用 CKEditor 5 官方套件或自訂 Plugin 類別。

掌握「選取 → 指令 → 插入 HTML」核心流程,即可快速開發各類編輯器增強功能。

copyright © 萬盛學電腦網 all rights reserved