HTMLArea 是一套自由的 WYSIWYG 編輯器, 能取代 <textarea> 欄位. 祇要在妳的網頁中加入幾列簡單的 JavaScript 源碼, 就可以把標準的 textarea 換成豐富的文字編輯器, 藉此妳可以:
以下列出一些 HTMLArea 格外有趣的特色, 這些特色使得 HTMLArea 跟其他 WYSIWYG 編輯器更加與眾不同:
沒錯! 它真的是自由的. 妳可以使用, 修改, 跟妳的軟體一起散佈, 或者任意對它加以處置.
HTMLArea 需要 Internet Explorer >= 5.5 (祇有 Windows 版纔能用), 或任何作業系統平台上的 Mozilla >= 1.3-Beta. 任何採用 Gecko 引擎的瀏覽器也都能動, 祇要他們採用的 Gecko 版本至少要是 Mozilla-1.3-Beta 裏的版本 (舉例來說, Galeon-1.2.8 就可以). 然而, 在其他的瀏覽器上它至少也能優雅地降級回來; 他們雖然不會看到 WYSIWYG 編輯器, 但至少可以看到標準的 textarea 欄位.
請先確認妳正在使用上述提及的瀏覽器, 然後參見以下的範例.
妳可以在 HTMLArea 首頁找到更多關於 HTMLArea 的消息，也能下載最新的版本; 此外妳也能在 HTMLArea 討論區裏跟其他的 HTMLArea 使用者交流心得或發表建言.
這個編輯器提供了下列的組合鍵:
這很容易. 首先妳得把 HTMLArea 的檔案上傳到妳的網站. 請按照下列步驟.
一旦 htmlArea 在妳的網站上之後, 當妳想要為某一個頁面加上所見即所得編輯器時, 就祇需要加上一些 JavaScript 即可. 以下就是實際的作法.
<script type="text/javascript"> _editor_url = "/htmlarea/"; _editor_lang = "en"; </script>
<script type="text/javascript" src="/htmlarea/htmlarea.js"></script>
如果妳想要把妳所有的 <textarea> 通通都變成 HTMLArea 的話, 最簡單的方法會是:
<script type="text/javascript" defer="1"> HTMLArea.replaceAll(); </script>
請注意: 如果妳會覺得更適當的話, 也可以把 HTMLArea.replaceAll() 源碼加進 body 組件的 onload 事件裏.
還有個不同的方法. 如果妳有許多 textarea, 而妳祇想變更其中一個的話, 則可以用 HTMLArea.replace("id") ──把 textarea 的 id 給傳進去. 請不要再用 name 屬性了, 那並不是標準的解決方案!
接下來這一段適用於 HTMLArea-3.0 第一釋出候選版或更新的版本; 在這一個版本以前, 妳可能得加入更多的檔案纔行, 然而現在 HTMLArea 已經能夠把這些檔案自動加進來了 (像是樣式表, 語系定義檔等等) 所以妳現在祇需要定義編輯器的路徑, 並載入 "htmlarea.js" 即可. 很棒, 不是嗎? ;-)
不但祇需要加入一列 JavaScript 就能建立 HTMLArea 所見即所得編輯器, 妳還可以在源碼中指定更多組態設定, 來決定它將如何運作, 以及它的樣貌該是如何. 底下是一些可用設定的範例:
var config = new HTMLArea.Config(); // 建立新的組態物件 // 並使用所有的預設值 config.width = '90%'; config.height = '200px'; // 底下的設定會指定頁面 body 的樣式 (黃底黑字) // 並讓所有的段落預設都會變粗體 config.pageStyle = 'body { background-color: yellow; color: black; font-family: verdana,sans-serif } ' + 'p { font-width: bold; } '; // 底下這邊會把具有給定 id 的 textarea 代換成 // 特定組態的 HTMLArea 物件 HTMLArea.replace('id', config);
重要: 我們強烈建議妳把這些自訂功能及組態加到另一個檔案裏. 如此一來, 當我們正式釋出新版的 HTMLArea 時, 纔能確保妳升級不會太苦.
使用前述的組態物件, 也能讓妳完全操控工具列的內容. 底下這個範例是個祇有一列的自訂化工具列, 比預設的工具列還要單純許多:
var config = new HTMLArea.Config(); config.toolbar = [ ['fontname', 'space', 'fontsize', 'space', 'formatblock', 'space', 'bold', 'italic', 'underline'] ]; HTMLArea.replace('id', config);
這個工具列是個陣列物件的陣列. 工具列裏的每一個陣列都會定義一列新的工具列. 預設的工具列看起來會像這樣:
config.toolbar = [ [ "fontname", "space", "fontsize", "space", "formatblock", "space", "bold", "italic", "underline", "separator", "strikethrough", "subscript", "superscript", "separator", "copy", "cut", "paste", "space", "undo", "redo" ], [ "justifyleft", "justifycenter", "justifyright", "justifyfull", "separator", "insertorderedlist", "insertunorderedlist", "outdent", "indent", "separator", "forecolor", "hilitecolor", "textindicator", "separator", "inserthorizontalrule", "createlink", "insertimage", "inserttable", "htmlmode", "separator", "popupeditor", "separator", "showhelp", "about" ] ];
除了三個字串外, 上述範例中的其他東西都得要被定義在 config.btnList 物件裏纔行 (這份文件稍後會對此有較詳細的說明). 這三個例外字串分別是: 'space', 'separator' 和 'linebreak'. 這三個字串的意義如下, 它們不能出現在 btnList:
重要: 我們強烈建議妳把這些自訂功能及組態加到另一個檔案裏. 如此一來, 當我們正式釋出新版的 HTMLArea 時, 纔能確保妳升級不會太苦.
在設計上, 這個工具列應該要是易於延展的. 當妳打算要加入自訂按鈕時, 祇需要兩個步驟.
config.btnList 裏.對於工具列中的每一個按鈕來說, HTMLArea 都得要得知下列這些資訊:
當妳要登錄新按鈕時, 也得要提供這些資訊. 其中按鈕 ID 可以是任何字串識別符, 會在定義工具列時用到, 這個我們稍早已經介紹過了. 我們建議妳把自訂工具列按鈕的 ID 以 "my-" 開頭來命名, 這麼一來纔不會跟標準的 ID (在預設工具列裏的那些) 相衝突.
登錄按鈕範例 #1
// 取得預設組態 var config = new HTMLArea.Config(); // 使用 Config.registerButton 來登錄新的按鈕. // 參數: 按鈕 ID, 工具提示, 圖片, 純文字模式, config.registerButton("my-hilite", "Highlight text", "my-hilite.gif", false, // 按鈕被按下時所要叫用的函式 function(editor, id) { editor.surroundHTML('<span class="hilite">', '</span>'); } );
另一種叫用 registerButton 的作法犯例如下. 這種作法中的源碼應該會大些, 不過也會讓妳的源碼更易於維護些. 甚至不需要加上註解, 就很清楚明白了.
登錄按鈕範例 #2
var config = new HTMLArea.Config(); config.registerButton({ id : "my-hilite", tooltip : "Highlight text", image : "my-hilite.gif", textMode : false, action : function(editor, id) { editor.surroundHTML('<span class="hilite">', '</span>'); } });
也許妳已經注意到了 "action" 函式會接收兩個參數: editor 和 id. 在上述的範例中, 我們祇用到了 editor 參數. 不過如果妳兩個都能弄懂的話, 會非常有幫助:
到了這一步時, 妳得要指定要把按鈕插入至工具列的哪裡, 或者像前一個小節裏提到的那樣, 重新再設計一次整個工具列. 妳會用到按鈕 ID, 正如前一小節中自訂工具列的範例那樣.
基於貫徹始終的原則, 底下是另一個範例.
把妳的按鈕附加到預設工具列之後
config.toolbar.push([ "my-hilite" ]);
自訂過的工具列
config.toolbar = [ ['fontname', 'space', 'fontsize', 'space', 'formatblock', 'space', 'separator', 'my-hilite', 'separator', 'space', // 妳的按鈕在這邊 'bold', 'italic', 'underline', 'space'] ];
請注意: 在上述的範例中, 我們的新按鈕被放在兩個垂直的分隔線之間. 不過這並不表示妳非得跟著這麼做不可. 妳可以把它隨意放在妳喜歡的位置上. 一旦它被登錄在 btnList (步驟 1) 後, 妳的自訂按鈕就會跟其他預設按鈕一樣運作.
重要: 我們強烈建議妳把這些自訂功能及組態加到另一個檔案裏. 如此一來, 當我們正式釋出新版的 HTMLArea 時, 纔能確保妳升級不會太苦.
請注意這並非意味著妳一定得把下列這些源碼放進 htmlarea.js 檔案裏. 相反地, 那樣反而可能無法正常運作. 整個組態系統被設計成可以隨時使用外部檔案來自訂編輯器, 這麼一來 htmlarea.js 檔案就能夠保持完整了. 如此一來, 當我們正式釋出新版的 HTMLArea 時, 纔能確保妳升級不會太苦. 好啦, 我保證這是我最後一次提到這件事了. ;)
// 我們任何的自訂按鈕被按下時, 都會叫用這個函式. // 我們用了 buttonId 參數來偵測是哪一個按鈕叫用了這個函式 function clickHandler(editor, buttonId) { switch (buttonId) { case "my-toc": editor.insertHTML("<h1>Table Of Contents</h1>"); break; case "my-date": editor.insertHTML((new Date()).toString()); break; case "my-bold": editor.execCommand("bold"); editor.execCommand("italic"); break; case "my-hilite": editor.surroundHTML("<span class=\"hilite\">", "</span>"); break; } }; // 建立一個新的組態物件 var config = new HTMLArea.Config(); // 登錄我們的自訂按鈕 config.registerButton("my-toc", "Insert TOC", "my-toc.gif", false, clickHandler); config.registerButton("my-date", "Insert date/time", "my-date.gif", false, clickHandler); config.registerButton("my-bold", "Toggle bold/italic", "my-bold.gif", false, clickHandler); config.registerButton("my-hilite", "Hilite selection", "my-hilite.gif", false, clickHandler); // 把按鈕附加到預設的工具列後面 config.toolbar.push(["linebreak", "my-toc", "my-date", "my-bold", "my-hilite"]); // 把某個既有的 textarea 代換成 HTMLArea 物件, 並使用上述的組態. HTMLArea.replace("textAreaID", config);