505
prototype開發者手冊
開發者手冊
對應版本1.4.0
其它版本English versionPDF (v1.4.0)Korean (v1.4.0)Italian (v1.4.0)Portuguese (v1.4.0)Hungarian (v1.4.0)Dutch (v1.4.0)Polish (v1.4.0)Japanese (v1.4.0)English (v1.3.1)Chinese (v1.3.1)Spanish (v1.3.1)French (v1.3.1)German (v1.3.1)Romanian (v1.3.1)Russian (v1.3.1)Other versions (volunteers needed)
看到一個很好的東西在國內沒有被很多人使用起來，實在是不爽，所以花了很大功夫把這個手冊翻譯成中文，由於這篇文章很長，所以，翻譯的工作量很大而且有些地方英文版也沒有說清楚，雖得查看源代碼，好在不是堅持做完了，大家鼓勵下啊！^o^
prototype.js是一個非常優雅的javascript基礎類庫，對javascript做了大量的擴展，而且很好的支持Ajax，國外有多個基於此類庫實現的效果庫，也做得很棒。
prototype.js不僅是一個有很大實用價值的js庫，而且有很高的學習價值，所以我強烈建議B/S開發人員和對JS開發感興趣的朋友去瀏覽一些它的源代碼，其中有很多的珠璣，你絕對會覺得讀它的源代碼是一種享受，當然要讀得懂，嗬嗬。
網上也有人寫過1.3版的源碼解讀，大家可以找來看看。不過1.4版做了很大的擴充，所以希望有朋友寫出1.4版的源碼解讀。
幾點說明：
prototype.js是什麼?
萬一你沒有使用過大名鼎鼎的prototype.js，那麼讓我來告訴你，是由寫的一個javascript類庫。這個構思奇妙，而且兼容標準的類庫，能幫助你輕鬆建立有高度互動的web2.0特性的富客戶端頁麵。
如果你最近嚐試使用它，你大概了解到文檔並不是作者的一個強項。和在我以前使用這個類庫的不少開發者一樣，一開始，我不得不一頭紮進閱讀prototype.js的源代碼和實驗它的功能中。我想，在我學習完它之後，把我學到的東西分享給大家是件不錯的事。
同時，在本文中，我也將提供一個關於這個類庫提供的objects,classes,functions,extensions這對東東的
在閱讀這個文檔時，熟悉Ruby的開發者將會注意到Ruby的一些內建類和本類庫擴展實現之間非常相似。
相關文章
一些實用的函數
這個類庫帶有很多預定義的對象和實用函數，這些東東的目的顯然是把你從一些重複的打字中解放出來 。
使用$()方法
$() 方法是在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 >
<p>This is a paragraph</p>
</div>
<div >
<p>This is another paragraph</p>
</div>
<input type="button" value=Test1 ><br>
<input type="button" value=Test2 ><br>
</BODY>
</HTML>
另外一個好處是，這個函數能傳入用string表示的對象ID，也可以傳入對象本身，這樣，在建立其它能傳兩種類型的參數的函數時非常有用。
使用$F()函數
$F()函數是另一個大收歡迎的“快捷鍵”，它能用於返回任何表單輸入控件的值，比如text box,drop-down list。這個方法也能用元素id或元素本身做為參數。
<script>
function test3()
{
alert( $F('userName') );
}
</script>
<input type="text" value="Joe Doe"><br>
<input type="button" value=Test3 ><br>
使用$A()函數
$A()函數能把它接收到的單個的參數轉換成一個Array對象。
這個方法，結合被本類庫擴展了的Array類，能方便的把任何的可枚舉列表轉換成或拷貝到一個Array對象。一個推薦的用法就是把DOM Node Lists轉換成一個普通的Array對象，從而更有效率的進行遍曆，請看下麵的例子。
<script>
function showOptions(){
var someNodeList = $('lstEmployees').getElementsByTagName('option');
var nodes = $A(someNodeList);
nodes.each(function(node){
alert(node.nodeName + ': ' + node.innerHTML);
});
}
</script>
<select 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" >
使用 $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>
使用$R()函數
$R()是new ObjectRange(lowBound,upperBound,excludeBounds)的縮寫。
跳到 類文檔可以看到一個關於此類的完整描述. 此時，我們還是先來看一個例子以展示這個縮寫能代替哪些方法吧。其它相關的一些知識可以在 對象文檔中找到。
<script>
function demoDollar_R(){
var range = $R(10, 20, false);
range.each(function(value, index){
alert(value);
});
}
</script>
<input type="button" value="Sample Count" >
使用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>
Ajax對象
上麵提到的共通方法非常好，但是麵對它吧，它們不是最高級的那類東西。它們是嗎？你很可能自己編寫了這些甚至在你的腳本裏麵有類似功能的方法。但是這些方法隻是冰山一角。
我很肯定你對prototype.js感興趣的原因很可能是由於它的AJAX能力。所以讓我們解釋當你需要完成AJAX邏輯的時候，這個包如何讓它更容易。
Ajax 對象是一個預定義對象，由這個包創建，為了封裝和簡化編寫 功能涉及的狡猾的代碼。 這個對象包含一係列的封裝AJAX邏輯的類。我們來看看其中幾個類。
使用Ajax.Request類
如果你不使用任何的幫助程序包，你很可能編寫了整個大量的代碼來創建XMLHttpRequest對象並且異步的跟蹤它的進程， 然後解析出響應 然後處理它。當你不需要支持多於一種類型的瀏覽器時你會感到非常的幸運。
為了支持 AJAX 功能。這個包定義了 Ajax.Request 類。
假如你有一個應用程序可以通過url https://yoursever/app/get_sales?empID=1234&year=1998與服務器通信。它返回下麵這樣的XML 響應。
<?xml version="1.0" encoding="utf-8" ?> <ajax-response> <response type="object" > <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 = 'https://yoursever/app/get_sales';
var pars = 'empID=' + empID + '&year=' + y;
你注意到傳入 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。
在1.4.0版本中，一種新的事件回傳外理被引入。如果你有一段代碼總是要為一個特殊的事件執行，而不管是哪個AJAX調用引發它，那麼你可以使用新的對象。
假設你想要在一個AJAX調用正在運行時，顯示一些提示效果，像一個不斷轉動的圖標之類的，你可以使用兩個全局事件Handler來做到，其中一個在第一個調用開始時顯示圖標，另一個在最後一個調用完成時隱藏圖標。看下麵的例子。
<script>
var myGlobalHandlers = {
onCreate: function(){
Element.show('systemWorking');
},
onComplete: function() {
if(Ajax.activeRequestCount == 0){
Element.hide('systemWorking');
}
}
};
Ajax.Responders.register(myGlobalHandlers);
</script>
<div id='systemWorking'><img src='spinner.gif'>Loading...</div>
使用Ajax.Updater類
如果你的服務器的另一端返回的信息已經是HTML了，那麼使用這個程序包中 Ajax.Updater 類將使你的生活變得更加得容易。用它你隻需提供哪一個元素需要被AJAX請求返回的HTML填充就可以了，例子比我寫說明的更清楚。
<script>
function getHTML()
{
var url = 'https://yourserver/app/getSomeHTML';
var pars = 'someParameter=ABC';
你可以看到，這段代碼比前麵的例子更加簡潔，不包括 onComplete 方法，但是在構造方法中傳入了一個元素id。 我們來稍稍修改一下代碼來描述如何在客戶端處理服務器段錯誤成為可能。
我們將加入更多的選項， 指定處理錯誤的一個方法。這個是用 onFailure 選項來完成的。我們也指定了一個 placeholder 隻有在成功請求之後才會被填充。為了完成這個目的我們修改了第一個參數從一個簡單的元素id到一個帶有兩個屬性的對象， success (一切OK的時候被用到) 和 failure (有地方出問題的時候被用到) 在下麵的例子中沒有用到failure屬性，而僅僅在 onFailure 處使用了 reportError 方法。
<script>
function getHTML()
{
var url = 'https://yourserver/app/getSomeHTML';
var pars = 'someParameter=ABC';
如果你的服務器邏輯是連同HTML 標記返回JavaScript 代碼， Ajax.Updater對象可以執行那段JavaScript代碼。為了使這個對象對待響應為JavaScript，你隻需在最後參數的對象構造方法中簡單加入evalScripts: true屬性。但是值得提醒的是，像這個選項名evalScripts暗示的，這些腳本會被執行，但是它們不會被加入到Page的腳本中。“有什麼區別？”，可能你會這樣問。我們假定請求地址返回的東東像這樣：
<script language="javascript" type="text/javascript">
function sayHi(){
alert('Hi');
}
</script>
<input type=button value="Click Me" >
如果你以前這樣嚐試過，你知道這些腳本不會如你所期望的那樣工作，原因是這段腳本會被執行，但像上麵這樣的腳本執行並不會創建一個名叫sayHi的函數，它什麼也不做。如果要創建一個函數，我們應當把代碼改成下麵這個樣子：
<script language="javascript" type="text/javascript">
為什麼我們在上麵的代碼中不使用var關鍵字來聲明這個變量呢（指sayHi ），因為那樣做創建出來的函數將隻是當前腳本塊的一個局部變量（至少在IE中是這樣）。不寫var關鍵字，創建出來的對象的作用域就是我們所期望的window。
枚舉... 噢!噢!
你知道，我們都是這樣來做循環的，建一個Array，用elements組織它們，再建一個循環結構（例如for,foreach,while)通過index數字來訪問每一個element，再用這個element做一些動作。
當你想到這時，你會發現幾乎每次寫循環代碼你都會遲早用到一個Array。那麼，如果Array對象能夠提供更多的功能給它們的迭代器使用不是很爽嗎？確實是這樣，事實上很多的編程語言都在它們的Array或其它類似的結構中（如Collections,Lists）提供一些這樣的功能。
現在好了，prototype.js了給我們一個 對象，它實現了很多和可迭代數據進行交互的竅門。和原有的JS對象相比prototype.js更上一層樓，它對Array 類s擴展了所有枚舉要用的函數。
循環, Ruby樣式的
在標準的javascript中，如果你想把一個array中的所有elements顯示出來，你可以像下麵代碼這樣寫得很好：
<script>
function showList(){
var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Meg'];
使用我們新的最好的朋友，prototype.js，我們可以把它生寫成這樣
function showList(){
var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Meg'];
你可能會想“非常奇怪的方式...相對舊的，這種語法太怪異了”。哦，在上麵的例子，確實什麼也沒有，在這個簡單得要死例子中，也沒有改變太多啊，盡管如此，請繼續讀下去。
在繼續下麵內容之前，你注意到那個被做為一個參數傳遞給each函數的函數？我們把它理解成迭代器函數。
Your arrays on steroids
就如我們上麵提到的，把你的Array中的elements當成相同的類型使用相同的屬性和函數是很通用(Common,不知該翻譯成通用還是庸俗)的。讓我們看看怎麼樣利用我們新的馬力強勁的Arrays的迭代功能吧。
依照標準找到一個element。
<script>
function findEmployeeById(emp_id){
var listBox = $('lstEmployees')
var options = listBox.getElementsByTagName('option');
options = $A(options);
var opt = options.find( function(employee){
return (employee.value == emp_id);
});
alert(opt.innerHTML); //displays the employee name
}
</script>
<select 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="Find Laura" >
現在我們再下一城，看看如何過濾一個Array中的元素，從每個元素中得到我們想要的成員。
<script>
function showLocalLinks(paragraph){
paragraph = $(paragraph);
var links = $A(paragraph.getElementsByTagName('a'));
//find links that do not start with 'http'
var localLinks = links.findAll( function(link){
var start = link.href.substring(0,4);
return start !='http';
});
//now the link texts
var texts = localLinks.pluck('innerHTML');
//get them in a single string
var result = texts.inspect();
alert(result);
}
</script>
<p >
This <a href="https://othersite.com/page.html">text</a> has
a <a href="#localAnchor">lot</a> of
<a href="#otherAnchor">links</a>. Some are
<a href="https://wherever.com/page.html">external</a>
and some are <a href="#someAnchor">local</a>
</p>
<input type=button value="Find Local Links" >
上麵的代碼僅僅是一點小小的實踐讓人愛上這種語法。請參看 和的所有函數
prototype.js參考
JavaScript類擴展
prototype.js 類庫實現強大功能的一種途徑是擴展已有的JavaScript 類。
對 Object的擴展
| Method | Kind | Arguments | Description |
|---|---|---|---|
| extend(destination, source) | static | destination: any object, source: any object | 提供一種通過拷貝所有源以象屬性和函數到目標函數實現繼承的方法 |
| inspect(targetObj) | static | targetObj: any object | 返回可讀性好關於目標對象的文字描述，如果對象實例沒有定義一個inspect函數，默認返回toString函數的值。 |
對Number的擴展
| Method | Kind | Arguments | Description |
|---|---|---|---|
| toColorPart() | instance | (none) | 返回數字的十六進製表示形式。在把一個RGB數字轉換成HTML表現形式時很有用。 |
| succ() | instance | (none) | 返回下一個數字，這個方法可用於迭代調用場景中。 |
| times(iterator) | instance | iterator: a function object conforming to Function(index) | Calls the iterator function repeatedly passing the current index in the index argument. 反複調用iterator函數並傳遞當前index到iterator的index參數。 |
下麵的例子用提示框顯示0-9。
<script>
function demoTimes(){
var n = 10;
n.times(function(index){
alert(index);
});
/***************************
* you could have also used:
* (10).times( .... );
***************************/
}
</script>
<input type=button value="Test Number.times()" >
對 Function擴展
| Method | Kind | Arguments | Description |
|---|---|---|---|
| bind(object) | instance | object: the object that owns the method | 返回function的實例，這個實例和源function的結構一樣，但是它已被綁定給了參數中提供的object，就是說，function中的this指針指向參數object。 |
| bindAsEventListener(object) | instance | object: the object that owns the method | 用法和上麵的bind一樣，區別在於用來綁定事件。 |
讓我們看看如何運用這些擴展。
<input type=checkbox id=myChk value=1> Test?
<script>
//declaring the class
var CheckboxWatcher = Class.create();
//defining the rest of the class implementation
CheckboxWatcher.prototype = {
initialize: function(chkBox, message) {
this.chkBox = $(chkBox);
this.message = message;
//assigning our method to the event
對String的擴展
| Method | Kind | Arguments | Description |
|---|---|---|---|
| stripTags() | instance | (none) | 返回一個把所有的HTML或XML標記都移除的字符串。 |
| stripScripts() | instance | (none) | 返回一個把所有的script都移除的字符串。 |
| escapeHTML() | instance | (none) | 返回一個把所有的HTML標記合適的轉義掉的字符串。 |
| unescapeHTML() | instance | (none) | escapeHTML()的反轉。 |
| extractScripts() | instance | (none) | 返回一個包含在string中找到的所有<script>的數組。 |
| evalScripts() | instance | (none) | 執行在string中找到的所有<script>。 |
| toQueryParams() | instance | (none) | 把querystring分割才一個用parameter name做index的聯合Array，更像一個hash。 |
| parseQuery() | instance | (none) | 和toQueryParams()一樣. |
| toArray() | instance | (none) | 把字符串轉換成字符數組. |
| camelize() | instance | (none) | 轉換一個以連字符連接的字符串成一個駱駝法樣式的字符串。比如，這個函數在寫代碼時，把它做為一個樣式工具使用是很有用的。 |
對 Array的擴展
因為array擴展於enumerable，所以所有enumberable對象的函數，array都是可以使用的，除此之外，下麵的這些也是已經實現了的。
| Method | Kind | Arguments | Description |
|---|---|---|---|
| clear() | instance | (none) | 清空。 |
| compact() | instance | (none) | 返回一個不包括源array中null或undefined元素的array,此方法不改變源array。 |
| first() | instance | (none) | 返回array的第一個對象。 |
| flatten() | instance | (none) | 通過遞歸組合array每個元素的子元素（如果該元素也是array)來返回一個“扁平的”一維的array。 |
| indexOf(value) | instance | value: what you are looking for. | 返回給出數字位置（從０算起）的元素，如果在該位置沒有找到對象，返回-1。 |
| inspect() | instance | (none) | 重載inspect(),返回更好格式的反映Array每個元素的字符描述。 |
| last() | instance | (none) | 返回最後一個元素。 |
| reverse([applyToSelf]) | instance | applyToSelf: indicates if the array itself should also be reversed. | 反轉Array中元素的順序，如果沒有給出參數，或參數為true，則源Array中元素的順序也反轉，否則源Array保持不變。 |
| shift() | instance | (none) | 返回Array的第一個元素並從Array中移除它，Array的Length-1。 |
| without(value1 [, value2 [, .. valueN]]) | instance | value1 ... valueN: values to be excluded if present in the array. | 返回一個把參數列表中包含的元素從源Array中排除的Array。 |
document DOM擴展
| Method | Kind | Arguments | Description |
|---|---|---|---|
| getElementsByClassName(className [, parentElement]) | instance | className: name of a CSS class associated with the elements, parentElement: object or id of the element that contains the elements being retrieved. | 返回所有CSS className屬性等於className參數的元素，如果沒有給出parentElement,那麼將搜索document body。(此處使用document.body我覺得不如使用document,因為有時有的頁麵沒有body) |
Event擴展
| Property | Type | Description |
|---|---|---|
| KEY_BACKSPACE | NumberNumber | 8: Constant. Code for the Backspace key. |
| KEY_TAB | Number | 9: Constant. Code for the Tab key. |
| KEY_RETURN | Number | 13: Constant. Code for the Return key. |
| KEY_ESC | Number | 27: Constant. Code for the Esc key. |
| KEY_LEFT | Number | 37: Constant. Code for the Left arrow key. |
| KEY_UP | Number | 38: Constant. Code for the Up arrow key. |
| KEY_RIGHT | Number | 39: Constant. Code for the Right arrow key. |
| KEY_DOWN | Number | 40: Constant. Code for the Down arrow key. |
| KEY_DELETE | Number | 46: Constant. Code for the Delete key. |
| observers: | Array | List of cached observers. Part of the internal implementation details of the object. |
| Method | Kind | Arguments | Description |
|---|---|---|---|
| element(event) | static | event: an Event object | 返回事件源對象。 |
| isLeftClick(event) | static | event: an Event object | 如果點擊了鼠標左鍵，返回true. |
| pointerX(event) | static | event: an Event object | 返回鼠標的X座標。 |
| pointerY(event) | static | event: an Event object | 返回鼠標的Y座標。 |
| stop(event) | static | event: an Event object | 使用此函數來中斷事件的默認行為並阻止傳遞（冒泡)。 |
| findElement(event, tagName) | static | event: an Event object, tagName: name of the desired tag. | 從事件源對象開始向上搜索DOM樹，直到找到第一個符合tagName的元素 |
| observe(element, name, observer, useCapture) | static | element: object or id, name: event name (like 'click', 'load', etc), observer: function to handle the event, useCapture: if true, handles the event in the capture phase and if false in the bubbling phase. | 為對象的某個事件增加一個處理函數。 |
| stopObserving(element, name, observer, useCapture) | static | element: object or id, name: event name (like 'click'), observer: function that is handling the event, useCapture: if true handles the event in the capture phase and if false in the bubbling phase. | 和上麵的函數相反。 |
| _observeAndCache(element, name, observer, useCapture) | static | 私有函數，別管它。 | |
| unloadCache() | static | (none) | 私有函數，別管它。從內存中清除所有的observers緩存。 |
下麵代碼演示如何給window添加一個load事件處理函數。
<script>
Event.observe(window, 'load', showMessage, false);
function showMessage() {
alert('Page loaded.');
}
</script>
在prototype.js中定義新的對象和類
另一個這個程序包幫助你的地方就是提供許多既支持麵向對象設計理念又有共通功能的許多對象。
The PeriodicalExecuter object
這個對象提供一定間隔時間上重複調用一個方法的邏輯。
| Method | Kind | Arguments | Description |
|---|---|---|---|
| [ctor](callback, interval) | constructor | callback: a parameterless function, interval: number of seconds | 創建這個對象的實例將會重複調用給定的方法。 |
| Property | Type | Description |
|---|---|---|
| callback | Function() | 被調用的方法，該方法不能傳入參數。 |
| frequency | Number | 以秒為單位的間隔。 |
| currentlyExecuting | Boolean | 表示這個方法是否正在執行。 |
The Prototype object
Prototype 沒有太重要的作用，隻是聲明了該程序包的版本 。
| Property | Type | Description |
|---|---|---|
| Version | String | |
| emptyFunction | Function() | 空函數。 |
| K | Function(obj) | 一個僅僅回傳參數的函數。 |
| ScriptFragment | String | 識別script的正則式。 |
The Enumerable object
Enumberable對象能夠已更優雅的方式實現對列表樣式的結構進行枚舉。
很多其它的對象通過擴展自Enumberable對象來得到這些有用的接口。
| Method | Kind | Arguments | Description |
|---|---|---|---|
| each(iterator) | instance | iterator: a function object conforming to Function(value, index) | 把每個element做為第一個參數，element的index作為第一個參數調用iterator函數。 |
| all([iterator]) | instance | iterator: a function object conforming to Function(value, index) | 這個函數會用給出的iterator測試整個集合，如果集合中任一元素在iterator函數測試中返回false或null，那麼這個函數返回false,否則返回true。如果沒有給出iterator，那麼就會測試所有的元素是不是不等於false和null。你可以簡單的把它看成是“檢測每個元素都為非空非負”。 |
| any(iterator) | instance | iterator: a function object conforming to Function(value, index), optional. | 這個函數會用給出的iterator測試整個集合，如果集合中任一元素在iterator函數測試中返回true，那麼這個函數返回true,否則返回false。如果沒有給出iterator，那麼就會測試所有的元素是不是有一個不等於false和null。你可以簡單的把它看成是“檢測元素中是不是有非空非負的”。 |
| collect(iterator) | instance | iterator: a function object conforming to Function(value, index) | 調用iterator函數根據集合中每個元素返回一個結果，然後按照原來集合中的順序，返回一個Array。 |
| detect(iterator) | instance | iterator: a function object conforming to Function(value, index) | 集合中每個元素調用一次Iterator，返回第一個使Iterator返回True的元素，如果最終都沒有為true的調用，那麼返回null。 |
| entries() | instance | (none) | 等於toArray(). |
| find(iterator) | instance | iterator: a function object conforming to Function(value, index) | 等於 detect(). |
| findAll(iterator) | instance | iterator: a function object conforming to Function(value, index) | 集合中每個元素調用Iterator，返回一個由所有調用Iterator返回結果等於true的元素組成的數組。和reject()相反。 |
| grep(pattern [, iterator]) | instance | pattern: a RegExp object used to match the elements, iterator: a function object conforming to Function(value, index) | 用pattern參數正則表達式測試集合中的每個元素，返回一個包含所有匹配正則式的元素的Array，如果給出了Iterator，那個每個結果還要經過一下Iterator處理。 |
| include(obj) | instance | obj: any object | 判斷集合中包不包含指定對象。 |
| inject(initialValue, iterator) | instance | initialValue: any object to be used as the initial value, iterator: a function object conforming to Function(accumulator, value, index) | 用Iterator聯接所有集合中的元素。Iterator在被調用時把上一次迭代的結果做為第一個參數傳給accumulator。第一次迭代時，accurmelator等於initialValue,最後返回accumulator的值。 |
| invoke(methodName [, arg1 [, arg2 [...]]]) | instance | methodName: name of the method that will be called in each element, arg1..argN: arguments that will be passed in the method invocation. | 集合中的每個元素調用指定的函數（查看源代碼可以發現指定函數被調用時，this指針被傳成當前元素），並傳入給出的參數，返回調用結果組成的Array。 |
| map(iterator) | instance | iterator: a function object conforming to Function(value, index) | 同collect(). |
| max([iterator]) | instance | iterator: a function object conforming to Function(value, index) | 返回集合中元素的最大值，或調用Iterator後返回值的最大值(如果給出了Iterator的話)。 |
| member(obj) | instance | obj: any object | 同 include(). |
| min([iterator]) | instance | iterator: a function object conforming to Function(value, index) | 返回最小值，參見max()。 |
| partition([iterator]) | instance | iterator: a function object conforming to Function(value, index) | 返回一個包含兩個Array的Array，第一個Array包含所有調用Iterator返回True的元素，第二個Array包含剩下的元素。如果Iterator沒有給出，那麼就根據元素本身判斷。 |
| pluck(propertyName) | instance | propertyName name of the property that will be read from each element. This can also contain the index of the element | 返回每個元素的指定屬性名的屬性的值組成的Array。 |
| reject(iterator) | instance | iterator: a function object conforming to Function(value, index) | 和 findAll()相反（返回所有等於false的元素）. |
| select(iterator) | instance | iterator: a function object conforming to Function(value, index) | 同 findAll(). |
| sortBy(iterator) | instance | iterator: a function object conforming to Function(value, index) | 根據每個元素調用Iterator返回的值進行排序返回一個Array。 |
| toArray() | instance | (none) | 返回由集合所有元素組成的一個Array。 |
| zip(collection1[, collection2 [, ... collectionN [,transform]]]) | instance | collection1 .. collectionN: enumerations that will be merged, transform: a function object conforming to Function(value, index) | 合並每個給出的集合到當前集合。合並操作返回一個新的array，這個array的元素個數和原集合的元素個數一樣，這個array的每個元素又是一個子array,它合並了所有集合中相同index的元素。如果transform函數被指定，那麼array的每個元素還會調用transform函數先做處理。舉個例子: [1,2,3].zip([4,5,6], [7,8,9]).inspect() 返回 "[ [1,4,7],[2,5,8],[3,6,9] ]" |
The Hash object
Hash對象實現一種Hash結構，也就是一個Key:Value對的集合。
Hash中的每個Item是一個有兩個元素的array，前一個是Key，後一個是Value，每個Item也有兩個不需加以說明的屬性,key和value。
| Method | Kind | Arguments | Description |
|---|---|---|---|
| keys() | instance | (none) | 返回所有Item的key的集合的一個array。 |
| values() | instance | (none) | 返回所有Item的value的集合的一個array。 |
| merge(otherHash) | instance | otherHash: Hash object | 合並給出的Hash，返回一個新Hash。 |
| toQueryString() | instance | (none) | 以QueryString那樣的樣式返回hash中所有的item，例如： 'key1=value1&key2=value2&key3=value3' |
| inspect() | instance | (none) | 用一種合適的方法顯示hash中的key:value對。 |
The ObjectRange class
用上、下邊界描述一個對象區域。
| Property | Type | Kind | Description |
|---|---|---|---|
| start | (any) | instance |
range的下邊界 |
| end | (any) | instance | range的上邊界 |
| exclusive | Boolean | instance | 決定邊界自身是不是range的一部分。 |
| Method | Kind | Arguments | Description |
|---|---|---|---|
| [ctor](start, end, exclusive) | constructor | start: the lower bound, end: the upper bound, exclusive: include the bounds in the range? | 創建一個range對象，從start生成到end,這裏要注意的是，start和end必段類型一致，而且該類型要有succ()方法。 |
| include(searchedValue) | instance | searchedValue: value that we are looking for | 檢查一個value是不是在range中。 |
The Class object
在這個程序包中 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
| Method | Kind | Arguments | Description |
|---|---|---|---|
| create(*) | instance | (any) | 定義新類的構造方法。 |
The Ajax object
這個對象被用作其他提供AJAX功能的類的根對象。
| Property | Type | Kind | Description |
|---|---|---|---|
| activeRequestCount | Number | instance | 正在處理中的Ajax請求的個數。 |
| Method | Kind | Arguments | Description |
|---|---|---|---|
| getTransport() | instance | (none) | 返回新的XMLHttpRequest 對象。 |
The Ajax.Responders object
這個對象維持一個在Ajax相關事件發生時將被調用的對象的列表。比如，你要設置一個全局鉤子來處理Ajax操作異常，那麼你就可以使用這個對象。
| Property | Type | Kind | Description |
|---|---|---|---|
| responders | Array | instance | 被注冊到Ajax事件通知的對象列表。 |
| Method | Kind | Arguments | Description |
|---|---|---|---|
| register(responderToAdd) | instance | responderToAdd: object with methods that will be called. | 被傳入參數的對象應包含名如Ajax事件的係列方法（如onCreate,onComplete,onException）。通訊事件引發所有被注冊的對象的合適名稱的函數被調用。 |
| unregister(responderToRemove) | instance | responderToRemove: object to be removed from the list. | 從列表中移除。 |
| dispatch(callback, request, transport, json) | instance | callback: name of the AJAX event being reported, request: the Ajax.Request object responsible for the event, transport: the XMLHttpRequest object that carried (or is carrying) the AJAX call, json: the X-JSON header of the response (if present) | 遍曆被注冊的對象列表，找出有由callback參數決定的那個函數的對象。然後向這些函數傳遞其它的三個參數，如果Ajax響應中包含一個含有JSON內容的X-JSON HTTP頭，那麼它會被熱行並傳入json參數。如果事件是onException,那麼transport參數會被異常代替，json不會傳遞。 |
The Ajax.Base class
這個類是其他在Ajax對象中定義的類的基類。
The Ajax.Request class
封裝 AJAX 操作
| Property | Type | Kind | Description |
|---|---|---|---|
| Events | Array | static | 在AJAX操作中所有可能報告的事件/狀態的列表。這個列表包括: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', 和 'Complete'。 |
| transport | XMLHttpRequest | instance | 承載AJAX操作的 XMLHttpRequest 對象。 |
| url | string | instance | 請求的URL。 |
| Method | Kind | Arguments | Description |
|---|---|---|---|
| [ctor](url, options) | constructor | url: the url to be fetched, options: AJAX options | 創建這個對象的一個實例，它將在給定的選項下請求url。onCreate事件在調用constructor事被激發。 重要： 如果選擇的url受到瀏覽器的安全設置，他會一點作用也不起。 很多情況下，瀏覽器不會請求與當前頁麵不同主機(域名)的url。 你最好隻使用本地url來避免限製用戶配置他們的瀏覽器(謝謝Clay) |
| evalJSON() | instance | (none) | 這個方法顯然不會被外部調用。它在Ajax響應中含有X-JSON HTTP頭時用於內部調用執行這些內容。 |
| evalReponse() | instance | (none) | 這也方法顯然不會被外部調用，如果Ajax響應含有一個值為text/javascript的Cotent-Type頭，那麼這個方法就用被調用執行響應體。 |
| header(name) | instance | name: HTTP header name | 引用Ajax響應的頭的內容，在Ajax訪問結束後再調用這個方法。 |
| onStateChange() | instance | (none) | 這個方法通常不會被外部調用。 當AJAX請求狀態改變的時候被這個對象自己調用。 |
| request(url) | instance | url: url for the AJAX call | 這個方法通常不會被外部調用。已經在構造方法中調用了。 |
| respondToReadyState(readyState) | instance | readyState: state number (1 to 4) | 這個方法通常不會被外部調用。 當AJAX請求狀態改變的時候被這個對象自己調用。 |
| setRequestHeaders() | instance | (none) | 這個方法通常不會被外部調用。 被這個對象自己調用來配置在HTTP請求要發送的HTTP報頭。 |
The options argument object
An important part of the AJAX operations is the options argument. There's no options class per se. Any object can be passed, as long as it has the expected properties. It is common to create anonymous objects just for the AJAX calls.
The Ajax.Updater class
當請求的url返回一段HTML而你想把它直接放置到頁麵中一個特定的元素的時候被用到。 如果url的返回<script> 的塊並且想在接收到時就執行它的時候也可以使用該對象。含有腳本的時候使用 evalScripts 選項。
| Property | Type | Kind | Description |
|---|---|---|---|
| containers | Object | instance | 這個對象包含兩個屬性:AJAX請求成功執行的時候用到 containers.success , 否則的話用到 containers.failure 。 |