prototype.js　1.4版開發者手冊(強烈推薦) (轉載)

原創 liangjian103103103 2018-11-14 08:51

看到一個很好的東西在國內沒有被很多人使用起來，實在是不爽，所以花了很大功夫把這個手冊翻譯成中文，由於這篇文章很長，所以，翻譯的工作量很大而且有些地方英文版也沒有說清楚，雖得查看源代碼，好在不是堅持做完了，大家鼓勵下啊！^o^
prototype.js是一個非常優雅的javascript基礎類庫，對javascript做了大量的擴展，而且很好的支持Ajax，國外有多個基於此類庫實現的效果庫，也做得很棒。
prototype.js不僅是一個有很大實用價值的js庫，而且有很高的學習價值，所以我強烈建議B/S開發人員和對JS開發感興趣的朋友去瀏覽一些它的源代碼，其中有很多的珠璣，你絕對會覺得讀它的源代碼是一種享受，當然要讀得懂，呵呵。
網上也有人寫過1.3版的源碼解讀，大家可以找來看看。不過1.4版做了很大的擴充，所以希望有朋友寫出1.4版的源碼解讀。
幾點說明：

  • 有朋友說prototye已經有人翻譯過了，呵呵，是對的，說明你以前關注過它，不過原來翻譯的是1.3版的文檔，1.4版有很多重要的擴展，而且pre_1.5版現在也出來，不地改動不大。
  • 有朋友說有用多沒有翻譯地來的，拜託，只是各個方法的參數說明沒有翻，這些說明很多都是什麼類型，還是有空再弄吧，先將就一下，對不起了，翻到這個程序已經很累人了，畢竟有這麼長。
  • 做成CHM文檔的事也只能Sorry，因爲我沒有這個時間，也沒有做過CHM，我覺得排版一下看網頁和CHM是差不多吧。

 

 

prototype.js是什麼?

萬一你沒有使用過大名鼎鼎的prototype.js，那麼讓我來告訴你，prototype.js是由Sam Stephenson寫的一個javascript類庫。這個構思奇妙，而且兼容標準的類庫，能幫助你輕鬆建立有高度互動的web2.0特性的富客戶端頁面。

如果你最近嘗試使用它，你大概瞭解到文檔並不是作者的一個強項。和在我以前使用這個類庫的不少開發者一樣，一開始，我不得不一頭扎進閱讀prototype.js的源代碼和實驗它的功能中。我想，在我學習完它之後，把我學到的東西分享給大家是件不錯的事。

同時，在本文中，我也將提供一個關於這個類庫提供的objects,classes,functions,extensions這對東東的非官方參考

在閱讀這個文檔時，熟悉Ruby的開發者將會注意到Ruby的一些內建類和本類庫擴展實現之間非常相似。

相關文章

Advanced JavaScript guide.

一些實用的函數

這個類庫帶有很多預定義的對象和實用函數，這些東東的目的顯然是把你從一些重複的打字中解放出來 。

使用$()方法

$() 方法是在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>

 

另外一個好處是，這個函數能傳入用string表示的對象ID，也可以傳入對象本身，這樣，在建立其它能傳兩種類型的參數的函數時非常有用。

使用$F()函數

$F()函數是另一個大收歡迎的“快捷鍵”，它能用於返回任何表單輸入控件的值，比如text box,drop-down list。這個方法也能用元素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>

 

使用$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 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();" >

 

使用 $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)的縮寫。

跳到ObjectRange 類文檔可以看到一個關於此類的完整描述. 此時，我們還是先來看一個例子以展示這個縮寫能代替哪些方法吧。其它相關的一些知識可以在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();" >

 

使用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邏輯的類。我們來看看其中幾個類。

使用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。

 在1.4.0版本中，一種新的事件回傳外理被引入。如果你有一段代碼總是要爲一個特殊的事件執行，而不管是哪個AJAX調用引發它，那麼你可以使用新的Ajax.Responders對象。

假設你想要在一個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.Request 參考 和 Ajax選項參考。

 

使用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>

 如果你的服務器邏輯是連同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" onclick="sayHi()">

 如果你以前這樣嘗試過，你知道這些腳本不會如你所期望的那樣工作，原因是這段腳本會被執行，但像上面這樣的腳本執行並不會創建一個名叫sayHi的函數，它什麼也不做。如果要創建一個函數，我們應當把代碼改成下面這個樣子：

<script language="javascript" type="text/javascript">

sayHi = function(){
alert('Hi');
};

</script>
<input type=button value="Click Me" onclick="sayHi()">

 

爲什麼我們在上面的代碼中不使用var關鍵字來聲明這個變量呢（指sayHi ），因爲那樣做創建出來的函數將只是當前腳本塊的一個局部變量（至少在IE中是這樣）。不寫var關鍵字，創建出來的對象的作用域就是我們所期望的window。

更多相關知識，請參看  Ajax.Updater reference 和options reference.

枚舉... 噢!噢!

你知道，我們都是這樣來做循環的，建一個Array，用elements組織它們，再建一個循環結構（例如for,foreach,while)通過index數字來訪問每一個element，再用這個element做一些動作。

當你想到這時，你會發現幾乎每次寫循環代碼你都會遲早用到一個Array。那麼，如果Array對象能夠提供更多的功能給它們的迭代器使用不是很爽嗎？確實是這樣，事實上很多的編程語言都在它們的Array或其它類似的結構中（如Collections,Lists）提供一些這樣的功能。

現在好了，prototype.js了給我們一個 Enumerable對象，它實現了很多和可迭代數據進行交互的竅門。和原有的JS對象相比prototype.js更上一層樓，它對Array 類s擴展了所有枚舉要用的函數。

循環, Ruby樣式的

在標準的javascript中，如果你想把一個array中的所有elements顯示出來，你可以像下面代碼這樣寫得很好： 

<script>

function showList(){

var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Meg'];

for(i=0;i<simpsons.length;i++){
alert(simpsons[i]);
}

}
</script>
<input type="button" value="Show List" onclick="showList();" >

 使用我們新的最好的朋友，prototype.js，我們可以把它生寫成這樣 

function showList(){

var simpsons = ['Homer', 'Marge', 'Lisa', 'Bart', 'Meg'];

simpsons.each( function(familyMember){
alert(familyMember);
});

}

 

你可能會想“非常奇怪的方式...相對舊的，這種語法太怪異了”。哦，在上面的例子，確實什麼也沒有，在這個簡單得要死例子中，也沒有改變太多啊，儘管如此，請繼續讀下去。

在繼續下面內容之前，你注意到那個被做爲一個參數傳遞給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 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="Find Laura" onclick="findEmployeeById(8);" >

 現在我們再下一城，看看如何過濾一個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 id="someText">

This <a href="http://othersite.com/page.html">text</a> has

a <a href="#localAnchor">lot</a> of

<a href="#otherAnchor">links</a>. Some are

<a href="http://wherever.com/page.html">external</a>

and some are <a href="#someAnchor">local</a>

</p>

<input type=button value="Find Local Links" onclick="showLocalLinks('someText')">

上面的代碼僅僅是一點小小的實踐讓人愛上這種語法。請參看 Enumerable和Array的所有函數

 

 

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()" onclick="demoTimes()">

 

對 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

this.chkBox.onclick = this.showMessage.bindAsEventListener(this);

},
showMessage: function(evt) {
alert(this.message + ' (' + evt.type + ')');
}
};
var watcher = new CheckboxWatcher('myChk', 'Changed');
</script>

  

對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

繼承自  Enumerable

用上、下邊界描述一個對象區域。

 

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

繼承自 Enumerable

這個對象維持一個在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對象中定義的類的基類。

 

Method Kind Arguments Description
setOptions(options) instance options: AJAX options 設定AJAX操作想要的選項。
responseIsSuccess() instance (none) 返回 true 如果AJAX操作成功,否則爲 false 。
responseIsFailure() instance (none) 與 responseIsSuccess() 相反。

 

The Ajax.Request class

繼承自 Ajax.Base

封裝 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.

 

Property Type Default Description
method String '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, Object) undefined 在AJAX請求中，當相應的事件/狀態形成的時候調用的自定義方法。 例如 var myOpts = {onComplete: showResponse, onLoaded: registerLoaded};. 這個方法將被傳入一個參數， 這個參數是承載AJAX操作的 XMLHttpRequest 對象，另一個是包含被執行X-JSON響應HTTP頭。
onSuccess Function(XMLHttpRequest, Object) undefined 當AJAX請求成功完成的時候調用的自定義方法。 這個方法將被傳入一個參數， 這個參數是承載AJAX操作的 XMLHttpRequest 對象，另一個是包含被執行X-JSON響應HTTP頭。
onFailure Function(XMLHttpRequest, Object) undefined 當AJAX請求完成但出現錯誤的時候調用的自定義方法。這個方法將被傳入一個參數， 這個參數是承載AJAX操作的 XMLHttpRequest 對象，另一個是包含被執行X-JSON響應HTTP頭。
onException Function(Ajax.Request, exception) undefined 當一個在客戶端執行的Ajax發生像無效響應或無效參數這樣的異常情況時被調用的自定義函數。它收到兩個參數，包含異常Ajax操作的Ajax.Request對象和異常對象。
insertion an Insertion class undefined 一個能決定怎麼樣插入新內容的類，能 Insertion.Before, Insertion.Top, Insertion.Bottom, 或 Insertion.After. 只能應用於Ajax.Updater 對象.
evalScripts Boolean undefined, false 決定當響應到達的時候是否執行其中的腳本塊，只在 Ajax.Updater 對象中應用。
decay Number undefined, 1 決定當最後一次響應和前一次響應相同時在 Ajax.PeriodicalUpdater 對象中的減漫訪問的次數， 例如，如果設爲2，後來的刷新和之前的結果一樣， 這個對象將等待2個設定的時間間隔進行下一次刷新， 如果又一次一樣， 那麼將等待4次，等等。 不設定這個只，或者設置爲1，將避免訪問頻率變慢。
frequency Number undefined, 2 用秒錶示的刷新間的間隔，只能應用於 Ajax.PeriodicalUpdater  對象。

 

The Ajax.Updater class

繼承自 Ajax.Request

當請求的url返回一段HTML而你想把它直接放置到頁面中一個特定的元素的時候被用到。 如果url的返回<script> 的塊並且想在接收到時就執行它的時候也可以使用該對象。含有腳本的時候使用 evalScripts 選項。

 

Property Type Kind Description
containers Object instance 這個對象包含兩個屬性:AJAX請求成功執行的時候用到 containers.success , 否則的話用到 containers.failure 。

 

 

Method Kind Arguments Description
[ctor](container, url, options) constructor container:this can be the id of an element, the element object itself, or an object with two properties - object.success element (or id) that will be used when the AJAX call succeeds, and object.failure element (or id) that will be used otherwise. url: the url to be fetched, options: AJAX options 創建一個用給定的選項請求給定的url的一個實例。
updateContent() instance (none) 這個方法通常不會被外部調用。 當響應到達的時候，被這個對象自己調用。 它會用HTML更新適當的元素或者調用在 insertion 選項中傳入的方法-這個方法將被傳入兩個參數， 被更新的元素和響應文本。

 

The Ajax.PeriodicalUpdater class

繼承自Ajax.Base

這個類重複生成並使用 Ajax.Updater 對象來刷新頁面中的一個元素。或者執行 Ajax.Updater 可以執行的其它任務。更多信息參照 Ajax.Updater 參考 。

 

Property Type Kind Description
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 計時器。

 

 

Method Kind Arguments Description
[ctor](container, url, options) constructor container:this can be the id of an element, the element object itself, or an object with two properties - object.success element (or id) that will be used when the AJAX call succeeds, and object.failure element (or id) that will be used otherwise. url: the url to be fetched, options: AJAX options 創建一個用給定的選項請求給定的url的一個實例。
start() instance (none) 這個方法通常不會被外部調用。 對象爲了開始週期性執行任務的時候調用的方法。
stop() instance (none) 使對象停止執行週期任務。停止後，如果有onComplete選項，那麼引發callback。
updateComplete() instance (none) 這個方法通常不會被外部調用。 被當前的 Ajax.Updater 使用，當一次請求結束的時候，它被用作計劃下一次請求。
onTimerEvent() instance (none) 這個方法通常不會被外部調用。當到下一次更新時被內部調用。

 

The Element object

這個對象提供在操作DOM中元素時使用的功能性方法。

 

Method Kind Arguments Description
addClassName(element, className) instance element: element object or id, className: name of a CSS class 將給出的className添加到對象的className屬性中。
classNames(element) instance element: element object or id 返回一個Element.ClassName的對象表示CSS 給出對象有的class names。
cleanWhitespace(element) instance element: element object or id 清除對象子元素中所有空白的text node。
empty(element) instance element: element object or id 返回一個布爾值指示對象爲空或只有空白字符。
getDimensions(element) instance element: element object or id 返回對象的尺寸，返回值有兩個屬性，height和width。
getHeight(element) instance element: element object or id 返回元素的 offsetHeight 。
getStyle(element, cssProperty) instance element: element object or id, cssProperty name of a CSS property (either format 'prop-name' or 'propName' works). 返回給定對象的CSS屬性值或沒有指定cssProperty時返回null。
hasClassName(element, className) instance element: element object or id, className: name of a CSS class 返回 true 如果元素的類名中含有給定的類名
hide(elem1 [, elem2 [, elem3 [...]]]) instance elemN: element object or id 通過設定style.display 爲 'none'來隱藏每個傳入的元素。
makeClipping(element) instance element: element object or id 能過設定overflow的值設定內容溢出剪輯。
makePositioned(element) instance element: element object or id 更改對象的style.position爲'relative'。
remove(element) instance element: element object or id 從document對象中刪除指定的元素。
removeClassName(element, className) instance element: element object or id, className: name of a CSS class 從元素的類名中刪除給定的類名。
scrollTo(element) instance element: element object or id 滾動window到對象的位置。
setStyle(element, cssPropertyHash) instance element: element object or id, cssPropertyHash Hash object with the styles to be applied. 依照cssPropertyHash參數給對象設置CSS屬性值。
show(elem1 [, elem2 [, elem3 [...]]]) instance elemN: element object or id 用設定它的 style.display 爲 ''來顯示每個傳入的元素。
toggle(elem1 [, elem2 [, elem3 [...]]]) instance elemN: element object or id 切換每一個傳入元素的可視性。
undoClipping(element) instance element: element object or id style.overflow的值返回上一個設定值。
undoPositioned(element) instance element: element object or id 清除對象的 style.position 爲 ''
update(element, html) instance element: element object or id, html: html content 用給出的HTML參數替換對象的innerHTML,如果HTML參數中包含<script>，那麼它們不會被包含進去，但是會執行。
visible(element) instance element: element object or id 返回一個布爾值指示對象可不可見。

 

The Element.ClassNames class

繼承自  Enumerable

在一個對象中表示CSS class names的集合。

 

Method Kind Arguments Description
[ctor](element) constructor element: any DOM element object or id 創建一個對象，給出對象的CSS class names被表現在這個ClassNames對象中。
add(className) instance className: a CSS class name 把CSS class name包含進對象的class names 列表。
remove(className) instance className: a CSS class name 從對象的class names列表中移除className
set(className) instance className: a CSS class name 設定對象CSS class name爲className,移除其它class names。

 

The Abstract object

這個對象是這個程序包中其他類的根。它沒有任何屬性和方法。在這個對象中定義的類可以被視爲傳統的抽象類。

The Abstract.Insertion class

這個類被用作其他提供動態內容插入功能的類的基類，它像一個抽象類一樣被使用。

 

Method Kind Arguments Description
[ctor](element, content) constructor element: element object or id, content: HTML to be inserted 創建一個可以幫助插入動態內容的對象。
contentFromAnonymousTable() instance (none) 對content通過匿名錶格變成一個Node數組。

 

 

Property Type Kind Description
adjacency String static, parameter 這個參數指定相對於給定元素，內容將被放置的位置。 可能的值是: 'beforeBegin', 'afterBegin', 'beforeEnd', 和 'afterEnd'.
element Object instance 與插入物做參照元素對象。
content String instance 被插入的 HTML 。

 

The Insertion object

這個對象是其他類似功能的根。它沒有任何屬性和方法。在這個對象中定義的類仍然可以被視爲傳統的抽象類。

The Insertion.Before class

繼承自 Abstract.Insertion

在給定元素開始標記的前面插入HTML。

 

Method Kind Arguments Description
[ctor](element, content) constructor element: element object or id, content: HTML to be inserted 繼承自   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>

The Insertion.Top class


繼承自 Abstract.Insertion


在給定元素第一個子節點位置插入 HTML。內容將位於元素的開始標記的緊後面。


 


 


Method
Kind
Arguments
Description

[ctor](element, content)
constructor
element: element object or id, content: HTML to be inserted
繼承自  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>



The Insertion.Bottom class


Inherits from Abstract.Insertion


在給定元素最後一個子節點位置插入 HTML。內容將位於元素的結束標記的緊前面。


 


 


Method
Kind
Arguments
Description

[ctor](element, content)
constructor
element: element object or id, content: HTML to be inserted
Inherited from Abstract.Insertion. Creates an object that will help with dynamic content insertion.

 


The following code 


<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.Bottom('person', " What's up?"); </script>




Will change the HTML to 


<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going? What's up?</span>








The Insertion.After class


Inherits from Abstract.Insertion


在給定元素結束標記的後面插入HTML。


 


Method
Kind
Arguments
Description

[ctor](element, content)
constructor
element: element object or id, content: HTML to be inserted
Inherited from Abstract.Insertion. Creates an object that will help with dynamic content insertion.

 


The following code 


<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.After('person', ' Are you there?'); </script>




Will change the HTML to 


<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> Are you there?





The Field object


這個對象提供操作表單中的輸入項目的功能性方法。


 


Method
Kind
Arguments
Description

clear(field1 [, field2 [, field3 [...]]])
instance
fieldN: field element object or id 
清除傳入表單中項目元素的值。

present(field1 [, field2 [, field3 [...]]])
instance
fieldN: field element object or id 
只有在所有的表單項目都不爲空時返回 true 。

focus(field)
instance
field: field element object or id
移動焦點到給定的表單項目。

select(field)
instance
field: field element object or id
選擇支持項目值選擇的表單項目的值。

activate(field)
instance
field: field element object or id
移動焦點並且選擇支持項目值選擇的表單項目的值。

 




The Form object


這個對象提供操作表單和他們的輸入元素的功能性方法。


 


Method
Kind
Arguments
Description

serialize(form)
instance
form: form element object or id
返回url參數格式的項目名和值的列表， 如'field1=value1&field2=value2&field3=value3'。 

findFirstElement(form)
instance
form: form element object or id
返回Form中第一個Enable的對象。

getElements(form)
instance
form: form element object or id
返回包含所有在表單中輸入項目的 Array 對象。

getInputs(form [, typeName [, name]])
instance
form: form element object or id, typeName: the type of the input element, name: the name of the input element.
返回一個 Array 包含所有在表單中的 <input> 元素。 另外， 這個列表可以對元素的類型或名字屬性進行過濾。

disable(form)
instance
form: form element object or id
使表單中的所有輸入項目無效。

enable(form)
instance
form: form element object or id
使表單中的所有輸入項目有效。

focusFirstElement(form)
instance
form: form element object or id
激活第一個表單中可視的，有效的輸入項目。

reset(form)
instance
form: form element object or id
重置表單。和調用表單對象的 reset() 方法一樣。

 




The Form.Element object


這個對象提供表單對象中的可視和非可視元素的功能性方法。


 


Method
Kind
Arguments
Description

serialize(element)
instance
element: element object or id
返回元素的 名稱=值 對, 如 'elementName=elementValue'。 

getValue(element)
instance
element: element object or id
返回元素的值。

 




The Form.Element.Serializers object


這個對象提供了內部使用的用來協助解析出表單元素的當前值的一些有用的方法。


 


Method
Kind
Arguments
Description

inputSelector(element)
instance
element: object or id of a form element that has the checked property, like a radio button or checkbox.
返回帶有元素名稱和值的 Array , 如 ['elementName', 'elementValue'] 

textarea(element)
instance
element: object or id of a form element that has the value property, like a textbox, button or password field.
返回帶有元素名稱和值的 Array , 如 ['elementName', 'elementValue'] 

select(element)
instance
element: object of a <select> element
返回帶有元素名稱和所有被選擇的選項的值或文本的 Array , 如 ['elementName', 'selOpt1 selOpt4 selOpt9'] 

 




The Abstract.TimedObserver class


這個類是用於其它監聽一個元素的值(或者任何類中涉及的屬性)變化的類的基類，這個類像一個抽象類一樣被使用。


子類可以被創建來監聽如輸入項目值，或style屬性，或表格的行數，或者其他任何對跟蹤變化相關的東西。


子類必須實現這個方法來決定什麼纔是被監聽的元素的當前值。 


Method
Kind
Arguments
Description

[ctor](element, frequency, callback)
constructor
element: element object or id, frequency: interval in seconds, callback: function to be called when the element changes
創建一個監聽元素的對象。

getValue()
instance, abstract
(none)
子類必須實現這個方法以瘊定什麼這個元素被監視的當前值。

registerCallback()
instance
(none)
這個方法通常不會被外部調用。 被這個對象自己調用來開始監聽那個元素。 

onTimerEvent()
instance
(none)
這個方法通常不會被外部調用。 被這個對象自己調用來週期性的檢查那個元素。 

 


 


Property
Type
Description

element
Object
被監聽的元素對象。

frequency
Number
每次檢查中的以秒爲單位的時間間隔。

callback
Function(Object, String)
只要元素改變這個方法就會被調用。 會接收到元素對象和新值作爲參數。

lastValue
String
元素被覈實的最後一個值。

 




The Form.Element.Observer class


繼承自 Abstract.TimedObserver


Abstract.TimedObserver 的一個實現類用來監聽表單輸入項目的值的變化。當你想監聽一個沒有帶報告值變化事件的元素的時候使用這個類。否則的話使用 Form.Element.EventObserver 類代替。


 


Method
Kind
Arguments
Description

[ctor](element, frequency, callback)
constructor
element: element object or id, frequency: interval in seconds, callback: function to be called when the element changes
繼承自 Abstract.TimedObserver. 創建一個監聽元素值屬性的對象。

getValue()
instance
(none)
返回元素的值。

 




The Form.Observer class


繼承自 Abstract.TimedObserver


Abstract.TimedObserver 的一個實現類用來監聽表單中任何數據項的值的變化。當你想監聽一個沒有帶報告值變化事件的元素的時候使用這個類。 否則的話使用類Form.EventObserver 代替。


 


Method
Kind
Arguments
Description

[ctor](form, frequency, callback)
constructor
form: form object or id, frequency: interval in seconds, callback function to be called when any data entry element in the form changes
繼承自 Abstract.TimedObserver. 創建一個監聽表單變化的對象。

getValue()
instance
(none)
返回所有表單數據的一系列值。

 




The Abstract.EventObserver class


這個類被用作其他一些類的基類，這些類具有在一個元素的值改變事件發生的時候執行一個回調方法這樣的功能。


類 Abstract.EventObserver 的多個對象可以綁定到一個元素上，不是一個幫其他的擦出了，而是按照他們付給元素的順序執行這些回調方法。


單選按鈕和複選框的觸發事件是 onclick ，而文本框和下拉列表框/下拉列表框的是 onchange 。  


 


Method
Kind
Arguments
Description

[ctor](element, callback)
constructor
element: element object or id, callback: function to be called when the event happens
創建監聽元素的對象。

getValue()
instance,abstract
(none)
子類必須實現這個方法以瘊定什麼這個元素被監視的當前值。

registerCallback()
instance
(none)
這個方法通常不會被外部調用。 被對象調用來把自己綁定到元素的事件上。 

registerFormCallbacks()
instance
(none)
這個方法通常不會被外部調用。 被對象調用來把自己綁定到表單中的每一個數據項元素的事件上。 

onElementEvent()
instance
(none)
這個方法通常不會被外部調用。 將被綁定到元素的事件上。 

 


 


Property
Type
Description

element
Object
被監聽的元素對象。

callback
Function(Object, String)
只要元素改變就調用的方法。會接收到元素對象和新值作爲參數。

lastValue
String
元素被覈實的最後一個值。

 




The Form.Element.EventObserver class


繼承自 Abstract.EventObserver


Abstract.EventObserver 的一個實現類，它在監測到表單中數據項元素的值改變的相應事件時候執行一個回調方法。 如果元素沒有任何報告變化的事件，那麼你可以使用 Form.Element.Observer 類代替。


 


Method
Kind
Arguments
Description

[ctor](element, callback)
constructor
element: element object or id, callback: function to be called when the event happens
繼承自 Abstract.EventObserver。 創建一個監聽元素值屬性的對象。

getValue()
instance
(none)
返回元素的值。

 




The Form.EventObserver class


繼承自 Abstract.EventObserver


Abstract.EventObserver 的一個實現類，監聽表單對象中包含的任何對象的任何變化，用元素的事件檢測值的變化。如果元素沒有任何報告變化的事件， 那麼你可以使用Form.Observer 類代替。 


Method
Kind
Arguments
Description

[ctor](form, callback)
constructor
form: form object or id, callback: function to be called when any data entry element in the form changes
繼承自 Abstract.EventObserver。 創建一個監聽元素值屬性的對象。

getValue()
instance
(none)
返回所有表單數據的一系列值。

 





Position 對象 (預備文檔)


這個對象提供許多和元素位置相關的方法。


 


Method
Kind
Arguments
Description

prepare()
instance
(none)
調整 deltaX 和 deltaY 屬性來協調在滾動位置中的變化。 記得在頁面滾動之後的任何調用的withinIncludingScrolloffset 之前調用這個方法。

realOffset(element)
instance
element: object
返回這個元素的正確滾動偏差的 Array 對象， 包括所有影響元素的滾動偏差。結果數組類似 [total_scroll_left, total_scroll_top] 

cumulativeOffset(element)
instance
element: object
回這個元素的正確滾動偏差的 Array 對象， 包含任何被放置的父元素強加偏差。結果數組類似 [total_offset_left, total_offset_top] 

within(element, x, y)
instance
element: object, x and y: coordinates of a point
測試給定的點的座標是否在給定的元素的外部矩形範圍之內。

withinIncludingScrolloffsets(element, x, y)
instance
element: object, x and y: coordinates of a point
 測試給定的點的座標是否在給定的元素的外部矩形範圍之內（包含scroll offsets）。

overlap(mode, element)
instance
mode: 'vertical' or 'horizontal', element: object
在調用這個方法之前需要調用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: element object or id, target: element object or id
改變目標元素的大小尺寸和位置與源元素的相同。

 






 










    





發表評論














所有評論



還沒有人評論，想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.







相關文章








用生僻字實現雙字詞高亮顯示






liangjian103103103

2018-11-04 09:20:43