Get Involved
* java-net Project
* Request a Project
* Project Help Wanted Ads
* Publicize your Project
* Submit Content
* Site Help
Project tools
* Project home
* Announcements
* Discussion forums
* Mailing lists
* Documents & files
* CVS
* Issue tracker
Search
Advanced search
How do I...
* Get release notes for CollabNet 4.5.2?
* Get help?
prototype.js開發筆記
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://yoursever/app/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://yoursever/app/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://yourserver/app/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://yourserver/app/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選項參考 。
Chapter 2. prototype.js參考
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 (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.8. 在 prototype.js中定義的新對象和類
另一個這個程序包幫助你的地方就是提供許多既支持面向對象設計理念又有共通功能的許多對象。
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 改變目標元素的大小尺寸和位置與源元素的相同。
如果你發現錯誤，過失或信息不完全，或平淡無意義的東西，請 通知作者 ，作者會儘可能快的修正它，作者仍然在寫其他沒寫的類，來保持一致。 任何翻譯的過失，不足，詞不達意，表達含糊等請通知我，我會再加斟酌，找到合適的描述。
* java-net Project
* Request a Project
* Project Help Wanted Ads
* Publicize your Project
* Submit Content
* Site Help
Project tools
* Project home
* Announcements
* Discussion forums
* Mailing lists
* Documents & files
* CVS
* Issue tracker
Search
Advanced search
How do I...
* Get release notes for CollabNet 4.5.2?
* Get help?
prototype.js開發筆記
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://yoursever/app/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://yoursever/app/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://yourserver/app/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://yourserver/app/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選項參考 。
Chapter 2. prototype.js參考
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 (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.8. 在 prototype.js中定義的新對象和類
另一個這個程序包幫助你的地方就是提供許多既支持面向對象設計理念又有共通功能的許多對象。
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 改變目標元素的大小尺寸和位置與源元素的相同。
如果你發現錯誤，過失或信息不完全，或平淡無意義的東西，請 通知作者 ，作者會儘可能快的修正它，作者仍然在寫其他沒寫的類，來保持一致。 任何翻譯的過失，不足，詞不達意，表達含糊等請通知我，我會再加斟酌，找到合適的描述。