Table of Contents
1.
Programming Guide
1.1.
Prototype是什么?
1.2.
關聯文章
1.3.
通用性方法
1.3.1.
使用 $()方法
1.3.2.
使用$F()方法
1.3.3.
使用$A()方法
1.3.4.
使用$H()方法
1.3.5.
使用$R()方法
1.3.6.
使用Try.these()方法
1.4.
Ajax 對象
1.4.1.
使用 Ajax.Request類
1.4.2.
使用 Ajax.Updater 類
2.
prototype.js參考
2.1.
JavaScript 類的擴展
2.2.
對 Object 類的擴展
2.3.
對 Number 類的擴展
2.4.
對 Function 類的擴展
2.5.
對 String 類的擴展
2.6.
對 document DOM 對象的擴展
2.7.
對 Event 對象的擴展
2.8.
在 prototype.js中定義的新對象和類
2.9.
PeriodicalExecuter 對象
2.10.
Prototype 對象
2.11.
Class 對象
2.12.
Ajax 對象
2.13.
Ajax.Base 類
2.14.
Ajax.Request 類
2.15.
options 參數對象
2.16.
Ajax.Updater 類
2.17.
Ajax.PeriodicalUpdater 類
2.18.
Element 對象
2.19.
Abstract 對象
2.20.
Abstract.Insertion 類
2.21.
Insertion 對象
2.22.
Insertion.Before 類
2.23.
Insertion.Top 類
2.24.
Insertion.Bottom 類
2.25.
Insertion.After 類
2.26.
Field 對象
2.27.
Form 對象
2.28.
Form.Element 對象
2.29.
Form.Element.Serializers 對象
2.30.
Abstract.TimedObserver 類
2.31.
Form.Element.Observer 類
2.32.
Form.Observer 類
2.33.
Abstract.EventObserver 類
2.34.
Form.Element.EventObserver 類
2.35.
Form.EventObserver 類
2.36.
Position 對象 (預備文檔) 覆蓋版本 1.3.1
Chapter 1. Programming Guide
1.1. Prototype是什么?
或許你還沒有用過它， prototype.js 是一個由 Sam Stephenson 寫的JavaScript包。這個構思奇妙編寫良好的一段 兼容標準 的一段代碼將承擔創造胖客戶端， 高交互性WEB應用程序的重擔。輕松加入Web 2.0特性。
如果你最近體驗了這個程序包，你很可能會發現文檔并不是它的強項之一。像所有在我之前的開發者一樣，我只能一頭扎進prototype.js的源代碼中并且試驗其中的每一個部分。 我想當我學習他的時候記寫筆記然后分享給其他人將會很不錯。
我也一起提供了這個包的對象，類，方法和擴展的 非官方參考 。
1.2. 關聯文章
高級 JavaScript指南
1.3. 通用性方法
這個程序包里面包含了許多預定義的對象和通用性方法。編寫這些方法的明顯的目的就是為了減少你大量的重復編碼和慣用法。
1.3.1. 使用 $() 方法
$() 方法是在DOM中使用過于頻繁的 document.getElementById() 方法的一個便利的簡寫，就像這個DOM方法一樣，這個方法返回參數傳入的id的那個元素。
比起DOM中的方法，這個更勝一籌。你可以傳入多個id作為參數然后 $() 返回一個帶有所有要求的元素的一個 Array 對象。下面的例子會向你描述這些。
<HTML> <HEAD> <TITLE> Test Page </TITLE> <script src="prototype-1.3.1.js"></script> <script> function test1() { var d = $('myDiv'); alert(d.innerHTML); } function test2() { var divs = $('myDiv','myOtherDiv'); for(i=0; i<divs.length; i++) { alert(divs[i].innerHTML); } } </script> </HEAD> <BODY> <div id="myDiv"> <p>This is a paragraph</p> </div> <div id="myOtherDiv"> <p>This is another paragraph</p> </div> <input type="button" value=Test1 onclick="test1();"><br> <input type="button" value=Test2 onclick="test2();"><br> </BODY> </HTML>
這個方法的另一個好處就是你可以傳入id字符串或者元素對象自己，這使得在創建可以傳入任何形式參數的方法的時候， 它變得非常有用。
1.3.2. 使用 $F() 方法
$F() 方法是另一個非常受歡迎的簡寫。它可以返回任何輸入表單控件的值，如文本框或下拉框。 這個方法可以傳入元素的id或者元素自己。
<script> function test3() { alert(
$F('userName') ); } </script> <input type="text" id="userName" value="Joe Doe"><br> <input type="button" value=Test3 onclick="test3();"><br>
1.3.3. 使用 $A() 方法
$A() 方法把接收到的參數轉換成一個 Array 對象。
這個方法加上對 Array 類的擴展，可以很容易的轉換或者復制任意的列舉列表到 Array 對象， 一個被推薦使用的用法就是轉換 DOM 的 NodeLists 到一個普通的數組里，可以被更廣泛高效的使用， 看下面的例子。
<script> function showOptions(){ var someNodeList = $('lstEmployees').getElementsByTagName('option'); var nodes = $A(someNodeList); nodes.each(function(node){ alert(node.nodeName + ': ' + node.innerHTML); }); } </script> <select id="lstEmployees" size="10" > <option value="5">Buchanan, Steven</option> <option value="8">Callahan, Laura</option> <option value="1">Davolio, Nancy</option> </select> <input type="button" value="Show the options" onclick="showOptions();" >
1.3.4. 使用 $H() 方法
$H() 方法把對象轉化成可枚舉的貌似聯合數組 Hash 對象。
<script> function testHash() { //let's create the object var a = { first: 10, second: 20, third: 30 }; //now transform it into a hash var h = $H(a); alert(h.toQueryString()); //displays: first=10&second=20&third=30 } </script>
1.3.5. 使用 $R() 方法
$R() 方法是 new ObjectRange(lowerBound, upperBound, excludeBounds) 的一個簡單快捷的使用方式。
ObjectRange 類文檔里面有完整的解釋。 同時，我們來看看一個簡單的例子， 來演示通過 each 方法遍歷的用法。 那個方法的更多解釋在 Enumerable 對象文檔里面。
<script> function demoDollar_R(){ var range = $R(10, 20, false); range.each(function(value, index){ alert(value); }); } </script> <input type="button" value="Sample Count" onclick="demoDollar_R();" >
1.3.6. 使用 Try.these() 方法
Try.these() 方法使得實現當你想調用不同的方法直到其中的一個成功正常的這種需求變得非常容易， 他把一系列的方法作為參數并且按順序的一個一個的執行這些方法直到其中的一個成功執行，返回成功執行的那個方法的返回值。
在下面的例子中， xmlNode.text 在一些瀏覽器中好用，但是 xmlNode.textContent 在另一些瀏覽器中正常工作。 使用 Try.these() 方法我們可以得到正常工作的那個方法的返回值。
<script> function getXmlNodeValue(xmlNode){ return Try.these( function() {return xmlNode.text;}, function() {return xmlNode.textContent;) ); } </script>
1.4. Ajax 對象
上面提到的共通方法非常好，但是面對它吧，它們不是最高級的那類東西。它們是嗎？你很可能自己編寫了這些甚至在你的腳本里面有類似功能的方法。但是這些方法只是冰山一角。
我很肯定你對prototype.js感興趣的原因很可能是由于它的AJAX能力。所以讓我們解釋當你需要完成AJAX邏輯的時候，這個包如何讓它更容易。
Ajax 對象是一個預定義對象，由這個包創建，為了封裝和簡化編寫 AJAX 功能涉及的狡猾的代碼。 這個對象包含一系列的封裝AJAX邏輯的類。我們來看看它們的一些。
1.4.1. 使用 Ajax.Request 類
如果你不使用任何的幫助程序包，你很可能編寫了整個大量的代碼來創建 XMLHttpRequest 對象并且異步的跟蹤它的進程， 然后解析出響應 然后處理它。當你不需要支持多于一種類型的瀏覽器時你會感到非常的幸運。
為了支持 AJAX 功能。這個包定義了 Ajax.Request 類。
假如你有一個應用程序可以通過url http://www.wnetw.net/demoapp/get_sales?empID=1234&year=1998 與服務器通信。它返回下面這樣的XML 響應。
<?xml version="1.0" encoding="utf-8" ?> <ajax-response> <response type="object" id="productDetails"> <monthly-sales> <employee-sales> <employee-id>1234</employee-id> <year-month>1998-01</year-month> <sales>$8,115.36</sales> </employee-sales> <employee-sales> <employee-id>1234</employee-id> <year-month>1998-02</year-month> <sales>$11,147.51</sales> </employee-sales> </monthly-sales> </response> </ajax-response>
用 Ajax.Request 對象和服務器通信并且得到這段XML是非常簡單的。下面的例子演示了它是如何完成的。
<script> function searchSales() { var empID = $F('lstEmployees'); var y = $F('lstYears'); var url = 'http://www.wnetw.net/demoapp/get_sales'; var pars = 'empID=' + empID + '&year=' + y;
var myAjax = new Ajax.Request( url, {method: 'get', parameters: pars, onComplete: showResponse} ); } function showResponse(originalRequest) { //put returned XML in the textarea $('result').value = originalRequest.responseText; } </script> <select id="lstEmployees" size="10" onchange="searchSales()"> <option value="5">Buchanan, Steven</option> <option value="8">Callahan, Laura</option> <option value="1">Davolio, Nancy</option> </select> <select id="lstYears" size="3" onchange="searchSales()"> <option selected="selected" value="1996">1996</option> <option value="1997">1997</option> <option value="1998">1998</option> </select> <br><textarea id=result cols=60 rows=10 ></textarea>
你看到傳入 Ajax.Request 構造方法的第二個對象了嗎？ 參數 {method: 'get', parameters: pars, onComplete: showResponse} 表示一個匿名對象的真實寫法。他表示你傳入的這個對象有一個名為 method 值為 'get'的屬性， 另一個屬性名為 parameters 包含HTTP請求的查詢字符串，和一個 onComplete 屬性/方法包含函數 showResponse 。
還有一些其它的屬性可以在這個對象里面定義和設置，如 asynchronous ，可以為 true 或 false 來決定AJAX對服務器的調用是否是異步的（默認值是 true ）。
這個參數定義AJAX調用的選項。在我們的例子中，在第一個參數通過HTTP GET命令請求那個url，傳入了變量 pars 包含的查詢字符串， Ajax.Request 對象在它完成接收響應的時候將調用 showResponse 方法。
也許你知道， XMLHttpRequest 在HTTP請求期間將報告進度情況。這個進度被描述為四個不同階段： Loading , Loaded , Interactive , 或 Complete 。你可以使 Ajax.Request 對象在任何階段調用自定義方法 ， Complete 是最常用的一個。想調用自定義的方法只需要簡單的在請求的選項參數中的名為 onXXXXX 屬性/方法中提供自定義的方法對象。 就像我們例子中的 onComplete 。你傳入的方法將會被用一個參數調用，這個參數是 XMLHttpRequest 對象自己。你將會用這個對象去得到返回的數據并且或許檢查包含有在這次調用中的HTTP結果代碼的 status 屬性。
還有另外兩個有用的選項用來處理結果。我們可以在 onSuccess 選項處傳入一個方法，當AJAX無誤的執行完后調用， 相反的，也可以在 onFailure 選項處傳入一個方法，當服務器端出現錯誤時調用。正如 onXXXXX 選項傳入的方法一樣，這兩個在被調用的時候也傳入一個帶有AJAX請求的 XMLHttpRequest對象。
我們的例子沒有用任何有趣的方式處理這個 XML響應， 我們只是把這段XML放進了一個文本域里面。對這個響應的一個典型的應用很可能就是找到其中的想要的信息，然后更新頁面中的某些元素， 或者甚至可能做某些XSLT轉換而在頁面中產生一些HTML。
更完全的解釋，請參照 Ajax.Request 參考 和 Ajax選項參考 。
1.4.2. 使用 Ajax.Updater 類
如果你的服務器的另一端返回的信息已經是HTML了，那么使用這個程序包中 Ajax.Updater 類將使你的生活變得更加得容易。用它你只需提供哪一個元素需要被AJAX請求返回的HTML填充就可以了，例子比我寫說明的更清楚。
<script> function getHTML() { var url = 'http://www.wnetw.net/demoapp/getSomeHTML'; var pars = 'someParameter=ABC';
var myAjax = new Ajax.Updater('placeholder', url, {method: 'get', parameters: pars}); } </script> <input type=button value=GetHtml onclick="getHTML()"> <div id="placeholder"></div>
你可以看到，這段代碼比前面的例子更加簡潔，不包括 onComplete 方法，但是在構造方法中傳入了一個元素id。 我們來稍稍修改一下代碼來描述如何在客戶端處理服務器段錯誤成為可能。
我們將加入更多的選項， 指定處理錯誤的一個方法。這個是用 onFailure 選項來完成的。
我們也指定了一個 placeholder 只有在成功請求之后才會被填充。為了完成這個目的我們修改了第一個參數從一個簡單的元素id到一個帶有兩個屬性的對象， success (一切OK的時候被用到) 和 failure (有地方出問題的時候被用到) 在下面的例子中沒有用到 failure 屬性，而僅僅在 onFailure 處使用了 reportError 方法。
<script> function getHTML() { var url = 'http://www.wnetw.net/demoapp/getSomeHTML'; var pars = 'someParameter=ABC';
var myAjax = new Ajax.Updater( {success: 'placeholder'}, url, {method: 'get', parameters: pars, onFailure: reportError}); } function reportError(request) { alert('Sorry. There was an error.'); } </script> <input type=button value=GetHtml onclick="getHTML()"> <div id="placeholder"></div>
如果你的服務器邏輯是返回JavaScript 代碼而不是單純的 HTML 標記， Ajax.Updater 對象可以執行那段JavaScript代碼。為了使這個對象對待響應為JavaScript，你只需在最后參數的對象構造方法中簡單加入 evalScripts: true 屬性。
更完全的解釋，請參照 Ajax.Updater 參考 和 Ajax選項參考 。
2.1. JavaScript 類的擴展
prototype.js 包中加入功能的一種途徑就是擴展已有的JavaScript 類。
2.2. 對 Object 類的擴展
Table 2.1. Object 類的擴展
| 方法 |
類別 |
參數 |
描述 |
| extend(destination, source) |
static |
destination : 任何對象, source : 任何對象 |
用從 source 到 destination 復制所有屬性和方法的方式 來提供一種繼承機制。 |
| extend(object) |
instance |
任何對象 |
用從傳入的 object 中復制所有屬性和方法的方式 來提供一種繼承機制。 |
2.3. 對 Number 類的擴展
Table 2.2. Number 類的擴展
| 方法 |
類別 |
參數 |
描述 |
| toColorPart() |
instance |
bgcolor="#FFFFFF"
(none) |
返回數字的十六進制描述， 當在HTML中轉換為RGB顏色組件到HTML中使用的顏色。 |
2.4. 對 Function 類的擴展
Table 2.3. 對 Function 類的擴展
| 方法 |
類別 |
參數 |
描述 |
| bind(object) |
instance |
object : 擁有這個方法的對象 |
返回預先綁定在擁有該函數(=方法)的對象上的函數實例， 返回的方法將和原來的方法具有相同的參數。 |
| bindAsEventListener(object) |
instance |
object : 擁有這個方法的對象 |
返回預先綁定在擁有該函數(=方法)的對象上的函數實例， 返回的方法將把當前的事件對象作為它的參數。 |
讓我們看看這些擴展的具體例子。
<input type=checkbox id=myChk value=1> Test? <script> //declaring the class var CheckboxWatcher = Class.create(); //defining the rest of the class implmentation CheckboxWatcher.prototype = { initialize: function(chkBox, message) { this.chkBox = $(chkBox); this.message = message; //assigning our method to the event
this.chkBox.onclick = this.showMessage.bindAsEventListener(this); }, showMessage: function(evt) { alert(this.message + ' (' + evt.type + ')'); } }; var watcher = new CheckboxWatcher('myChk', 'Changed'); </script>
2.5. 對 String 類的擴展
Table 2.4. String 類的擴展
| 方法 |
類別 |
參數 |
描述 |
| stripTags() |
instance |
(none) |
返回一個把所有的HTML或XML標記都移除的字符串。 |
| escapeHTML() |
instance |
(none) |
返回一個把所有的HTML標記回避掉的字符串。 |
| unescapeHTML() |
instance |
(none) |
和 escapeHTML() 相反。 |
2.6. 對 document DOM 對象的擴展
Table 2.5. document DOM 對象的擴展
| 方法 |
類別 |
參數 |
描述 |
| getElementsByClassName(className) |
instance |
className : 關聯在元素上的CSS類名 |
返回給定的具有相同的CSS類名的所有元素。 |
2.7. 對 Event 對象的擴展
Table 2.6. Event 對象的擴展
| 屬性 |
類型 |
描述 |
| KEY_BACKSPACE |
Number |
8: 常量，退格(Backspace)鍵的代碼。 |
| KEY_TAB |
Number |
9: 常量，Tab鍵的代碼。 |
| KEY_RETURN |
Number |
13: 常量，回車鍵的代碼。 |
| KEY_ESC |
Number |
27: 常量， Esc鍵的代碼。 |
| KEY_LEFT |
Number |
37: 常量，左箭頭鍵的代碼。 |
| KEY_UP |
Number |
38: 常量，上箭頭鍵的代碼。 |
| KEY_RIGHT |
Number |
39: 常量，右箭頭鍵的代碼。 |
| KEY_DOWN |
Number |
40: 常量，下箭頭鍵的代碼。 |
| KEY_DELETE |
Number |
46: 常量，刪除(Delete)鍵的代碼。 |
| observers: |
Array |
緩存的觀察者的列表，這個對象內部具體實現的一部分。 |
Table 2.7. Event 對象的擴展
| 方法 |
類別 |
參數 |
描述 |
| element(event) |
static |
event : 事件對象 |
返回引發這個事件的元素。 |
| isLeftClick(event) |
static |
event : 事件對象 |
如果鼠標左鍵單擊返回true。 |
| pointerX(event) |
static |
event : 事件對象 |
返回在頁面上x坐標。 |
| pointerY(event) |
static |
event : 事件對象 |
返回在頁面上y坐標。 |
| stop(event) |
static |
event : 事件對象 |
用這個方法來中止事件的默認行為來使事件的傳播停止。 |
| findElement(event, tagName) |
static |
event : 事件對象, tagName : 指定標記的名字 |
向 DOM 樹的上位查找，找到第一個給定標記名稱的元素， 從這個元素開始觸發事件。 |
| observe(element, name, observer, useCapture) |
static |
element : 對象或者對象id, name : 事件名 (如 'click', 'load', etc), observer : 處理這個事件的方法, useCapture : 如果true, 在捕捉到事件的階段處理事件 那么如果 false在 bubbling 階段處理。 |
加入一個處理事件的方法。 |
| stopObserving(element, name, observer, useCapture) |
static |
element : 對象或者對象id, name : 事件名 (如 'click', 'load', etc), observer : 處理這個事件的方法, useCapture : 如果true, 在捕捉到事件的階段處理事件 那么如果 false在 bubbling 階段處理。 |
刪除一個處理實踐的方法。 |
| _observeAndCache( element, name, observer, useCapture) |
static |
|
私有方法，不用管它。 |
| unloadCache() |
static |
(none) |
私有方法，不用管它。清除內存中的多有觀察著緩存。 |
讓我們看看怎樣用這個對象加入處理 window 對象的 load 事件的處理方法。
<script>
Event.observe(window, 'load', showMessage, false); function showMessage() { alert('Page loaded.'); } </script>
另一個這個程序包幫助你的地方就是提供許多既支持面向對象設計理念又有共通功能的許多對象。
2.9. PeriodicalExecuter 對象
這個對象提供一定間隔時間上重復調用一個方法的邏輯。
Table 2.8. PeriodicalExecuter 對象
| 方法 |
類別 |
參數 |
描述 |
| [ctor](callback, interval) |
constructor |
callback : 沒有參數的方法, interval : 秒數 |
創建這個對象的實例將會重復調用給定的方法。 |
Table 2.9. PeriodicalExecuter 對象
| 屬性 |
類型 |
描述 |
| callback |
Function() |
被調用的方法，該方法不會被傳入參數。 |
| frequency |
Number |
以秒為單位的間隔。 |
| currentlyExecuting |
Boolean |
表示這個方法是否正在執行。 |
2.10. Prototype 對象
Prototype 沒有太重要的作用，只是聲明了該程序包的版本 。
Table 2.10. The Prototype object
| 屬性 |
類型 |
描述 |
| Version |
String |
包的版本。 |
| emptyFunction |
Function() |
空方法對象。 |
2.11. Class 對象
在這個程序包中 Class 對象在聲明其他的類時候被用到 。用這個對象聲明類使得新類支持 initialize() 方法，他起構造方法的作用。
看下面的例子
//declaring the class
var MySampleClass = Class.create(); //defining the rest of the class implmentation MySampleClass.prototype = { initialize: function(message) { this.message = message; }, showMessage: function(ajaxResponse) { alert(this.message); } }; //now, let's instantiate and use one object var myTalker = new MySampleClass('hi there.'); myTalker.showMessage(); //displays alert
Table 2.11. Class 對象
| 方法 |
類別 |
參數 |
描述 |
| create(*) |
instance |
(any) |
定義新類的構造方法。 |
2.12. Ajax 對象
這個對象被用作其他提供AJAX功能的類的根對象。
Table 2.12. Ajax 對象
| 方法 |
類別 |
參數 |
描述 |
| getTransport() |
instance |
(none) |
返回新的 XMLHttpRequest 對象。 |
2.13. Ajax.Base 類
這個類是其他在Ajax對象中定義的類的基類。
Table 2.13. Ajax.Base 類
| 方法 |
類別 |
參數 |
描述 |
| setOptions(options) |
instance |
options : AJAX 選項 |
設定AJAX操作想要的選項。 |
| responseIsSuccess() |
instance |
(none) |
返回 true 如果AJAX操作成功,否則為 false 。 |
| responseIsFailure() |
instance |
(none) |
與 responseIsSuccess() 相反。 |
2.14. Ajax.Request 類
繼承自 Ajax.Base
封裝 AJAX 操作
Table 2.14. Ajax.Request 類
| 屬性 |
類型 |
類別 |
描述 |
| Events |
Array |
static |
在AJAX操作中所有可能報告的事件/狀態的列表。這個列表包括: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', 和 'Complete' 。 |
| transport |
XMLHttpRequest |
instance |
攜帶AJAX操作的 XMLHttpRequest 對象。 |
Table 2.15. Ajax.Request 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](url, options) |
constructor |
url : 請求的url, options : AJAX 選項 |
創建這個對象的一個實例，它將在給定的選項下請求url。 重要： 如果選擇的url受到瀏覽器的安全設置，他會一點作用也不起。 很多情況下，瀏覽器不會請求與當前頁面不同主機(域名)的url。 你最好只使用本地url來避免限制用戶配置他們的瀏覽器(謝謝Clay) |
| request(url) |
instance |
url : AJAX 請求的url |
這個方法通常不會被外部調用。已經在構造方法中調用了。 |
| setRequestHeaders() |
instance |
(none) |
這個方法通常不會被外部調用。 被這個對象自己調用來配置在HTTP請求要發送的HTTP報頭。 |
| onStateChange() |
instance |
(none) |
這個方法通常不會被外部調用。 當AJAX請求狀態改變的時候被這個對象自己調用。 |
| respondToReadyState(readyState) |
instance |
readyState : 狀態數字 (1 到 4) |
這個方法通常不會被外部調用。 當AJAX請求狀態改變的時候被這個對象自己調用。 |
2.15. options 參數對象
AJAX操作中一個重要的部分就是 options 參數。 本質上沒有options類。任何對象都可以被傳入，只要帶有需要的屬性。通常會只為了AJAX調用創建匿名類。
Table 2.16. options 參數對象
| 屬性 |
類型 |
Default |
描述 |
| method |
Array |
'post' |
HTTP 請求方式。 |
| parameters |
String |
'' |
在HTTP請求中傳入的url格式的值列表。 |
| asynchronous |
Boolean |
true |
指定是否做異步 AJAX 請求。 |
| postBody |
String |
undefined |
在HTTP POST的情況下，傳入請求體中的內容。 |
| requestHeaders |
Array |
undefined |
和請求一起被傳入的HTTP頭部列表， 這個列表必須含有偶數個項目， 任何奇數項目是自定義的頭部的名稱， 接下來的偶數項目使這個頭部項目的字符串值。 例子: ['my-header1', 'this is the value', 'my-other-header', 'another value'] |
| onXXXXXXXX |
Function(XMLHttpRequest) |
undefined |
在AJAX請求中，當相應的事件/狀態形成的時候調用的自定義方法。 例如 var myOpts = {onComplete: showResponse, onLoaded: registerLoaded}; . 這個方法將被傳入一個參數， 這個參數是攜帶AJAX操作的 XMLHttpRequest 對象。 |
| onSuccess |
Function(XMLHttpRequest) |
undefined |
當AJAX請求成功完成的時候調用的自定義方法。 這個方法將被傳入一個參數， 這個參數是攜帶AJAX操作的 XMLHttpRequest 對象。 |
| onFailure |
Function(XMLHttpRequest) |
undefined |
當AJAX請求完成但出現錯誤的時候調用的自定義方法。 這個方法將被傳入一個參數， 這個參數是攜帶AJAX操作的 XMLHttpRequest 對象。 |
| insertion |
Function(Object, String) |
null |
為了把返回的文本注入到一個元素中而執行的方法。 這個方法將被傳入兩個參數，要被更新的對象并且只應用于 Ajax.Updater 的響應文本 。 |
| evalScripts |
Boolean |
undefined, false |
決定當響應到達的時候是否執行其中的腳本塊，只在 Ajax.Updater 對象中應用。 |
| decay |
Number |
undefined, 1 |
決定當最后一次響應和前一次響應相同時在 Ajax.PeriodicalUpdater 對象中的減漫訪問的次數， 例如，如果設為2，后來的刷新和之前的結果一樣， 這個對象將等待2個設定的時間間隔進行下一次刷新， 如果又一次一樣， 那么將等待4次，等等。 不設定這個只，或者設置為1，將避免訪問頻率變慢。 |
2.16. Ajax.Updater 類
繼承自 Ajax.Request
當請求的url返回一段HTML而你想把它直接放置到頁面中一個特定的元素的時候被用到。 如果url的返回 <script> 的塊并且想在接收到時就執行它的時候也可以使用該對象。含有腳本的時候使用 evalScripts 選項。
Table 2.17. Ajax.Updater 類
| 屬性 |
類型 |
類別 |
描述 |
| ScriptFragment |
String |
static |
可以判斷是否為腳本的正則表達式。 |
| containers |
Object |
instance |
這個對象包含兩個屬性:AJAX請求成功執行的時候用到 containers.success , 否則的話用到 containers.failure 。 |
Table 2.18. Ajax.Updater 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](container, url, options) |
constructor |
container :可以是元素的id, 也可以是元素自己, 或者可以是帶有2個屬性的對象 - object.success AJAX請求成功的時候用到的元素(或者id) 否則用到 object.failure 中設定的元素(或id) ,url : 請求的url, options : AJAX 選項 |
創建一個用給定的選項請求給定的url的一個實例。 |
| updateContent() |
instance |
(none) |
這個方法通常不會被外部調用。 當響應到達的時候，被這個對象自己調用。 它會用HTML更新適當的元素或者調用在 insertion 選項中傳入的方法-這個方法將被傳入兩個參數， 被更新的元素和響應文本。 |
2.17. Ajax.PeriodicalUpdater 類
繼承自 Ajax.Base
這個類重復生成并使用 Ajax.Updater 對象來刷新頁面中的一個元素。或者執行 Ajax.Updater 可以執行的其它任務。更多信息參照 Ajax.Updater 參考 。
Table 2.19. Ajax.PeriodicalUpdater 類
| 屬性 |
類型 |
類別 |
描述 |
| container |
Object |
instance |
這個值將直接傳入 Ajax.Updater 的構造方法。 |
| url |
String |
instance |
這個值將直接傳入 Ajax.Updater 的構造方法。 |
| frequency |
Number |
instance |
兩次刷新之間的間隔 (不是頻率) ，以秒為單位。 默認2秒。 This 當調用 Ajax.Updater 對象的時候，這個數將和當前的 decay 相乘。 |
| decay |
Number |
instance |
重負執行任務的時候保持的衰敗水平。 |
| updater |
Ajax.Updater |
instance |
最后一次使用的 Ajax.Updater 對象 |
| timer |
Object |
instance |
通知對象該下一次更新時用到的JavaScript 計時器。 |
Table 2.20. Ajax.PeriodicalUpdater 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](container, url, options) |
constructor |
container :可以是元素的id, 也可以是元素自己, 或者可以是帶有2個屬性的對象 - object.success AJAX請求成功的時候用到的元素(或者id) 否則用到 object.failure 中設定的元素(或id) ,url : 請求的url, options : AJAX 選項 |
創建一個用給定的選項請求給定的url的一個實例。 |
| start() |
instance |
(none) |
這個方法通常不會被外部調用。 對象為了開始周期性執行任務的時候調用的方法。 |
| stop() |
instance |
(none) |
這個方法通常不會被外部調用。 對象為了停止周期性執行任務的時候調用的方法。 |
| updateComplete() |
instance |
(none) |
這個方法通常不會被外部調用。 被當前的 Ajax.Updater 使用，當一次請求結束的時候，它被用作計劃下一次請求。 |
| onTimerEvent() |
instance |
(none) |
這個方法通常不會被外部調用。當到下一次更新時被內部調用。 |
2.18. Element 對象
這個對象提供在操作DOM中元素時使用的功能性方法。
Table 2.21. Element 對象
| 方法 |
類別 |
參數 |
描述 |
| toggle(elem1 [, elem2 [, elem3 [...]]]) |
constructor |
elemN : 元素對象或id |
切換每一個傳入元素的可視性。 |
| hide(elem1 [, elem2 [, elem3 [...]]]) |
instance |
elemN : 元素對象或id |
用設定它的 style.display 為 'none' 來隱藏每個傳入的元素。 |
| show(elem1 [, elem2 [, Slem3 [...]]]) |
instance |
elemN : 元素對象或id |
用設定它的 style.display 為 '' 來顯示每個傳入的元素。 |
| remove(element) |
instance |
element : 元素對象或id |
從document對象中刪除指定的元素。 |
| getHeight(element) |
instance |
element : 元素對象或id |
返回元素的 offsetHeight 。 |
| addClassName( element, className) |
instance |
element : 元素對象或id, className : CSS類名 |
向元素的類名中加入給定的類名。 |
| hasClassName( element, className) |
instance |
element : 元素對象或id, className : CSS類名 |
返回 true 如果元素的類名中含有給定的類名 |
| removeClassName( element, className) |
instance |
element : 元素對象或id, className : CSS類名 |
從元素的類名中刪除給定的類名。 |
| cleanWhitespace( element ) |
instance |
element : 元素對象或id |
刪除該元素的所有只含有空格的子節點。 |
2.19. Abstract 對象
這個對象是這個程序包中其他類的根。它沒有任何屬性和方法。在這個對象中定義的類可以被視為傳統的抽象類。
2.20. Abstract.Insertion 類
這個類被用作其他提供動態內容插入功能的類的基類，它像一個抽象類一樣被使用。
Table 2.22. Abstract.Insertion 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, content) |
constructor |
element : 元素對象或id, content : 被插入的HTML |
創建一個可以幫助插入動態內容的對象。 |
Table 2.23. Abstract.Insertion 類
| 屬性 |
類型 |
類別 |
描述 |
| adjacency |
String |
static, parameter |
這個參數指定相對于給定元素，內容將被放置的位置。 可能的值是: 'beforeBegin' , 'afterBegin' , 'beforeEnd' , 和 'afterEnd' . |
| element |
Object |
instance |
與插入物做參照元素對象。 |
| content |
String |
instance |
被插入的 HTML 。 |
2.21. Insertion 對象
這個對象是其他類似功能的根。它沒有任何屬性和方法。在這個對象中定義的類仍然可以被視為傳統的抽象類。
2.22. Insertion.Before 類
繼承自 Abstract.Insertion
在給定元素開始標記的前面插入HTML。
Table 2.24. Insertion.Before 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, content) |
constructor |
element : 元素對象或id, content : 被插入的HTML |
繼承自 Abstract.Insertion . 創建一個可以幫助插入動態內容的對象。 |
下面的代碼
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script>
new Insertion.Before('person', 'Chief '); </script>
將把 HTML 變為
<br>Hello,
Chief <span id="person" style="color:red;">Wiggum. How's it going?</span>
2.23. Insertion.Top 類
繼承自 Abstract.Insertion
在給定元素第一個子節點位置插入 HTML。內容將位于元素的開始標記的緊后面。
Table 2.25. Insertion.Top 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, content) |
constructor |
element : 元素對象或id, content : 被插入的HTML |
繼承自 Abstract.Insertion . 創建一個可以幫助插入動態內容的對象。 |
下面的代碼
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script>
new Insertion.Top('person', 'Mr. '); </script>
將把 HTML 變為
<br>Hello, <span id="person" style="color:red;">
Mr. Wiggum. How's it going?</span>
2.24. Insertion.Bottom 類
繼承自 Abstract.Insertion
在給定元素最后一個子節點位置插入 HTML。內容將位于元素的結束標記的緊前面。
Table 2.26. Insertion.Bottom 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, content) |
constructor |
element : 元素對象或id, content : 被插入的HTML |
繼承自 Abstract.Insertion . 創建一個可以幫助插入動態內容的對象。 |
下面的代碼
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script>
new Insertion.Bottom('person', " What's up?"); </script>
將把 HTML 變為
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?
What's up? </span>
2.25. Insertion.After 類
繼承自 Abstract.Insertion
在給定元素結束標記的后面插入HTML。
Table 2.27. Insertion.After 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, content) |
constructor |
element : 元素對象或id, content : 被插入的HTML |
繼承自 Abstract.Insertion . 創建一個可以幫助插入動態內容的對象。 |
下面的代碼
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script>
new Insertion.After('person', ' Are you there?'); </script>
將把 HTML 變為
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>
Are you there?
2.26. Field 對象
這個對象提供操作表單中的輸入項目的功能性方法。
Table 2.28. Field 對象
| 方法 |
類別 |
參數 |
描述 |
| clear(field1 [, field2 [, field3 [...]]]) |
instance |
fieldN : 元素對象或id |
清除傳入表單中項目元素的值。 |
| present(field1 [, field2 [, field3 [...]]]) |
instance |
fieldN : 元素對象或id |
只有在所有的表單項目都不為空時返回 true 。 |
| focus(field) |
instance |
fieldN : 元素對象或id |
移動焦點到給定的表單項目。 |
| select(field) |
instance |
fieldN : 元素對象或id |
選擇支持項目值選擇的表單項目的值。 |
| activate(field) |
instance |
fieldN : 元素對象或id |
移動焦點并且選擇支持項目值選擇的表單項目的值。 |
2.27. Form 對象
這個對象提供操作表單和他們的輸入項目的功能性方法。
Table 2.29. Form 對象
| 方法 |
類別 |
參數 |
描述 |
| serialize(form) |
instance |
form : 表單元素或id |
返回url參數格式的項目名和值的列表， 如 'field1=value1&field2=value2&field3=value3'。 |
| getElements(form) |
instance |
form : 表單元素或id |
返回包含所有在表單中輸入項目的 Array 對象。 |
| getInputs(form [, typeName [, name]]) |
instance |
form : 表單元素或id, typeName : 輸入項目的類型, name : 輸入項目的名稱 |
返回一個 Array 包含所有在表單中的 <input> 元素 。 另外， 這個列表可以對元素的類型或名字屬性進行過濾。 |
| disable(form) |
instance |
form : 表單元素或id |
使表單中的所有輸入項目無效。 |
| enable(form) |
instance |
form : 表單元素或id |
使表單中的所有輸入項目有效。 |
| focusFirstElement(form) |
instance |
form : 表單元素或id |
激活第一個表單中可視的，有效的輸入項目。 |
| reset(form) |
instance |
form : 表單元素或id |
重置表單。和調用表單對象的 reset() 方法一樣。 |
2.28. Form.Element 對象
這個對象提供表單對象中的可視和非可視元素的功能性方法。
Table 2.30. Form.Element 對象
| 方法 |
類別 |
參數 |
描述 |
| serialize(element) |
instance |
element : 表單元素或id |
返回元素的 名稱=值 對, 如 'elementName=elementValue'。 |
| getValue(element) |
instance |
element : 表單元素或id |
返回元素的值。 |
2.29. Form.Element.Serializers 對象
這個對象提供了內部使用的用來協助解析出表單元素的當前值功能性方法。
Table 2.31. Form.Element.Serializers 對象
| 方法 |
類別 |
參數 |
描述 |
| inputSelector(element) |
instance |
element : 一個帶有checked屬性的表單元素或id， 如 radio 或 checkbox。 |
返回帶有元素名稱和值的 Array , 如 ['elementName', 'elementValue'] |
| textarea(element) |
instance |
element : 一個帶有value屬性的表單元素或id， 如 textbox, button 或 password 項目。 |
返回帶有元素名稱和值的 Array , 如 ['elementName', 'elementValue'] |
| select(element) |
instance |
element : 一個 <select> 元素對象或id。 |
返回帶有元素名稱和所有被選擇的選項的值或文本的 Array , 如 ['elementName', 'selOpt1 selOpt4 selOpt9'] |
2.30. Abstract.TimedObserver 類
這個類是用于其它監聽一個元素的值(或者任何類中涉及的屬性)變化的類的基類，這個類像一個抽象類一樣被使用。
子類可以被創建來監聽如輸入項目值，或style屬性，或表格的行數，或者其他任何對跟蹤變化相關的東西。
子類必須實現這個方法來決定什么才是被監聽的元素的當前值。
Table 2.32. Abstract.TimedObserver 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, frequency, callback) |
constructor |
element : 元素對象或id, frequency : 以秒為單位的間隔, callback : 當元素改變的時候調用的方法。 |
創建一個監聽元素的對象。 |
| registerCallback() |
instance |
(none) |
這個方法通常不會被外部調用。 被這個對象自己調用來開始監聽那個元素。 |
| onTimerEvent() |
instance |
(none) |
這個方法通常不會被外部調用。 被這個對象自己調用來周期性的檢查那個元素。 |
Table 2.33. Abstract.TimedObserver 類
| 屬性 |
類型 |
描述 |
| element |
Object |
被監聽的元素對象。 |
| frequency |
Number |
每次檢查中的以秒為單位的時間間隔。 |
| callback |
Function(Object, String) |
只要元素改變這個方法就會被調用。 會接收到元素對象和新值作為參數。 |
| lastValue |
String |
元素被核實的最后一個值。 |
2.31. Form.Element.Observer 類
繼承自 Abstract.TimedObserver
Abstract.TimedObserver 的一個實現類用來監聽表單輸入項目的值的變化。當你想監聽一個沒有帶報告值變化事件的元素的時候使用這個類。否則的話使用 Form.Element.EventObserver 類代替。
Table 2.34. Form.Element.Observer 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, frequency, callback) |
constructor |
element : 元素對象或id, frequency : 以秒為單位的間隔, callback : 當元素改變的時候調用的方法。 |
繼承自 Abstract.TimedObserver . 創建一個監聽元素值屬性的對象。 |
| getValue() |
instance |
(none) |
返回元素的值。 |
2.32. Form.Observer 類
繼承自 Abstract.TimedObserver
Abstract.TimedObserver 的一個實現類用來監聽表單中任何數據項的值的變化。當你想監聽一個沒有帶報告值變化事件的元素的時候使用這個類。 否則的話使用類 Form.EventObserver 代替。
Table 2.35. Form.Observer 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](form, frequency, callback) |
constructor |
form : 表單對象或id, |
繼承自 Abstract.TimedObserver . 創建一個監聽表單變化的對象。 |
| getValue() |
instance |
(none) |
返回所有表單數據的一系列值。 |
2.33. Abstract.EventObserver 類
這個類被用作其他一些類的基類，這些類具有在一個元素的值改變事件發生的時候執行一個回調方法這樣的功能。
類 Abstract.EventObserver 的多個對象可以綁定到一個元素上，不是一個幫其他的擦出了，而是按照他們付給元素的順序執行這些回調方法。
單選按鈕和復選框的觸發事件是 onclick ，而文本框和下拉列表框/下拉列表框的是 onchange 。
子類必須實現這個方法來決定什么才是被監聽的元素的當前值。
Table 2.36. Abstract.EventObserver 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, callback) |
constructor |
element : 元素對象或id, callback : 當事件發生的時候調用的方法。 |
創建監聽元素的對象。 |
| registerCallback() |
instance |
(none) |
這個方法通常不會被外部調用。 被對象調用來把自己綁定到元素的事件上。 |
| registerFormCallbacks() |
instance |
(none) |
這個方法通常不會被外部調用。 被對象調用來把自己綁定到表單中的每一個數據項元素的事件上。 |
| onElementEvent() |
instance |
(none) |
這個方法通常不會被外部調用。 將被綁定到元素的事件上。 |
Table 2.37. Abstract.EventObserver 類
| 屬性 |
類型 |
描述 |
| element |
Object |
被監聽的元素對象。 |
| callback |
Function(Object, String) |
只要元素改變就調用的方法。會接收到元素對象和新值作為參數。 |
| lastValue |
String |
元素被核實的最后一個值。 |
2.34. Form.Element.EventObserver 類
繼承自 Abstract.EventObserver
Abstract.EventObserver 的一個實現類，它在監測到表單中數據項元素的值改變的相應事件時候執行一個回調方法。 如果元素沒有任何報告變化的事件，那么你可以使用 Form.Element.Observer 類代替。
Table 2.38. Form.Element.EventObserver 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](element, callback) |
constructor |
element : 元素對象或id, callback : 當事件發生的時候調用的方法。 |
繼承自 Abstract.EventObserver 。 創建一個監聽元素值屬性的對象。 |
| getValue() |
instance |
(none) |
返回元素的值。 |
2.35. Form.EventObserver 類
繼承自 Abstract.EventObserver
Abstract.EventObserver 的一個實現類，監聽表單對象中包含的任何對象的任何變化，用元素的事件檢測值的變化。如果元素沒有任何報告變化的事件， 那么你可以使用 Form.Observer 類代替。
Table 2.39. Form.Element.EventObserver 類
| 方法 |
類別 |
參數 |
描述 |
| [ctor](form, callback) |
constructor |
form : 元素對象或id, callback : 當表單中任何數據項改變的時候調用的方法 |
繼承自 Abstract.EventObserver 。 創建一個監聽元素值屬性的對象。 |
| getValue() |
instance |
(none) |
返回所有表單數據的一系列值。 |
2.36. Position 對象 (預備文檔)
這個對象提供許多和元素位置相關的方法。
Table 2.40. Position 對象 (預備文檔)
| 方法 |
類別 |
參數 |
描述 |
| prepare() |
instance |
(none) |
調整 deltaX 和 deltaY 屬性來協調在滾動位置中的變化。 記得在頁面滾動之后的任何調用的 withinIncludingScrolloffset 之前調用這個方法。 |
| realOffset(element) |
instance |
element : 對象或id |
返回這個元素的正確滾動偏差的 Array 對象， 包括所有影響元素的滾動偏差。結果數組類似 [total_scroll_left, total_scroll_top] |
| cumulativeOffset(element) |
instance |
element : 對象或id |
回這個元素的正確滾動偏差的 Array 對象， 包含任何被放置的父元素強加偏差。結果數組類似 [total_offset_left, total_offset_top] |
| within(element, x, y) |
instance |
element : 對象, x 和 y : 一個點的坐標 |
測試給定的點的坐標是否在給定的元素的外部矩形范圍之內。 |
| withinIncludingScrolloffsets(element, x, y) |
instance |
element : object, x and y: coordinates of a point |
|
| overlap(mode, element) |
instance |
mode : 'vertical' 或 'horizontal' , element : 對象 |
在調用這個方法之前需要調用 within() 。這個方法返回0.0到1.0之間的數字，來表示坐標在元素重疊的分數。 舉個例子，如果元素是一個邊長是100px的正方形的DIV，并且位于(300, 300), 然后 within(divSquare, 330, 330)； overlap('vertical', divSquare); 會返回 0.10，意思是那個點位于DIV頂部邊框以下 10% (30px) 的位置上。 |
| clone(source, target) |
instance |
source : 元素對象或 id, target : 元素對象或id |
改變目標元素的大小尺寸和位置與源元素的相同。 |