UEditor除 了具有輕量、可定制等優點外,還始終將優化編輯操作、提升用戶體驗擺在了很重要的位置。在這一點上,除了對編輯器功能、性能、實現細節等不斷地改進和追求 創新之外,眾多靈活而人性化的自定義配置也充分地體現了這個特點,通過修改配置項的值,用戶幾乎可以完全地改變編輯器的外觀和行為。
從配置本身的優先級來看,UEditor的配置可以分為系統默認配置和用戶自定義配置兩種類型。系統默認配置是指editor_config.js中的所有配置,而用戶自定義配置則是指用戶在實例化編輯器的時候傳入的JSON格式的配置。用戶自定義配置的優先級高於系統默認配置,若兩者同名,則覆蓋系統默認配置。若未提供對應的用戶自定義配置,則采用系統默認配置。一般情況下,推薦用戶在實例化的時候使用自定義配置來代替修改系統默認配置。
從配置對編輯器的作用來看,UEditor的配置又可以分為界面配置和功能配置兩種類型。界面配置主要集中在工具欄配置和初始化配置上;功能配置由於相對較多,下文將篩選一些同學們容易迷惑的配置項來進行講解,而其他簡單的則只要參考具體配置項對應的注釋即可。
- 界面配置
1、工具欄配置
默認配置項中包含了編輯器的所有按鈕,需要改變時,只要在初始化的時候傳入對應參數即可。示例代碼如下:
var editor = new baidu.editor.ui.Editor({ toolbars:[['Paragraph','RowSpacing','FontFamily','FontSize']] }); editor.render("myEditor");
這個時候的編輯就只有四個工具按鈕了。關於工具欄的更多高級配置,比如改變布局結構,雙欄和單欄混排等等
2、初始化內容 實例化的時候可以使用<textarea id="editor">初始內容</textarea>來為編輯器賦初始值。以PHP為例的話,可以將“初始內容”替換成<?=$content?>來動態從服務器去獲取。當有些地方不適合使用textarea作為編輯器容器時,比如上文采用div作為容器時,那如何來初始化內容:
var editor = new baidu.editor.ui.Editor({ initialContent: '<span style="color:#ccc">歡迎使用ueditor</span>' }); editor.render("myEditor");
3、初始化樣式 由於編輯器的編輯框位於一個單獨的iframe中,因此希望通過在編輯器實例化頁面設置編輯框中的元素樣式是行不通的。UEditor為大家提供了兩種方 式來改變編輯框中的元素樣式:一種是通過修改initialStyle的內容來實現,另外一種是通過iframeCssUrl引用外部的CSS文件來實現。具體的代碼例子如下:
var editor = new baidu.editor.ui.Editor({ initialStyle: 'body{margin:8px;font-family:"宋體";font-size:16px;}', iframeCssUrl: 'themes/default/iframe.css' }); editor.render("myEditor");
需要注意的是,如果同時配置了這兩個參數,那么initialStyle中的配置將優先於iframeCssUrl指向的CSS文件中的配置。另外,由於編輯器中的有些功能效果實現需要依賴於initialStyle中的默認配置,比如框選表格的藍色背景效果,因此,一般情況下不建議用戶刪除默認配置項中的默認樣式類,除非已經確認不需要對應的功能。
4、ElementPath
編輯框下部的path部分。不需要的同學設置elementPathEnabled : false即可。
5、字數統計
編輯框下部的字數統計部分。不需要的同學設置wordCount:false 即可。當設置開啟時,還可以通過maximumWords參數來控制允許的最大字符數、wordCountMsg參數來控制需要顯示的提示文字、 wordOverFlowMsg參數來控制超出最大字數限制時候的提示文字。
6、編輯器最小高度和自動長高
編輯器的最小高度由配置項minFrameHeight來確定,而autoHeightEnabled:true則讓編輯器的編輯框部分可以隨着編輯內容的增加而自動長高。
7、工具欄浮動
工具欄浮動是指當編輯框的頂部超出了瀏覽器頂部的時候,工具欄會一直浮動在瀏覽器的頂部,方便大家的編輯操作。在編輯框高度固定的編輯器實例頁面中,建議關閉此項功能以獲得最好的性能和體驗:autoFloatEnabled: false
- 功能配置
UEditor由於功能點較多,同時又希望能夠帶給用戶更加靈活個性的編輯需求,因此在功能配置上顯得有點令人眼花繚亂。不過對於大部分用戶來說,維持默認配置是最佳的選擇,實在有特殊需求時才考慮修改配置。 盡管配置較多,但是大部分配置都一目了然,基本不需要特別的解釋。這里總結出同學們問的較多的一些配置項進行簡單的講解,其余配置請同學們自行查看editor_config.js文件中的對應注釋即可。
1、提交表單的域名
將編輯器的容器置於一個form表單之中,后台如何獲取編輯器中的內容呢?UEditor內部做了自動處理,無需用戶諸如再創建一個隱藏表 單來放置編輯內容等操作,只需要在配置項中設置textarea : 'editorValue'即可,后台則可以直接通過$_POST['editorValue']或者 request.getParameter("editorValue")等方式來獲取編輯器中的內容。
2、黑白名單 UEditor提供了功能強大的黑白名單過濾機制,簡單的幾個配置就可以攔截任何不安全因素於編輯器之外。黑白名單可以同時使用,也可以單獨分開使用。黑名單中的標簽將會被編輯器完整地過濾掉,包括標簽本身以及標簽之內的任何內容。而不在白名單之中的那些標簽則僅被過濾了標簽本身,其內容會繼續走過濾流程。
具體的黑白名單配置示例如下所示,其中$表示元素的屬性:
serialize : function(){ return { //黑名單,表示不允許任何style、script、link、object、applet和input標簽 blackList: {style:1,script:1,link:1,object:1,applet:1,input:1}, //白名單 whiteList: { //表示允許div標簽,且其可包含p、span和br標簽,style、class屬性 div: {p:1,span:1,br:1,$:{style:1,class:1}}, //表示允許img標簽,且只能包含href、title和alt屬性 img: {$:{href:1,title:1,alt:1}} } } }()
3、表情本地化
鑒於有些內網用戶不能訪問外網而導致的編輯器表情功能不可用,從1.1.7正式版開始,UEditor提供了表情本地化功能。更改配置 emotionLocalization:true 即可開啟本地表情功能。當然,本地表情功能必須要確保dialogs/emotion/目錄下存在官方提供的images文件夾及所有表情文件。