ckeditor 4 開發指南 · WEB 摘要

## 一、安裝 #### 安裝CKEditor 是很容易的。選擇合適的過程（新安裝或升級），按下面描述的步驟安裝。 #### 1、新安裝 #### #### 第一次安裝CKEditor，按如下方式進行： #### 1) 從CKEditor 網站：http://ckeditor.com/download下載最新版本的CKEditor 。 #### #### 2) 將下載的文檔解壓到你的website根目錄下的ckeditor 目錄中。你可以將文檔放在你的website的任意路徑中。ckeditor 目錄是缺省目錄。 #### #### 2、升級 #### 要升級現有的CKEditor 安裝，按如下方式進行： #### 1) 將你的舊編輯文件夾更名為備份文件夾，如ckeditor_old。 #### 2) 從CKEditor 網站：http://ckeditor.com/download下載最新版本的CKEditor 。 #### #### 3) 將下載的文檔解壓到原編輯器的目錄，如ckeditor。 #### #### 4) 將你已做過更改的配置文件從備份目錄復制到其新目錄的相應位置。這些配置文件 #### 可能包括（但不限于）下列文件： #### #### oconfig.js , #### #### contents.css , #### #### styles.js #### #### 3、驗證安裝 #### CKEditor 帶有樣例頁面，可以用于驗證安裝是否正常。為了查看編輯器是否工作，看一下樣例目錄。 #### 要檢查安裝，在你的站點中調用下面的頁面： #### http://`<your site>`/`<CKEditor installation path>`/samples/index.html #### 例如：http://www.example.com/ckeditor/samples/index.html ## 二、集成 1、加載CKEditor CKEditor 是JavaScript應用程序。要加載它，需要在頁面中包含一個簡單的文件引用。如果已在站點根目錄下的ckeditor目錄中安裝了CKEditor ，你需要將下面的代碼片段插入到頁面的<head>部分： ``` <head> ... <script src="/ckeditor/ckeditor.js"></script> </head> ``` 當上述文件加載后，就可以使用CKEditor JavaScript API。當將CKEditor加入到web頁面時，使用原始的文件名（ckeditor.js）。如果想使用不同的文件名，或者甚至想將CKEditor合并到另外一個JavaScript文件中，請先參考開發人員指南中的 Specifying the Editor Path部分。生成編輯器現在已經可以在頁面中使用 CKEditor JavaScript API了，可以使用它生成編輯器。為此，有兩種可用的選項： 1、框架式編輯（Framed Editing）：最常用的使用方式，通常的表現形式是在頁面中指定位置放置工具欄和編輯區。內聯式編輯（Inline Editing）：用于看起來像最終的頁面中。通過HTML5的contenteditable（內容可編輯的）屬性，可以將編輯直接應用于HTML元素上。點擊你偏愛的選項獲得更多信息。 2、框架式編輯（Framed Editing）框架式編輯是使用 CKEditor最常用的方式。它通常的表現形式是在頁面中指定位置放置工具欄和編輯區。在加載 CKEditor的腳本后，就可以準備生成編輯器了。 ### 生成框架式編輯式在框架式編輯時，CKEditor 的工作就像頁面中的文本域元素。編輯器提供了用戶界面，可以容易在編寫、格式化，并可與富文本一起處理，但是可以用`<textarea>`元素完成同樣的事情（盡管不是那么容易），需要用戶在其中輸入HTML代碼。實際上，CKEditor 使用文本域將其數據傳給服務器。對于終端用來來說，文本域是不可見的。為了生成編輯器的實例，必須首先將`<textarea>`元素加入到HTML頁面的源代碼中。 ``` <textarea name="editor1"><p>Initial value.</p></textarea> ``` 注意如果你想將數據加載到編輯器中，如從數據中，你需要將數據置入`<textarea>`元素中，就像上面例子中HTML編碼的<p>元素一樣。在此例中，文本域被命名為editor1。在后面當收到提交的數據后，可以將此名字用于服務器端的代碼中。插入文本域后，就可以使用CKEditor JavaScript API將HTML元素替換為編輯器的實例。為此，需要調用簡單的CKEDITOR.replace方法： ``` <script> CKEDITOR.replace( 'editor1' ); </script> ``` 此腳本塊必須被包含在`<textarea>`標記后的頁面源代碼的任意位置。你也可以在`<head>`部分調用replace函數，但此時需要監聽window.onload事件： ``` <script> window.onload = function() { CKEDITOR.replace( 'editor1' ); }; </script> ``` 保存編輯器的數據如上所述，編輯器的工作方式類似于`<textarea>`域。這意味著當提交包含編輯器實例的表單時，數據將很簡單地提交，使用`<textarea>`元素名作為鍵來檢查它。例如，接著上面的例子，我們可以生成下面的PHP代碼： ``` <?php $editor_data = $_POST[ 'editor1' ]; ?> ``` 客戶端數據處理一些應用程序（如基于Ajax的）需要在客戶端處理所有的數據，用其特定的方法將數據發給服務器。如果是這樣，使用CKEditor JavaScript API就足以很容易地檢索編輯器實例的數據。為此，你可以使用getData方法： ``` <script> var editor_data = CKEDITOR.instances.editor1.getData(); </script> ``` 完整的樣例要插入一個CKEditor實例，可以使用下面的樣例來生成一個頁面，它包含一個用CKEditor替換過的表單。 ``` <html> <head> <title>CKEditor Sample</title> <script src="/ckeditor/ckeditor.js"></script> </head> <body> <form method="post"> <p> My Editor:<br> <textarea name="editor1"><p>Initial value.</p></textarea> <script> CKEDITOR.replace( 'editor1' ); </script> </p> <p> <input type="submit"> </p> </form> </body> </html> ``` 3、內聯式編輯（Inline Editing）內聯式編輯是一種新技術，使得可以編輯看起來像最終樣子的頁面。它是一種完全的“所見即所得”（WYSIWYG ）體驗，因為不僅是編輯的內容看起來像最終樣子，而且內容所在的頁面和上下文也是這樣。啟用內聯式編輯通過HTML5的contenteditable（內容可編輯的）屬性，內聯式編輯可以直接在HTML元素上啟用。例如，假設你想使用一個`<div>`元素可編輯。可以這樣做： ``` <div id="editable" contenteditable="true"> <h1>Inline Editing in Action!</h1> <p>The div element that holds this text is now editable. </div> ``` 也可以通過代碼來啟用編輯，通過調用CKEDITOR.inline： ``` <div id="editable" contenteditable="true"> <h1>Inline Editing in Action!</h1> <p>The div element that holds this text is now editable.</p> </div> <script> // Turn off automatic editor creation first. CKEDITOR.disableAutoInline = true; CKEDITOR.inline( 'editable' ); </script> ``` 當在上面的`<div>`內容中點擊時，CKEditor的工具欄就是出現。檢索編輯器的數據跟框架式編輯不同，當使用內聯式編輯時，用CKEditor編輯的數據沒有放在`<textarea>`中，而是直接存在于頁面的DOM中。因此，應用程序就要完成檢查數據和存儲所需的操作。要檢查編輯器的數據，簡單地調用編輯器實例的CKEDITOR.editor.getData方法。對于上面的例子，如下： ``` <script> var data = CKEDITOR.instances.editable.getData(); // Your code to save "data", usually though Ajax. </script> ``` 注意為了檢索編輯器實例，最初的`<div>` id已傳給了CKEDITOR.instances對象。 ## 三、配置 #### 1、設置CKEditor 的配置 #### CKEditor 具有豐富的一組配置選項，可以定制其外觀、功能和行為。主配置文件名字為config.js。此文件可以在CKEditor 安裝文件夾的根目錄中找到。 #### 可用的配置選項 #### 在API文檔中可以找到所有可用的配置選項。參考CKEDITOR.config對象的定義。 #### 在頁面中（In-Page）定義配置 #### 設置 CKEditor的最好方法是當生成了編輯器實例時，在頁面中設置。此方法可以使你避免修改 CKEditor安裝文件夾中最初發布的文件，使升級任務更容易。 #### 在頁面中可將設置傳給任意編輯器實例生成函數，即CKEDITOR.replace 和CKEDITOR.appendTo。例如： #### ``` #### #### CKEDITOR.replace( 'editor1', { #### toolbar : 'Basic', #### uiColor : '#9AB8F3' #### }); #### ``` #### 注意通過一個字面對象定義（以“｛”符號開始，以“｝”符號結束）來傳遞配置選項。因此，每個選項的正確語法是（"配置的名字"）:（"配置的值"）。一定不要在冒號字符（:）處使用“等于”字符（=）。 #### 使用config.js文件 #### 也可以通過使用config.js文件來配置CKEditor的設置。此文件缺省情況幾乎為空。要改變CKEditor的配置，將你想要修改的設置增加到config.js文件中。例如： #### ``` #### #### CKEDITOR.editorConfig = function( config ) { #### config.language = 'fr'; #### config.uiColor = '#AADC6E'; #### }; #### ``` #### 為了應用配置設置，必須總是要定義CKEDITOR.editorConfig函數。config.js文件將在頁面范圍中被執行，故你還可以引用在頁面（In-Page）或者甚至是其它JavaScript文件中定義的變量。 #### 使用定制的配置文件 #### 使用定制的配置文件是另一種推薦的設置CKEditor配置的方法。不使用缺省的config.js文件，你可以將此文件復制到站點的任何地方，并簡單地引導編輯器加載它。此方法的優點是采用此方法可以避免改變原始的文件，從而使以后升級CKEditor更容易，只是簡單地覆蓋所有的文件。 #### 假設你將config.js文件復制到你的站點根目錄下一個叫custom的文件夾中。你還將此文件更名為ckeditor_config.js。此時，要使用定義在文件中的定制設置，只需在生成編輯器實例時，設置customConfig配置選項即可。例如： #### #### ``` #### CKEDITOR.replace( 'editor1', { #### customConfig : '/custom/ckeditor_config.js' #### }); #### ``` #### 定制的配置文件必須看起來像缺省的config.js文件。 #### 配置的加載順序 #### 不要求你僅使用一種上述配置選項。可以混用上述方法，并且可以正確地加載配置。下面的列表表示在生成編輯器實例時所使用的配置加載順序： #### #### 生成一個編輯器的實例。此時，其所有配置項設置為缺少值。 #### 如果在頁面中（in-page）中有配置設置，該文件被加載，否則加載缺省的config.js文件。在定制配置文件中的所有設置覆蓋當前實例的配置。 #### 如果在第二步加載的設置中還定義了新的customConfig值，就加載另一個配置文件，且其設置覆蓋實例的當前設置。對所有文件遞歸，直到沒有再定義customConfig。 #### 最終，在頁面中(in-page)中定義的設置覆蓋實例的當前設置（除了customConfig，它已在第一步中使用過了）。 #### 避免加載外部的設置文件 #### 也可能完全避免加載外部的配置文件，以減少加載的文件數。為此，你需要將 #### CKEDITOR.config.customConfig設置為空字符串。例如： #### #### CKEDITOR.replace( 'editor1', { customConfig : ' ' }); #### 如果你在config.js文件中沒有配置，也沒有定制的配置文件，則一定推薦此設置。 #### 2、工具欄的定制 #### 雖然CKEditor是一個功能齊全的“所見即所得”編輯器，但是并不是其所有選項在所有情況下都需要。因此，工具欄定制是最常用需求之一。 #### 有兩種方法配置工具欄來匹配需求： #### #### 工具欄組配置 #### “逐項”配置 #### 工具欄組配置 #### CKEditor 4為組織工具欄引入了新概念，它基于“分組”，而不是傳統的“逐項定位”方式。 #### 配置分組是由toolbarGroups設置定義的。下面是CKEditor標準發布所使用的配置： #### ``` #### #### config.toolbarGroups = [ #### { name: 'clipboard', groups: [ 'clipboard', 'undo' ] }, #### { name: 'editing', groups: [ 'find', 'selection', 'spellchecker' ] }, #### { name: 'links' }, #### { name: 'insert' }, #### { name: 'forms' }, #### { name: 'tools' }, #### { name: 'document', groups: [ 'mode', 'document', 'doctools' ] }, #### { name: 'others' }, #### '/', #### { name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ] }, #### { name: 'paragraph', groups: [ 'list', 'indent', 'blocks', 'align' ] }, #### { name: 'styles' }, #### { name: 'colors' }, #### { name: 'about' } #### ]; #### ``` #### 它是一個對象的列表（數組），每一項有一個“name”（如"clipboard"或"links"）和一個可選的“子組”列表。 #### #### 改變組的順序 #### 可以通過改變上述配置，可以容易地定制組的順序和位置。 #### 通過加入'/'，正如在上面看到的，可以在工具欄中強制斷行（row-break）。 #### 注意：在上面的配置中，有沒有使用的組。這是因為“設計”的原因（參見“組配置的好處”）。 #### #### 組配置的好處 #### 與“逐項”配置相比，配置工具欄分組的最重要好處是：自動化。 #### 現在可以讓插件開發人員決定其插件應該將按鈕加到工具欄的哪個組中。例如，“圖像”插件，可將其按鈕包括到“插入”組中，而撤銷和重做按鈕加到“撤銷”子組中。 #### 雖然不是強制性的，但推薦要配置所有的組和子組（包括沒有使用的），因為在將來的任何時候，當安裝了新的插件時，其按鈕將會自動出現在工具欄中，而不用再配置。 #### #### 組配置的缺點 #### 分組配置的最明顯問題是不可能精確控制每項在工具欄中的放置位置。它是由插件自身來決定的。 #### #### “逐項”配置 #### 除了分組配置，還可以通過確定精確的位置來控制工具欄中的每一個單獨的元素。這是通過配置“工具欄定義”來完成的。 #### 工具欄定義是一個JavaScript數組，它含有在編輯器中可以使用的在所有工具欄行中顯示的元素。下面是一個例子： #### ``` #### #### config.toolbar = [ #### { name: 'document', items: [ 'Source', '-', 'NewPage', 'Preview', '-', 'Templates' ] }, #### { name: 'clipboard', items: [ 'Cut', 'Copy', 'Paste', 'PasteText', 'PasteFromWord', '-', 'Undo', 'Redo' ] }, #### '/', #### { name: 'basicstyles', items: [ 'Bold', 'Italic' ] } #### ]; #### ``` #### 這里每個工具欄組都給定了一個名字，并定義了其中項目的精確清單。也可以用簡單的語法實現上面的（參見后面的“訪問問題”）： #### ``` #### config.toolbar = [ #### [ 'Source', '-', 'NewPage', 'Preview', '-', 'Templates' ], #### [ 'Cut', 'Copy', 'Paste', 'PasteText', 'PasteFromWord', '-', 'Undo', 'Redo' ], #### '/', #### [ 'Bold', 'Italic' ] #### ]; #### ``` #### 通過將'-'(短線)加到項目列表中，將項目分隔符包括其中，如上面看到的。 #### 將'/'加到組之間，可以在工具欄中強制斷行。它們可以用于在其放置的位置強制斷行，使得下一個工具欄組處于新的一行。 #### #### “逐項”配置的好處 #### 這種配置最明顯的好處是每個單獨的項目在工具欄中的位置都可以控制。 #### #### 逐項”配置的缺點 #### 最大的問題是當安裝新的插件時沒有了自動化。這意味著，如果有任何新的插件加入到你的編輯器中，你將不得不手動改變你的配置，將插件按鈕包含于希望的位置。 #### #### 可訪問性問題 #### 用于每個工具欄組的名字將被幫助技術所使用，如屏幕閱讀器（screen readers）。該名字將被CKEditor 用于在編輯器語言文件（工具欄組條目）中查找每個工具欄組的“可讀”名字。 #### 屏幕閱讀器將通過使用其可讀名字（如果可用）或其已定義的名字屬性顯示每個工具欄組。 #### #### 3、樣式 #### 樣式組合（Stryles Combo）插件將一個組合加入到CKEditor 的工具欄中，包含一個樣式列表。此列表使很容易地將定制的樣式和語義值應用于在編輯器中生成的內容上。 #### 可以很容易地定制組合下拉列表中可用的條目，以滿足你的需要。 #### #### 定義樣式 #### 樣式定義是一個JavaScript數組，通過調用CKEDITOR.stylesSet.add函數注冊。必須給樣式定義賦以唯一的名字，這樣后面就可以配置每個編輯器實例來加載它。這種方法可以使一個樣式定義被頁面中多個CKEditor實例共享。 #### 下面的代碼展示了如何注冊一個例子樣式定義。 #### #### ``` #### #### CKEDITOR.stylesSet.add( 'my_styles', [ #### // Block-level styles #### { name: 'Blue Title', element: 'h2', styles: { 'color': 'Blue' } }, #### { name: 'Red Title' , element: 'h3', styles: { 'color': 'Red' } }, #### // Inline styles #### { name: 'CSS Style', element: 'span', attributes: { 'class': 'my_style' } }, #### { name: 'Marker: Yellow', element: 'span', styles: { 'background-color': 'Yellow' } } #### ]); #### ``` #### 如上面所示的樣式定義注冊可以內置于頁面源代碼中，或者存在于外部文件中，只要需要時，“按需”加載。（見下面）。 #### 當準備好定義后，你必須通過使用stylesSet設置使編輯器應用新注冊的樣式。這可以在config.js文件中設置，例如： #### #### config.stylesSet = 'my_styles'; #### 使用外部樣式定義文件 #### 可以將樣式定義的注冊調用包含在一個外部JavaScript文件中。缺省情況，CKEditor從其安裝文件夾中的styles.js文件中加載樣式定義。 #### 你的樣式定義文件可以保存在站點的任意地方（或互聯網的某個地方）。但，你必須知道訪問它所需的URL。例如，你可以將此文件保存在站點的根目錄中，然后按/styles.js調用它，或者放在其它任意地方，并使用其完整的URL引用它，如http://www.example.com/styles.js。 #### 此時，改變stylesSet設置，使編輯器指向此文件： #### #### config.stylesSet = 'my_styles:/styles.js'; #### //或者 #### config.stylesSet = 'my_styles:http://www.example.com/styles.js'; #### 樣式定義設置的語法總是：樣式定義名稱:文件的URL。 #### 注意，必須使用在此文件中注冊樣式定義時使用過的唯一的名稱。 #### #### 樣式規則 #### 在樣式定義中的輸入項稱為“樣式規則”。每條規則定義了單個樣式的顯示名字和元素、屬性以及所使用的CSS樣式。下面是它的一般表現形式： #### #### ``` #### { #### name: 'Name displayed in the Styles drop-down list', #### element: 'HTML element name (for example "span")', #### styles: { #### 'css-style1': 'desired value', #### 'css-style2': 'desired value', #### ... #### } #### attributes: { #### 'attribute-name1': 'desired value', #### 'attribute-name2': 'desired value', #### ... #### } #### } #### ``` #### 名稱和元素值是必須的，而其它的值是可選的。 #### 樣式的類型 #### 有三種樣式類型，每一種都與在樣式規則中使用的元素相關: #### #### 塊級樣式（Block-level styles）-作為整體應用于文本塊（段落），不限于文本選擇。應用于下面的元素：address, div, h1, h2, h3, h4, h5, h6, p, 和 pre。 #### 對象樣式（Object styles）- 用于特殊的可選擇的對象（不是文本的），不論何時只要你的瀏覽器支持這樣的選擇。應用于下面的元素：a, embed, hr, img, li, object, ol, table, td, tr 和 ul。 #### 內聯樣式（Inline styles ）- 應用于文本選擇，其樣式規則所使用的元素沒有在其它樣式類型中定義。 #### 樣式單解析器插件（Stylesheet Parser Plugin） #### 存在另一種簡化的方法，用于定制在CKEditor中生成文檔的樣式，用外部CSS樣式單文件中添加的樣式定義來填充下拉清單。樣式單解析器插件允許使用現有的CSS樣式，而不必按上面給出的格式專門為CKEditor定義樣式。 #### 安裝完樣式單解析器后，需要使用 contentsCss配置設置，提供含有樣式定義的CSS文件的位置： #### #### config.contentsCss = 'sample_CSS_file.css'; #### 最后，如果你想跳過加載CKEditor 缺省使用的樣式，可以將stylesSet設置為空值： #### config.stylesSet = []; #### 這種解決方法使得可以配置編輯器使用現有的CSS樣式單規則，而不需要為CKEditor生成單獨的樣式定義。另一方面，前面使用的方法提供了對用戶可以使用樣式的更多控制，因此，兩種方法可以按需要互換使用。 #### 選擇CSS選擇器 #### 可以細調此插件，以使只考慮與stylesheetParser_validSelectors配置值相匹配的CSS選擇器。默認的正則表達式接受 element.class形式的所有CSS規則，但可以修改它，以引用有限的元素集，如下面的例子： #### #### // Only add rules for `<p> `and `<span>` elements.（僅為`<p>`和`<span>`元素增加規則 #### config.stylesheetParser_validSelectors = /\^(p|span)\.\w+/; #### 限制CSS選擇器 #### 通過設置stylesheetParser_skipSelectors的配置值，也可以進行定制。那么，該插件將會角力忽略與正則表達式相匹配的CSS規則，不會在下拉列表中顯示它們，也不會使用它們輸出文檔內容。默認值不包括為<body>的所有元素和為非具體元素定義的類，但可以修改它，以忽略更廣泛的元素集，如下例： #### #### // Ignore rules for `<body>` and `<caption>` elements, classes starting with "high", and any class defined for no specific element.（忽略`<body>`和`<caption>`元素、以“high”開頭的類，以及為非具體元素定義的類的規則） #### config.stylesheetParser_skipSelectors = /(^body\.|^caption\.|\.high|^\.)/i; #### #### 4、高級內容過濾器 #### 介紹 #### 注意：高級內容過濾器是在CKEditor 4.1中引入的。 #### 什么是高級內容過濾器（ACF）？ #### ACF是自CKEditor 4.1可用的高度可配置的CKEditor核心特色功能。它限制和適配輸入的數據（在源代碼模式中或由editor.setData方法添加的HTML代碼，粘貼的HTML代碼，等等），因此它可以以更可行的方式配置編輯器的配置。它也可以使生成配置不允許的HTML代碼的功能無效。 #### 高級內容過濾器有兩種工作模式： #### 1、自動模式-過慮器由編輯器功能（如插件，按鈕和命令）進行配置，這些功能是由配 #### 置選項，如CKEDITOR.config.plugins、 CKEDITOR.config.extraPlugins和 CKEDITOR.config.toolbar，來啟用的。 #### 2、定制模式-由CKEDITOR.config.allowedContent選項來配置過濾器，并且只有與此設置匹配的功能才被激活。 #### 在兩種模式中，可以通過使用CKEDITOR.config.extraAllowedContent設置來擴展過濾器的配置。 #### 如果想使高級內容過濾器不起作用，將CKEDITOR.config.allowedContent設置為"true"。所有可用的編輯器功能將被激活，并且將不會過濾輸入的數據。 #### #### 自動模式 #### 當沒有提供CKEDITOR.config.allowedContent設置時，高級內容過濾器工作于自動模式。在編輯器初始化時，編輯功能將其規則添加到過濾器。因此，只允許使用當前加載的功能可以編輯的內容，其余所有內容都被過濾掉。 #### 下面的例子或許可以較容易地理解ACF的自動模式。 #### #### 1. 從完全或標準CKEditor包中打開datafiltering.html例子（基本包提供的功能集太有限了）。 #### 2. 勾選editor 1。它使用默認的配置，所以所有包中可用的按鈕、按鍵或樣式都是有效 #### 的，并且編輯器的內容也與最初加載的內容一樣（除了標準包中的很小細節--因為標準包不包括 Justify（調整版面）插件，頁腳沒有向右對齊）。 #### 3. 現在勾選editor 4。你可以看到很多插件和按鈕被CKEDITOR.config.removePlugins和 CKEDITOR.config.removeButtons移除了；CKEDITOR.config.format_tags列表也被縮減了。配置的改變自動反映在了編輯器的內容中了--Image工具欄按鈕沒有了，故在內容中也就不存在圖像了；Table插件沒有了，故添加在原始內容中的表格也被移除了。你可以在源代碼模式中看一下編輯器是如何清除粘貼的內容或HTML代碼。 #### 如果想將編輯器配置為工作于自動模式，但需要附加的HTML標記、屬性、樣式或類生效，可以使用CKEDITOR.config.extraAllowedContent配置選項。 #### #### 定制模式 #### 當定義了CKEDITOR.config.allowedContent設置后，高級內容過濾器就工作于定制模式。此配置選項告訴過濾器允許哪些HTML元素、屬性、樣式和類。基于默認的規則（稱為允許內容規則--Allowed Content Rules），編輯器過濾輸入的數據，決定哪些功能生效。 #### 允許內容規則（Allowed Content Rules）可以被設置為兩種不同的格式：緊湊的字符串格式（string format）和更強大的對象格式（object format）。關于允許內容規則，請閱讀允許內容規則。 #### 下面的例子可以使較容易地理解ACF的定制模式。 #### 1. 從完全或標準CKEditor包中打開datafiltering.html例子（基本包提供的功能集太有限了）。 #### 2. 勾選editor 1。它使用默認的配置，所以所有包中可用的按鈕、按鍵或樣式都是有效的，并且編輯器的內容也與最初加載的內容一樣（除了標準包中的很小細節--因為標準包不包括 Justify（調整版面）插件，頁腳沒有向右對齊）。 #### 3. 勾選editor 2。CKEDITOR.config.allowedContent選項定義了允許內容規則使用字符串格式。注意到，因為這些規則不允許's'元素，刪去（Strike Through）按鈕從工具欄中被刪除了，并且文本中的刪去格式化也被刪除了。對于帶有水平（Horizontal Line）、下標（Subscript）和上標（Superscript）功能的例子同樣如此。 #### 再看一下Styles和Format下拉列表，僅含有允許內容規則中定義的項目。而且，在某些對話框中可用的選項也受到了限制。例如，圖象對話窗口僅含有URL、替代文字（Alternative Text）、寬度和高度值，因為僅有這些屬性在CKEDITOR.config.allowedContent中定義了。 #### 4. 另外，editor 3 被配置為使用對象格式定義的不同規則集。 #### #### 內容轉換（Content Transformations） #### 高級內容過濾器不僅可以刪除不允許的HTML元素、它們的類、樣式和屬性，而且可以試著通過將元素從一種形式轉換為另一種更喜歡的形式，從而統一輸入數據。 #### 考慮加粗（Bold）功能。在HTML代碼中，它可以用`<strong>`、 `<b>`，或者甚至 `<span style="font-weight:700|800|900|bold">` 元素來表示。假設 CKEDITOR.config.allowedContent設置僅含有對`<b>`的規則。這是否意味著當解析`<string>`或`<span>`元素時，會刪除它們？ #### 不會。編輯器會將它們都轉換為`<b>`元素。結果是編輯器將只含有`<b>`元素，并且會保留粘貼內容的可視化形式。如果保留默認的CKEDITOR.config.allowedContent值（在自動模式中），也同樣如此--所有加粗的功能形式將被統一成偏愛的`<strong>`形式。 #### 假設將'img[!src,alt,width,height]'設置（`<img>`標記帶有必需的src和三個可選的屬性）添加到允許內容規則中。圖像大小應該用屬性來設置，因此，作為例子，用樣式設置大小的粘貼圖像將被轉換成具有屬性的圖像（注意，不是所有情況都可能--只有基于像素的大小可以被轉換）。 #### 內容轉換功能完全是自動的，不需要配置它。需要做的唯一的事情是設置CKEDITOR.config.allowedContent選項，或使用默認的值（自動模式） #### 目前，我們只是為幾個編輯器功能定義了內容轉換，但是在將來發布的版本中數量會增加。 #### #### 允許內容規則（Allowed Content Rules） #### 注意：高級內容過濾器是在CKEditor 4.1中引入的。 #### #### 簡介 #### 允許內容規則定義了允許哪些HTML元素、屬性、樣式和類。當配置CKEditor時，你將對設置CKEDITOR.config.allowedContent選項最感興趣。插件開發人員也需要設置CKEDITOR.config.allowedContent屬性，告訴編輯器在自動模式中一項功能所允許哪些內容。 #### 允許內容規則通常包括四個主要部分： #### #### 允許的元素， #### 這些元素可以有的屬性， #### 這些元素可以有的樣式， #### 這些元素可以有的類。 #### 注意：替代書寫“屬性(attributes)、樣式(styles)和類(classes)”，使用“屬性”（properties）作為簡便的描述方法。 #### 對于一個元素可以存在多項規則，一個元素可以被包含在多個元素列表中。例如，每一個規則可以允許另一元素屬性集。 #### 規則是一個一個地應用的。初始時，被過濾的元素是無效的，其所有屬性都被拒絕。應用于該元素的第一條規則校驗它（它不會被刪除），并且該規則可能接受某些元素的屬性。另一條規則可能使編輯器接受更多的元素屬性。因此： #### #### 如果一個元素不存在規則，則刪除它。 #### 可能接受一個元素，但拒絕其所有的屬性，然后就被刪除。 #### 一旦被驗證，一個元素和它的屬性不能被另一規則使之失效。 #### 字符串格式（String Format） #### 字符串格式是允許內容規則的緊湊表示法，但它沒有提供對象格式中可用的所有功能。但是，在大多數情況下，應該夠用了。 #### 規則格式： #### #### #### elements [attributes]{styles}(classes) #### 正則表達式模板： #### ``` #### < elements >< styles, attributes, and classes >< separator > #### /^([a-z0-9*\s]+)((?:\s*\{[!\w\-,\s\*]+\}\s*|\s*\[[!\w\-,\s\*]+\]\s*|\s*$[!\w\-,\s\*]+$\s*){0,3})(?:;\s*|$)/i, #### ``` #### 其中: #### elements – 一列由空格分隔的元素名或一個星號（*）字符， #### attributes –一列由逗號分隔的屬性名或一個星號（*）字符， #### styles –一列由逗號分隔的樣式名或一個星號（*）字符， #### classes –一列由逗號分隔的類或一個星號（*）字符， #### 特殊字符： #### #### 用于元素列表中的星號意思是：“該規則對所有元素接受后面的屬性，但不是這些元素本身；必須有另一條規則顯式地接受這些元素”。 #### 屬性列表中的星號意思是：“接受所有屬性”。 #### 用于屬性列表中條目名前的感嘆號（!）（如：[!href]）意思是：“此屬性是必需的。 #### 如果一個元素不具有此屬性，此規則不應應用于該元素（故此元素將不會由它得到驗證）”。 #### #### 例子： #### #### // 一條規則接受`<p>`和`<h1>`元素，但沒有任何屬性。 #### p h1 #### //一條規則接受具有可選的"left"和 "right"類的`<p>`和`<h1>`元素 //注意：兩個元素都可能含有這些類，而不僅僅是`<h1> ` #### p h1(left,right) #### //一條規則接受具有其所有屬性的`<p>`和`<h1>`元素 #### p h1[*] #### //一條規則接受`<a>`，只有當它含有"href"屬性時。 #### a[!href] #### //一條規則接受`<img>`，它具有必需的"src"屬性和一個可選的"alt"屬性，加上可選的"width"和"height"樣式 #### img[alt,!src]{width,height} #### //與上面相同，因為屬性的順序和其清單是不相關的，并且忽略空格 #### img { height, width } [ !src, alt ] #### 允許內容規則集可以含有由分號（;）分隔的多條規則。如： #### // 這些規則允許： #### // 具有可選的"text-align"樣式的`<p和>``<h1>`元素 //具有必需的"href"屬性的<a> // `<strong>` 和 `<em>` 元素, #### //具有可選的"tip"類的`<p>`（故`<p>`元素可以同時具有"text-align"樣式和"tip"類） #### p h1{text-align}; a[!href]; strong em; p(tip) #### //這些規則允許： #### // 具有可選的"id"屬性的`<p>`和`<h1>`元素 #### //具有必需的"href"屬性和可選的"id"屬性的<a> #### p h1; a[!href]; *[id] #### #### 調試 #### 為了驗證允許內容規則是否被正確解析了，可以檢查CKEDITOR.editor.filter對象的CKEDITOR.filter.allowedContent屬性。 #### ``` #### #### var editor = CKEDITOR.replace( 'textarea_id', { #### allowedContent: 'a[!href]; ul; li{text-align}(someclass)' } #### ); #### editor.on( 'instanceReady', function() { #### console.log( editor.filter.allowedContent ) #### } #### ); #### ``` #### // 這將對下列數組做日志： #### // { elements: 'p br', ... } (默認編輯器規則) #### // { elements: 'a', attributes: '!href' } #### // { elements: 'ul' } #### // { elements: 'li', styles: 'text-align', classes: 'someclass' } #### 對象格式（Object Format） #### 為方便使用，允許內容規則可以定義成標準的對象字面量，故下面的： #### #### allowedContent: 'p h1{text-align}; a[!href]; strong em; p(tip)' #### #### //與下面的相對應： #### #### ``` #### allowedContent: { #### 'p h1': { #### styles: 'text-align' #### }, #### a: { #### attributes: '!href' #### }, #### 'strong em': true, #### p: { #### classes: 'tip' #### } #### } #### #### ``` #### 采用此方法，允許內容規則可以由JavaScript動態地生成，并因任意目的存儲成JSON數據格式。注意：對象字面量的鍵必須是唯一的，因此： #### #### ``` #### allowedContent: { #### p: { #### styles: 'text-align' #### }, #### p: { #### classes: 'tip' #### } #### } #### ``` #### //等價于： #### allowedContent: 'p(tip)' #### //但永遠不會是： #### allowedContent: 'p{text-align}(tip)' #### #### 5、輸出格式化（Output Formatting） #### CKEditor提供了強大而又靈活的輸出格式化系統。它使開發人員可以完全控制由編輯器生成的HTML代碼的樣子。此系統可以控制所有HTML標記，并且可以給出每種標記不同的結果。 #### HTML編寫器（HTML Writer） #### HTML編寫器插件可以使CKEditor生成高級格式化的輸出。 #### CKEDITOR.htmlDataProcessor類使用"writer"來編寫輸出數據。因此，可以用editor.dataProcessor.writer屬性檢索出具體編輯器實例的當前編寫器。 #### 通過設置writer屬性可以配置幾種輸出格式化選項。下面的例子概括了最常用的幾種，給出了其默認值： #### var writer = editor.dataProcessor.writer; #### // 生一縮進步使用的字符串 #### writer.indentationChars = '\t'; #### //自結束標記的方式，就像`<br /> `writer.selfClosingEnd = ' />'; #### // 斷行所使用的字符串 writer.lineBreakChars = '\n'; #### // 標記的編寫規則 #### writer.setRules( 'p', { #### // 表示在此標記中斷行時縮進 #### indent: true, #### //在`<p>`的開始標記前插入斷行符 #### breakBeforeOpen: true, #### //在`<p>`的開始標記后插入斷行符 #### breakAfterOpen: true, #### // 在`<p>`的結束標記前插入斷行符 #### breakBeforeClose: false, #### // 在`<p>`的結束標記后插入斷行符 #### breakAfterClose: true }); #### #### 設置編寫器規則 #### 因為編輯器是每個編輯器實例的屬性，并且由于對加載的編寫器插件的依賴，對它進行修改的最好方法是監聽CKEDITOR.instanceReady事件；這樣含義可以安全地假設CKEDITOR.editor.dataProcessor屬性將會被加載，并準備好可以修改。下面的代碼展示了當生成編輯器實例時使用此方法的例子： #### ``` #### CKEDITOR.replace( 'editor1', { #### on: { #### instanceReady: function( ev ) { #### // Output paragraphs as <p>Text</p>. #### this.dataProcessor.writer.setRules( 'p', { #### indent: false, #### breakBeforeOpen: true, #### breakAfterOpen: false, #### breakBeforeClose: false, #### breakAfterClose: true #### }); #### } #### } #### }); #### ``` #### 另一種方法是使用CKEDITOR對象，這樣所有的編輯器實例會被改變： #### ``` #### CKEDITOR.on( 'instanceReady', function( ev ) { #### // Ends self closing tags the HTML4 way, like <br>. #### ev.editor.dataProcessor.writer.selfClosingEnd = '>'; #### }); #### #### ``` #### 6、拼寫檢查（Spell Checking） #### CKEditor可以被配置成使用本地由瀏覽器提供的拼寫檢查功能，也可以使用外部的拼寫檢查web服務。 #### 本地拼寫檢查器 #### 本地拼寫檢查功能默認情況在編輯器中是被禁用的，可以使用 disableNativeSpellChecker來使之生效： #### #### config.disableNativeSpellChecker = false; #### 在重新加載編輯器后，應該可以看到內容下面的拼寫下劃線。 #### 注意：如果上下文菜單插件生效，需要在右擊時按信CTRL鍵來查看建議。注意：一般情況下，拼寫檢查并不是對所有瀏覽器都是可用的。 #### SpellCheckAsYouType插件 #### SpellCheckAsYouType (SCAYT)插件提供了內聯（inline）拼寫檢查，更像本地的拼寫檢查器，與CKEditor上下文菜單很好地集成在一起。 #### 它是由 WebSpellChecker.net提供的。它使用其web服務，將文本傳遞到其服務器執行拼寫檢查。這是跨瀏覽器的解決方案。 #### #### WebSpellChecker插件 #### WebSpellChecker插件是由WebSpellChecker.net 提供的另一個拼寫檢查方案，它是通過一個對話窗口來運行查檢，而不是內聯標記拼寫不正確的單詞。 #### #### #### 7、文件瀏覽器和上傳 #### 與文件瀏覽器集成 #### CKEditor可以容易地與外部文件瀏覽器/上傳器進行集成。 #### 一旦正確地配置了，所有的文件瀏覽器功能將會自動變成可用。這包括Link、Image和 Flash Properties對話窗口中的Upload標簽（1），以及Browse Server 按鈕(2)中。 #### #### 基本配置 #### #### filebrowserBrowseUrl設置含有外部瀏覽器的位置，當按了Browse Server 按鈕后會啟動該瀏覽器。 #### filebrowserUploadUrl設置含有處理文件上傳腳本的位置。如果設置了，在一些對話窗口中會出現Upload 標簽--如果該功能在這些窗口中可用的話，即Link, Image and Flash Properties。 #### 例1 #### 下面的例子顯示了基本配置代碼，可以用于插入到配置了文件瀏覽的CKEditor實例中。 #### #### ``` #### CKEDITOR.replace( 'editor1', { #### filebrowserBrowseUrl: '/browser/browse.php', #### filebrowserUploadUrl: '/uploader/upload.php' #### }); #### ``` #### 例2 #### 也可以通過在文件瀏覽器設置：filebrowserBrowseUrl和filebrowserUploadUrl中，使用對話窗口名來為所選的對話窗口設置單獨的URL。 #### 對于為圖像對話窗口設置特殊的上傳URL的例子，使用 filebrowserImageUploadUrl屬性。 #### ``` #### CKEDITOR.replace( 'editor1', { #### filebrowserBrowseUrl: '/browser/browse.php', #### filebrowserImageBrowseUrl: '/browser/browse.php?type=Images', #### filebrowserUploadUrl: '/uploader/upload.php', #### filebrowserImageUploadUrl: '/uploader/upload.php?type=Images' #### }); #### ``` #### 在上面的例子中，filebrowserBrowseUrl和filebrowserUploadUrl 設置將在默認情況下使用。而在Image Properties對話窗口中，CKEditor將使用 filebrowserImageBrowseUrl和filebrowserImageUploadUrl 的配置設置。 #### 文件瀏覽器窗口的大小 #### 在CKEditor中，文件瀏覽器的默認寬度設置為屏幕寬度的80%，而默認高度設置為屏幕高度的70%。 #### 如果因為任意原因，默認值不適合你，你可以按需要進行調整，使用filebrowserWindowWidth改變窗口的寬度，使用filebrowserWindowHeight改變窗口的高度。 #### 要將文件瀏覽器窗口的大小定義成像素，將其設置為一個數字（如"800"）。如果你喜歡將窗口的高度和寬度設置為屏幕的百分數，不要忘記在數字后面加上百分號（如"60%"）。 #### #### 例3 #### 下面例子給出的基本配置代碼可以用于插入到配置了文件瀏覽器路徑和窗口大小的CKEditor中。 #### #### ``` #### CKEDITOR.replace( 'editor1', { #### filebrowserBrowseUrl: '/browser/browse.php', #### filebrowserUploadUrl: '/uploader/upload.php', #### filebrowserWindowWidth: '640', #### filebrowserWindowHeight: '480' #### }); #### ``` #### 要為指定的對話窗口設置文件瀏覽器的窗口大小，使用filebrowserWindowWidth和filebrowserWindowHeight 設置。 #### 例如，只想改變"Image"對話框中的文件瀏覽器的窗口大小，改變filebrowserImageWindowWidth和filebrowserImageWindowHeight的設置。 #### 例4 #### 下面例子給出的基本配置代碼可以用于插入到配置了文件瀏覽器路徑的CKEditor中。它還改變了文件瀏覽器窗口的默認尺寸，但僅當從Image Properties對話窗口中打開時。 #### #### ``` #### CKEDITOR.replace( 'editor1', { #### filebrowserBrowseUrl: '/browser/browse.php', #### filebrowserUploadUrl: '/uploader/upload.php', #### filebrowserImageWindowWidth: '640', #### filebrowserImageWindowHeight: '480' #### }); #### #### ``` #### 使用CKFinder #### CKEditor可以很容易地與CKFinder集成，它是一個高級的Ajax文件瀏覽器。看這里的現場演示。 #### 可以用兩種方式實現集成：通過設置CKEditor配置選項（下面的例子）或通過使用CKFinder API中可用CKFinder.SetupCKEditor()方法。 #### 例5 #### 下面例子給出的配置代碼可以用于插入到與CKFinder集成的CKEditor中。對于圖像和Flash對象的瀏覽和上傳路徑與CKFinder的默認路徑分開配置。 #### #### ``` #### CKEDITOR.replace( 'editor1', { #### filebrowserBrowseUrl: '/ckfinder/ckfinder.html', #### filebrowserImageBrowseUrl: '/ckfinder/ckfinder.html?Type=Images', #### filebrowserFlashBrowseUrl: '/ckfinder/ckfinder.html?Type=Flash', #### filebrowserUploadUrl:'/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files', #### filebrowserImageUploadUrl:'/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images', #### filebrowserFlashUploadUrl:'/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Flash' #### }); #### ``` #### 上面的例子對PHP環境有效。注意：/ckfinder/ 是CKFinder安裝目標的基路徑。 #### 如果你想在ASP, ASP.NET, 或 ColdFusion中使用CKFinder，記住將上面的php修改為正確的擴展名： #### ``` #### asp – CKFinder for ASP #### aspx – CKFinder for ASP.NET #### cfm – CKFinder for ColdFusion #### php – CKFinder for PHP #### ``` #### 例6 #### 下面例子說明了CKFinder.SetupCKEditor()的使用，可以插入到與CKFinder集成的CKEditor實例中。 #### ``` #### #### var editor = CKEDITOR.replace( 'editor1' ); #### CKFinder.SetupCKEditor( editor, '/ckfinder/' ); #### ``` #### SetupCKEditor()方法的第二個參數是CKFinder的安裝路徑。 #### 請查看與CKFinder一起發布的 _samples/js/ckeditor.html 例子，查看此集成方法的完整工作示例。 #### #### #### PHP API #### 至于CKFinder 1.4.2和CKEditor 3.1，可以使用PHP API將CKFinder與CKEditor集成。更多細節，參見 CKFinder for PHP文檔。其它資源 #### 關于將CKEditor與文件瀏覽器集成的更高級信息，參閱下面的文章： #### #### Creating a Custom File Browser（生成定制的文件瀏覽器） #### Adding the File Browser to Dialog Windows（將文件瀏覽器添加到對話窗口中） #### 文件瀏覽器API #### CKEditor可以很容易地與你自己的文件瀏覽器進行集成。 #### #### 要連接與CKEditor兼容的文件瀏覽器（如 CKFinder），遵循 File Browser (Uploader)文檔。 #### #### CKEditor與文件瀏覽器之間的交互 #### CKEditor自動向文件瀏覽器發送一些附加的參數： #### #### CKEditor – CKEditor實例名, #### langCode – CKEditor的語言 (英語為en), #### CKEditorFuncNum – 匿名函數引用編號，用于將文件的URL傳給CKEditor（一個隨機數）。 #### 例如： #### CKEditor=editor1&CKEditorFuncNum=1&langCode=en #### #### 例1 #### 假設CKEditor由下面的JavaScript調用生成： #### ``` #### #### #### CKEDITOR.replace( 'editor2', { #### filebrowserBrowseUrl: '/browser/browse.php?type=Images', #### filebrowserUploadUrl: '/uploader/upload.php?type=Files' #### }); #### ``` #### 為了瀏覽文件，CKEditor將調用： #### /browser/browse.php?type=Images&CKEditor=editor2&CKEditorFuncNum=2&langCode=de #### 該調用包括下面的元素： #### ``` #### #### /browser/browse.php?type=Images – filebrowserBrowseUrl參數的值 #### &CKEditor=editor2&CKEditorFuncNum=2&langCode=de – 由CKEditor:添加的信息。 #### ``` #### CKEditor=editor2 – CKEditor實例名 (editor2), #### #### CKEditorFuncNum=2 – 匿名函數的引用編號，將用于 callFunction中， o langCode=de – 語言編碼(此例中: German). 此參數可以用于發送本地化的錯誤信息。 #### #### 傳遞所選文件的URL #### 要從外部文件瀏覽器中傳回文件的URL，調用CKEDITOR.tools.callFunction，并將CKEditorFuncNum作為第一個參數進行傳遞： #### #### window.opener.CKEDITOR.tools.callFunction( funcNum, fileUrl [, data] ); #### 如果data（第三個參數）是字符串，將由CKEditor進行顯示。如果在文件上傳時發生了問題，此參數通常作為錯誤信息顯示。例2 #### 下面的例子說明了如何使用JavaScript代碼從文件瀏覽器中傳遞URL： #### //從查詢字符串中獲得參數的 Helper函數 #### #### ``` #### function getUrlParam( paramName ) { #### var reParam = new RegExp( '(?:[\?&]|&)' + paramName + '=([^&]+)', 'i' ) #### var match = window.location.search.match(reParam) return ( match && match.length > 1 ) ? match[ 1 ] : null #### } #### ``` #### var funcNum = getUrlParam( 'CKEditorFuncNum' ); #### var fileUrl = '/path/to/file.txt'; #### window.opener.CKEDITOR.tools.callFunction( funcNum, fileUrl ); #### #### 例3 #### 下面的代碼說明了如何從PHP連接器中傳回上傳文件的URL： #### #### ``` #### <?php #### // Required: anonymous function reference number as explained above. #### $funcNum = $_GET['CKEditorFuncNum'] #### // Optional: instance name (might be used to load a specific configuration file or anything else). #### $CKEditor = $_GET['CKEditor'] #### // Optional: might be used to provide localized messages. #### $langCode = $_GET['langCode'] #### // Check the $_FILES array and save the file. Assign the correct path to a variable ($url). #### $url = '/path/to/uploaded/file.ext'; #### // Usually you will only assign something here if the file could not be uploaded. #### $message = echo "<script type='text/javascript'>window.parent.CKEDITOR.tools.callFunction($funcNum, '$url', '$message');</script>"; #### ?> #### ``` #### #### 例4 #### 如果data是一個函數，將在調用此文件瀏覽器的按鈕范圍內執行它。這意味著服務器連接器可以直接訪問CKEditor和按鈕所屬的對話窗口。 #### 假設除了傳遞根據對話窗口定義自動賦給相應域的fileUrl外，如果文件瀏覽器在Image Properties 對話窗口中打開，你還想設置alt屬性。為此，將匿名函數作為第三個參數傳遞： #### ``` #### window.opener.CKEDITOR.tools.callFunction( funcNum, fileUrl, function() { #### // 獲得對話窗口的引用 #### var element, #### dialog = this.getDialog(); #### //檢查是否為Image對話窗口 #### if ( dialog.getName() == 'image' ) { #### // 獲得具有"alt"屬性的文本域的引用 #### element = dialog.getContentElement( 'info', 'txtAlt' ); #### // 賦新值 #### if ( element ) #### element.setValue( 'alt text' ); #### } ... #### // 返回false，停止進一步執行- - 在這種情況下，CKEditor將忽略第二個參數 (fileUrl) #### // 和賦給調用文件瀏覽器按鈕的onSelect函數 (如果定義了). [return false;] }); #### #### ``` #### 將文件瀏覽器添加到對話框中 #### CKEditor可以很容易地與你自己的文件瀏覽器集成。 #### 要連接與CKEditor兼容的文件瀏覽器（如 CKFinder），遵循 File Browser (Uploader)文檔。 #### #### 對話框 #### 請參考 Dialog definition API，獲得如何生成一個對話框的一般幫助。 #### #### Filebrowser 插件 #### filebrowser插件內置于CKEditor中。它的唯一目的是在CKEditor中提供一個API，可以集成任意外部文件瀏覽器，并為各種CKEditor組件（通常為對話框）增加文件瀏覽功能。 #### #### 添加"Browse Server"按鈕 #### 要將文件瀏覽器插件添加到一個對話框中的元素，設置"filebrowser"屬性。在image插件的例子中，有： #### #### ``` #### { #### type: 'button', #### hidden: true, #### id: 'browse', #### filebrowser: ' #### Link:txtUrl', #### label: editor.lang.common.browseServer, #### style: 'float:right', #### }, #### ``` #### 此按鈕默認是隱藏的 (hidden:true)。文件瀏覽器插件查找具有filebrowser屬性的所有元素，并且如果有可用的相應的配置設置(filebrowserBrowseUrl/filebrowserUploadUrl)，就不再隱藏它們。 #### 插件所執行的操作取決于元素的類型，對于fileButton，操作為QuickUpload，對于其它元素，默認的操作是Browse。在上面的例子中，當點擊按鈕時，將會啟動文件瀏覽器（在彈出窗口中）。 #### 'Link:txtUrl' 值告訴插件當調用CKEDITOR.tools.callFunction( funcNum )時，更新Link標簽中id為txtUrl的元素。 #### 添加 "Quick Upload"支持 #### 再次看看如何在我們的對話框中處理文件上傳，我們將使用來自CKEditor的工作示例。在image插件中，有一個Upload標簽定義： #### #### ``` #### { #### id: 'Upload', #### hidden: true, #### filebrowser: 'uploadButton', #### label: editor.lang.image.upload, #### elements: [ #### { #### type: 'file', #### id: 'upload', #### label: editor.lang.image.btnUpload, #### style: 'height:40px', #### size: 38 #### }, #### { #### type: 'fileButton', #### id: 'uploadButton', #### filebrowser: 'info:txtUrl', #### label: editor.lang.image.btnUpload, #### 'for': [ 'Upload', 'upload' ] #### } #### ] #### }, #### ``` #### 此例較前一例子稍復雜一些，因為1）這里有整個標簽的定義2）我們需要兩個元素：file和fileButton來上傳文件。 #### 在上面的例子中，標簽的id為'Upload'。它默認是隱藏的（hidden:true）。正如已提到的，文件瀏覽器插件查找具有filebrowser屬性的所有元素，并且如果相應的配置設置可用就不隱藏它們。在此例中，如果'uploadButton'文件瀏覽器設置（因為filebrowser:'uploadButton'）將成為可用(filebrowserUploadUrl)，則將自動不再隱藏此標簽。 #### file元素很簡單，不需要做解釋，它只是一個input元素，將保存將要上傳的文件名。 fileButton元素較有趣。'info:txtUrl'值使文件瀏覽器插件當調用 CKEDITOR.tools.callFunction( funcNum )時（參見 Custom File Browser），更新info標簽中id為txtUrl的元素。'for': [ 'Upload', 'upload' ] 一行用于將fileButton與file元素相關聯。它是CKEditor上傳文件的一條指令，在'Upload標簽'（第一個值）中使用id為'upload'的'file'元素。 #### 高級配置（瀏覽） #### 可以定義自己的函數，當選擇/上傳文件時可以調用它。 #### #### ``` #### #### { #### type: 'button', #### hidden: true, #### id: 'id0', #### label: editor.lang.common.browseServer, #### filebrowser: { #### action: 'Browse', #### // target: 'tab1:id1', #### onSelect: function( fileUrl, data ) { #### alert( 'The selected file URL is "' + fileUrl + '"' ); #### for ( var _info in data ) #### alert( 'data[ "' + _info + '" ]' + ' = ' + data[ _info ] ); #### var dialog = this.getDialog(); #### dialog.getContentElement( 'tab1', 'id1' ).setValue( data[ 'fileUrl' ] ); //不要調用內置的onSelect命令 #### return false; #### } #### } #### } #### ``` #### 在此例中，我們設置了'Browse'操作，當點擊按鈕時調用文件瀏覽器。'target'不是必需的，因為我們將在定制的onSelect函數中更新目標元素。 #### 如在此文檔中說明的，當用戶選擇了一個文件時，我們已調用了 CKEDITOR.tools.callFunction( funcNum, fileUrl, data )；。fileUrl和data參數被傳遞給我們定制的onSelect函數，我們可以使用它來更新目標元素。 #### 高級配置（快速上傳） #### 用我們配置按鈕打開文件瀏覽器相同的方法，我們配置fileButton。 #### #### ``` #### #### { #### type: 'file', #### label: editor.lang.common.upload, #### labelLayout: 'vertical', #### id: 'id2' #### }, #### { #### type: 'fileButton', #### label: editor.lang.common.uploadSubmit, #### id: 'id3', #### filebrowser: { #### action: 'QuickUpload', #### params: { type: 'Files', currentFolder: '/folder/' }, #### target: 'tab1:id1', #### onSelect: function( fileUrl, errorMessage ) { #### alert( 'The url of uploaded file is: ' + fileUrl + '\nerrorMessage: ' + errorMessage ); #### // Do not call the built-in onSelect command #### // return false; #### } #### }, #### 'for': [ 'tab1', 'id2' ] #### } #### #### ``` #### #### 在filebrowser.params屬性中，我們可以添加其它參數，在查詢字符串中傳遞給外部文件瀏覽器。filebrowser.target是當通過服務器連接器（uploader）返回文件時被更新的目標元素--如果我們定義了自己的onSelect函數(filebrowser.onSelect)并在此函數中更新了目標元素，就像前一例子中的作法，我們就不不需要此目標元素。 #### ## 四、定制 #### 1、插件 #### CKEditor是完全基于插件的。實際上，編輯器的核心是一個空盒子，它由插件提供的功能來進行填充。甚至編輯器的界面，像工具欄、按鈕和編輯區也是插件。 #### CKEditor的默認安裝，可能你正在使用，具有一些展現于其中的插件。你可以將插件添加到你的編輯器中，給你的用戶帶來更好更有用的功能。 #### #### 在哪里尋找插件？ #### CKEditor Add-ons Repository是尋找和共享插件的在線服務。它可以很容易地理解插件功能，與CKEditor群體進行交往。如果你是一個插件開發者，它也是一個展示你的技能，獲得大量用戶基礎的最佳地方。 #### 用CKBuilder生成定制的編輯器 #### CKBuilder 是CKEditor Add-ons Repository的姊妹服務，可以通過選擇更適合你需要的插件來生成定制的編輯器。 #### 通過插件件的導航，你可以使用 "Add to my editor button" 將你喜歡的插件發到你定制的編輯器中。一旦完成，你可以簡單地下載插件，盡享完美實現你需要的編輯體驗。 #### #### 手動安裝插件 #### 如果你不喜歡使用CKBuilder，如果你有自己的或第三方插件，或如果你只想在經歷CKBuilder過程前測試插件，你還可以將插件添加到你本地的安裝中，通過下面的幾個步驟： #### 1. 解壓zip文件：插件通常是zip文件。所以要想開始，要確保將zip文件解壓到一個文件夾中。 #### 2. 復制文件到CKEditor中：最簡單的安裝文件的方法是通過簡單地將文件復制到CKEditor安裝目錄的plugins文件夾中。必須放到與插件"技術"名字相匹配的子文件夾中。例如， Magic Line plugin將被安裝到這樣的文件夾中：`<CKEditor folder>`/plugins/magicline。 #### 3. 使插件生效：現在是時候告訴CKEditor你為它加了新的插件。為此，你簡單地使用extraPlugins配置選項：config.extraPlugins = 'magicline'; 就是這些。現在你的插件就可以在CKEditor中生效了。 #### #### 2、皮膚 #### CKEditor的用戶界面外觀完全可以通過皮膚來進行定制。像工具欄、對話框、按鈕以及甚至其圖標這些元素都可以按你喜歡的樣式進行改變。 #### CKEditor的默認安裝具有Moono skin。 #### #### 到哪里尋找皮膚？ #### CKEditor Add-ons Repository是尋找和共享皮膚的在線服務。如果你是一個皮膚開發者，它也是一個展示你的技能，獲得大量用戶基礎的最佳地方。 #### #### 下載帶有你喜歡皮膚的CKEditor #### CKBuilder 是CKEditor Add-ons Repository的姊妹服務，可以生成具有所需皮膚的定制編輯器。 #### #### 手動安裝皮膚 #### 如果你不喜歡使用CKBuilder，如果你有自己的或第三方皮膚，或如果你只想在經歷CKBuilder過程前測試皮膚，你還可以將皮膚添加到你本地的安裝中，通過下面的幾個步驟： #### 1. 解壓zip文件：皮膚通常是zip文件。所以要想開始，要確保將zip文件解壓到一個 #### 文件夾中。 #### 2. 復制文件到CKEditor中：最簡單的安裝文件的方法是通過簡單地將文件復制到 #### CKEditor安裝目錄的skins文件夾中。必須放到與皮膚"技術"名字相匹配的子文件夾中。例如，Kama skin 將被安裝到這樣的文件夾中：<CKEditor folder>/skins/kama。 3. Enabling the plugin: Now you must just setup CKEditor, by using the skin configuration #### option: #### 4. 使插件生效：現在你只需要配置CKEditor，通過使用skin配置選項： 5. config.skin = 'kama'; #### 就是這些。現在新皮膚就可以在CKEditor中生效了。