prototype.js 1.4版开发者手册
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的扩展
| extend(destination, source) | <nobr>static</nobr> | destination: any object, source: any object | 提供一种通过拷贝所有源以象属性和函数到目标函数实现继承的方法 |
| inspect(targetObj) | static | targetObj: any object | 返回可读性好关于目标对象的文字描述，如果对象实例没有定义一个inspect函数，默认返回toString函数的值。 |
对Number的扩展
| toColorPart() | <nobr>instance</nobr> | (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扩展
| bind(object) | <nobr>instance</nobr> | 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的扩展
| stripTags() | instance | (none) | 返回一个把所有的HTML或XML标记都移除的字符串。 |
| stripScripts() | <nobr>instance</nobr> | (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都是可以使用的，除此之外，下面的这些也是已经实现了的。
| clear() | <nobr>instance</nobr> | (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扩展
| getElementsByClassName(className [, parentElement]) | <nobr>instance</nobr> | 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扩展
| KEY_BACKSPACE | <nobr>Number</nobr>Number | 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. |
| 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() | <nobr>static</nobr> | (none) | 私有函数，别管它。从内存中清除所有的observers缓存。 |
下面代码演示如何给window添加一个load事件处理函数。
<script>
Event.observe(window, 'load', showMessage, false);
function showMessage() {
alert('Page loaded.');
}
</script>
在prototype.js中定义新的对象和类
另一个这个程序包帮助你的地方就是提供许多既支持面向对象设计理念又有共通功能的许多对象。
The PeriodicalExecuter object
这个对象提供一定间隔时间上重复调用一个方法的逻辑。
| [ctor](callback, interval) | <nobr>constructor</nobr> | callback: a parameterless function, interval: number of seconds | 创建这个对象的实例将会重复调用给定的方法。 |
| callback | <nobr>Function()</nobr> | 被调用的方法，该方法不能传入参数。 |
| frequency | Number | 以秒为单位的间隔。 |
| currentlyExecuting | Boolean | 表示这个方法是否正在执行。 |
The Prototype object
Prototype 没有太重要的作用，只是声明了该程序包的版本 。
| Version | String | 版本。 |
| emptyFunction | <nobr>Function()</nobr> | 空函数。 |
| K | Function(obj) | 一个仅仅回传参数的函数。 |
| ScriptFragment | String | 识别script的正则式。 |
The Enumerable object
Enumberable对象能够已更优雅的方式实现对列表样式的结构进行枚举。
很多其它的对象通过扩展自Enumberable对象来得到这些有用的接口。
| each(iterator) | <nobr>instance</nobr> | 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。
| keys() | instance | (none) | 返回所有Item的key的集合的一个array。 |
| values() | <nobr>instance</nobr> | (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
用上、下边界描述一个对象区域。
| start | (any) | <nobr>instance</nobr> | range的下边界 |
| end | (any) | instance | range的上边界 |
| exclusive | Boolean | instance | 决定边界自身是不是range的一部分。 |
| [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) | <nobr>instance</nobr> | 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
| create(*) | <nobr>instance</nobr> | (any) | 定义新类的构造方法。 |
The Ajax object
这个对象被用作其他提供AJAX功能的类的根对象。
| activeRequestCount | Number | instance | 正在处理中的Ajax请求的个数。 |
| getTransport() | <nobr>instance</nobr> | (none) | 返回新的XMLHttpRequest 对象。 |
The Ajax.Responders object
继承自 Enumerable
这个对象维持一个在Ajax相关事件发生时将被调用的对象的列表。比如，你要设置一个全局钩子来处理Ajax操作异常，那么你就可以使用这个对象。
| responders | Array | <nobr>instance</nobr> | 被注册到Ajax事件通知的对象列表。 |
| 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对象中定义的类的基类。
| setOptions(options) | <nobr>instance</nobr> | options: AJAX options | 设定AJAX操作想要的选项。 |
| responseIsSuccess() | instance | (none) | 返回 true 如果AJAX操作成功,否则为 false 。 |
| responseIsFailure() | instance | (none) | 与 responseIsSuccess() 相反。 |
The Ajax.Request class
继承自 Ajax.Base
封装 AJAX 操作
| Events | Array | static | 在AJAX操作中所有可能报告的事件/状态的列表。这个列表包括: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', 和 'Complete'。 |
| transport | XMLHttpRequest | instance | 承载AJAX操作的 XMLHttpRequest 对象。 |
| url | <nobr>string</nobr> | <nobr>instance</nobr> | 请求的URL。 |
| [ctor](url, options) | constructor | url: the url to be fetched, options: AJAX options | 创建这个对象的一个实例，它将在给定的选项下请求url。onCreate事件在调用constructor事被激发。 重要： 如果选择的url受到浏览器的安全设置，他会一点作用也不起。 很多情况下，浏览器不会请求与当前页面不同主机(域名)的url。 你最好只使用本地url来避免限制用户配置他们的浏览器(谢谢Clay) |
| evalJSON() | <nobr>instance</nobr> | (none) | 这个方法显然不会被外部调用。它在Ajax响应中含有X-JSONHTTP头时用于内部调用执行这些内容。 |
| evalReponse() | instance | (none) | 这也方法显然不会被外部调用，如果Ajax响应含有一个值为text/javascript的Cotent-Type头，那么这个方法就用被调用执行响应体。 |
| header(name) | instance | name: HTTP header name | 引用Ajax响应的头的内容，在Ajax访问结束后再调用这个方法。 |
| onStateChange() | instance | (none) | 这个方法通常不会被外部调用。 当AJAX请求状态改变的时候被这个对象自己调用。 |
| request(url) | <nobr>instance</nobr> | url: url for the AJAX call | 这个方法通常不会被外部调用。已经在构造方法中调用了。 |
| respondToReadyState(readyState) | instance | readyState: state number (1 to 4) | 这个方法通常不会被外部调用。 当AJAX请求状态改变的时候被这个对象自己调用。 |
| setRequestHeaders() | instance | (none) | 这个方法通常不会被外部调用。
分享到：
发表评论
wapysun
最新评论
|
评论