xiang888

prototype.js开发笔记

--------------------------------------------------------------------------------

覆盖版本 1.3.1
1. Prototype是什么?
或许你还没有用过它， prototype.js 是一个由Sam Stephenson写的JavaScript包。这个构思奇妙编写良好的一段兼容标准的一段代码将承担创造胖客户端，高交互性WEB应用程序的重担。轻松加入Web 2.0特性。

如果你最近体验了这个程序包，你很可能会发现文档并不是它的强项之一。像所有在我之前的开发者一样，我只能一头扎进prototype.js的源代码中并且试验其中的每一个部分。我想当我学习他的时候记写笔记然后分享给其他人将会很不错。

我也一起提供了这个包的对象，类，方法和扩展的非官方参考。

2. 通用性方法
这个程序包里面包含了许多预定义的对象和通用性方法。编写这些方法的明显的目的就是为了减少你大量的重复编码和惯用法。

2.1. 使用 $()方法
$() 方法是在DOM中使用过于频繁的 document.getElementById() 方法的一个便利的简写，就像这个DOM方法一样，这个方法返回参数传入的id的那个元素。

比起DOM中的方法，这个更胜一筹。你可以传入多个id作为参数然后 $() 返回一个带有所有要求的元素的一个 Array 对象。下面的例子会向你描述这些。

Test Page

This is a paragraph

This is another paragraph

这个方法的另一个好处就是你可以传入id字符串或者元素对象自己，这使得在创建可以传入任何形式参数的方法的时候，它变得非常有用。

2.2. 使用$F()方法
$F()方法是另一个非常受欢迎的简写。它可以返回任何输入表单控件的值，如文本框或下拉框。这个方法可以传入元素的id或者元素自己。

2.3. 使用Try.these()方法
Try.these() 方法使得实现当你想调用不同的方法直到其中的一个成功正常的这种需求变得非常容易，他把一系列的方法作为参数并且按顺序的一个一个的执行这些方法直到其中的一个成功执行，返回成功执行的那个方法的返回值。

在下面的例子中， xmlNode.text在一些浏览器中好用，但是xmlNode.textContent在另一些浏览器中正常工作。使用Try.these()方法我们可以得到正常工作的那个方法的返回值。

3. Ajax 对象
上面提到的共通方法非常好，但是面对它吧，它们不是最高级的那类东西。它们是吗？你很可能自己编写了这些甚至在你的脚本里面有类似功能的方法。但是这些方法只是冰山一角。

我很肯定你对prototype.js感兴趣的原因很可能是由于它的AJAX能力。所以让我们解释当你需要完成AJAX逻辑的时候，这个包如何让它更容易。

Ajax 对象是一个预定义对象，由这个包创建，为了封装和简化编写AJAX 功能涉及的狡猾的代码。这个对象包含一系列的封装AJAX逻辑的类。我们来看看它们的一些。

3.1. 使用 Ajax.Request类
如果你不使用任何的帮助程序包，你很可能编写了整个大量的代码来创建XMLHttpRequest对象并且异步的跟踪它的进程，然后解析出响应然后处理它。当你不需要支持多于一种类型的浏览器时你会感到非常的幸运。

为了支持 AJAX 功能。这个包定义了 Ajax.Request 类。

假如你有一个应用程序可以通过url http://yoursever/app/get_sales?empID=1234&year=1998与服务器通信。它返回下面这样的XML 响应。

                1234
                1998-01
                $8,115.36


                1234
                1998-02
                $11,147.51



用 Ajax.Request对象和服务器通信并且得到这段XML是非常简单的。下面的例子演示了它是如何完成的。

你看到传入 Ajax.Request构造方法的第二个对象了吗？参数{method: 'get', parameters: pars, onComplete: showResponse} 表示一个匿名对象的真实写法。他表示你传入的这个对象有一个名为 method 值为 'get'的属性，另一个属性名为 parameters 包含HTTP请求的查询字符串，和一个onComplete 属性/方法包含函数showResponse。

还有一些其它的属性可以在这个对象里面定义和设置，如 asynchronous，可以为true 或 false 来决定AJAX对服务器的调用是否是异步的（默认值是 true）。

这个参数定义AJAX调用的选项。在我们的例子中，在第一个参数通过HTTP GET命令请求那个url，传入了变量 pars包含的查询字符串， Ajax.Request 对象在它完成接收响应的时候将调用showResponse 方法。

也许你知道， XMLHttpRequest在HTTP请求期间将报告进度情况。这个进度被描述为四个不同阶段：Loading, Loaded, Interactive, 或 Complete。你可以使 Ajax.Request 对象在任何阶段调用自定义方法，Complete 是最常用的一个。想调用自定义的方法只需要简单的在请求的选项参数中的名为 onXXXXX 属性/方法中提供自定义的方法对象。就像我们例子中的 onComplete 。你传入的方法将会被用一个参数调用，这个参数是 XMLHttpRequest 对象自己。你将会用这个对象去得到返回的数据并且或许检查包含有在这次调用中的HTTP结果代码的 status 属性。

还有另外两个有用的选项用来处理结果。我们可以在onSuccess 选项处传入一个方法，当AJAX无误的执行完后调用，相反的，也可以在onFailure选项处传入一个方法，当服务器端出现错误时调用。正如onXXXXX 选项传入的方法一样，这两个在被调用的时候也传入一个带有AJAX请求的XMLHttpRequest对象。

我们的例子没有用任何有趣的方式处理这个 XML响应，我们只是把这段XML放进了一个文本域里面。对这个响应的一个典型的应用很可能就是找到其中的想要的信息，然后更新页面中的某些元素，或者甚至可能做某些XSLT转换而在页面中产生一些HTML。

更完全的解释，请参照 Ajax.Request 参考和 Ajax选项参考。

3.2. 使用 Ajax.Updater 类
如果你的服务器的另一端返回的信息已经是HTML了，那么使用这个程序包中 Ajax.Updater 类将使你的生活变得更加得容易。用它你只需提供哪一个元素需要被AJAX请求返回的HTML填充就可以了，例子比我写说明的更清楚。

你可以看到，这段代码比前面的例子更加简洁，不包括 onComplete 方法，但是在构造方法中传入了一个元素id。我们来稍稍修改一下代码来描述如何在客户端处理服务器段错误成为可能。

我们将加入更多的选项，指定处理错误的一个方法。这个是用 onFailure 选项来完成的。

我们也指定了一个 placeholder 只有在成功请求之后才会被填充。为了完成这个目的我们修改了第一个参数从一个简单的元素id到一个带有两个属性的对象， success (一切OK的时候被用到) 和 failure (有地方出问题的时候被用到) 在下面的例子中没有用到failure属性，而仅仅在 onFailure 处使用了 reportError 方法。

如果你的服务器逻辑是返回JavaScript 代码而不是单纯的 HTML 标记， Ajax.Updater对象可以执行那段JavaScript代码。为了使这个对象对待响应为JavaScript，你只需在最后参数的对象构造方法中简单加入evalScripts: true属性。

更完全的解释，请参照 Ajax.Updater 参考和 Ajax选项参考。

4. prototype.js参考
4.1. JavaScript 类的扩展
prototype.js 包中加入功能的一种途径就是扩展已有的JavaScript 类。

4.2. 对 Object 类的扩展
Table 1. Object 类的扩展

方法类别参数描述
extend(destination, source) static destination: 任何对象, source: 任何对象用从 source 到 destination复制所有属性和方法的方式来提供一种继承机制。
extend(object) instance 任何对象用从传入的 object 中复制所有属性和方法的方式来提供一种继承机制。

4.3. 对 Number 类的扩展
Table 2. Number 类的扩展

方法类别参数描述
toColorPart() instance (none) 返回数字的十六进制描述，当在HTML中转换为RGB颜色组件到HTML中使用的颜色。

4.4. 对 Function 类的扩展
Table 3. 对 Function 类的扩展

方法类别参数描述
bind(object) instance object: 拥有这个方法的对象返回预先绑定在拥有该函数(=方法)的对象上的函数实例，返回的方法将和原来的方法具有相同的参数。
bindAsEventListener(object) instance object: 拥有这个方法的对象返回预先绑定在拥有该函数(=方法)的对象上的函数实例，返回的方法将把当前的事件对象作为它的参数。

让我们看看这些扩展的具体例子。

Test?
4.5. 对 String 类的扩展
Table 4. String 类的扩展

方法类别参数描述
stripTags() instance (none) 返回一个把所有的HTML或XML标记都移除的字符串。
escapeHTML() instance (none) 返回一个把所有的HTML标记回避掉的字符串。
unescapeHTML() instance (none) 和 escapeHTML()相反。

4.6. 对 document DOM 对象的扩展
Table 5. document DOM 对象的扩展

方法类别参数描述
getElementsByClassName(className) instance className: 关联在元素上的CSS类名返回给定的具有相同的CSS类名的所有元素。

4.7. 对 Event 对象的扩展
Table 6. Event 对象的扩展

属性类型描述
KEY_BACKSPACE Number 8: 常量，退格(Backspace)键的代码。
KEY_TAB Number 9: 常量，Tab键的代码。
KEY_RETURN Number 13: 常量，回车键的代码。
KEY_ESC Number 27: 常量， Esc键的代码。
KEY_LEFT Number 37: 常量，左箭头键的代码。
KEY_UP Number 38: 常量，上箭头键的代码。
KEY_RIGHT Number 39: 常量，右箭头键的代码。
KEY_DOWN Number 40: 常量，下箭头键的代码。
KEY_DELETE Number 46: 常量，删除(Delete)键的代码。
observers: Array 缓存的观察者的列表，这个对象内部具体实现的一部分。

Table 7. Event 对象的扩展

方法类别参数描述
element(event) static event: 事件对象返回引发这个事件的元素。
isLeftClick(event) static event: 事件对象如果鼠标左键单击返回true。
pointerX(event) static event: 事件对象返回在页面上x坐标。
pointerY(event) static event: 事件对象返回在页面上y坐标。
stop(event) static event: 事件对象用这个方法来中止事件的默认行为来使事件的传播停止。
findElement(event, tagName) static event: 事件对象, tagName: 指定标记的名字向 DOM 树的上位查找，找到第一个给定标记名称的元素，从这个元素开始触发事件。
observe(element, name, observer, useCapture) static element: 对象或者对象id, name: 事件名 (如 'click', 'load', etc), observer: 处理这个事件的方法, useCapture: 如果true, 在捕捉到事件的阶段处理事件那么如果 false在bubbling 阶段处理。加入一个处理事件的方法。
stopObserving(element, name, observer, useCapture) static element: 对象或者对象id, name: 事件名 (如 'click', 'load', etc), observer: 处理这个事件的方法, useCapture: 如果true, 在捕捉到事件的阶段处理事件那么如果 false在bubbling 阶段处理。删除一个处理实践的方法。
_observeAndCache( element, name, observer, useCapture) static 私有方法，不用管它。
unloadCache() static (none) 私有方法，不用管它。清除内存中的多有观察着缓存。

让我们看看怎样用这个对象加入处理 window 对象的load事件的处理方法。

4.8. 在 prototype.js中定义的新对象和类
另一个这个程序包帮助你的地方就是提供许多既支持面向对象设计理念又有共通功能的许多对象。

4.9. PeriodicalExecuter 对象
这个对象提供一定间隔时间上重复调用一个方法的逻辑。

Table 8. PeriodicalExecuter 对象

方法类别参数描述
[ctor](callback, interval) constructor callback: 没有参数的方法, interval: 秒数创建这个对象的实例将会重复调用给定的方法。

Table 9. PeriodicalExecuter 对象

属性类型描述
callback Function() 被调用的方法，该方法不会被传入参数。
frequency Number 以秒为单位的间隔。
currentlyExecuting Boolean 表示这个方法是否正在执行。

4.10. Prototype 对象
Prototype 没有太重要的作用，只是声明了该程序包的版本。

Table 10. The Prototype object

属性类型描述
Version String 包的版本。
emptyFunction Function() 空方法对象。

4.11. Class 对象
在这个程序包中 Class 对象在声明其他的类时候被用到。用这个对象声明类使得新类支持 initialize() 方法，他起构造方法的作用。

看下面的例子

//declaring the class
var MySampleClass = Class.create();
//defining the rest of the class implmentation
MySampleClass.prototype = {

   initialize: function(message) {
        this.message = message;
   },

   showMessage: function(ajaxResponse) {
      alert(this.message);
   }
};

//now, let's instantiate and use one object
var myTalker = new MySampleClass('hi there.');
myTalker.showMessage(); //displays alertTable 11. Class 对象

方法类别参数描述
create(*) instance (any) 定义新类的构造方法。

4.12. Ajax 对象
这个对象被用作其他提供AJAX功能的类的根对象。

Table 12. Ajax 对象

方法类别参数描述
getTransport() instance (none) 返回新的XMLHttpRequest 对象。

4.13. Ajax.Base 类
这个类是其他在Ajax对象中定义的类的基类。

Table 13. Ajax.Base 类

方法类别参数描述
setOptions(options) instance options: AJAX 选项设定AJAX操作想要的选项。
responseIsSuccess() instance (none) 返回 true 如果AJAX操作成功,否则为 false 。
responseIsFailure() instance (none) 与 responseIsSuccess() 相反。

4.14. Ajax.Request 类
继承自 Ajax.Base

封装 AJAX 操作

Table 14. Ajax.Request 类

属性类型类别描述
Events Array static 在AJAX操作中所有可能报告的事件/状态的列表。这个列表包括: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', 和 'Complete'。
transport XMLHttpRequest instance 携带AJAX操作的 XMLHttpRequest 对象。

Table 15. Ajax.Request 类

方法类别参数描述
[ctor](url, options) constructor url: 请求的url, options: AJAX 选项创建这个对象的一个实例，它将在给定的选项下请求url。重要：如果选择的url受到浏览器的安全设置，他会一点作用也不起。很多情况下，浏览器不会请求与当前页面不同主机(域名)的url。你最好只使用本地url来避免限制用户配置他们的浏览器(谢谢Clay)
request(url) instance url: AJAX 请求的url 这个方法通常不会被外部调用。已经在构造方法中调用了。
setRequestHeaders() instance (none) 这个方法通常不会被外部调用。被这个对象自己调用来配置在HTTP请求要发送的HTTP报头。
onStateChange() instance (none) 这个方法通常不会被外部调用。当AJAX请求状态改变的时候被这个对象自己调用。
respondToReadyState(readyState) instance readyState: 状态数字 (1 到 4) 这个方法通常不会被外部调用。当AJAX请求状态改变的时候被这个对象自己调用。

4.15. options 参数对象
AJAX操作中一个重要的部分就是 options 参数。本质上没有options类。任何对象都可以被传入，只要带有需要的属性。通常会只为了AJAX调用创建匿名类。

Table 16. options 参数对象

属性类型 Default 描述
method Array 'post' HTTP 请求方式。
parameters String '' 在HTTP请求中传入的url格式的值列表。
asynchronous Boolean true 指定是否做异步 AJAX 请求。
postBody String undefined 在HTTP POST的情况下，传入请求体中的内容。
requestHeaders Array undefined 和请求一起被传入的HTTP头部列表，这个列表必须含有偶数个项目，任何奇数项目是自定义的头部的名称，接下来的偶数项目使这个头部项目的字符串值。例子:['my-header1', 'this is the value', 'my-other-header', 'another value']
onXXXXXXXX Function(XMLHttpRequest) undefined 在AJAX请求中，当相应的事件/状态形成的时候调用的自定义方法。例如 var myOpts = {onComplete: showResponse, onLoaded: registerLoaded};. 这个方法将被传入一个参数，这个参数是携带AJAX操作的 XMLHttpRequest对象。
onSuccess Function(XMLHttpRequest) undefined 当AJAX请求成功完成的时候调用的自定义方法。这个方法将被传入一个参数，这个参数是携带AJAX操作的 XMLHttpRequest对象。
onFailure Function(XMLHttpRequest) undefined 当AJAX请求完成但出现错误的时候调用的自定义方法。这个方法将被传入一个参数，这个参数是携带AJAX操作的 XMLHttpRequest对象。
insertion Function(Object, String) null 为了把返回的文本注入到一个元素中而执行的方法。这个方法将被传入两个参数，要被更新的对象并且只应用于 Ajax.Updater的响应文本。
evalScripts Boolean undefined, false 决定当响应到达的时候是否执行其中的脚本块，只在 Ajax.Updater 对象中应用。
decay Number undefined, 1 决定当最后一次响应和前一次响应相同时在 Ajax.PeriodicalUpdater 对象中的减漫访问的次数，例如，如果设为2，后来的刷新和之前的结果一样，这个对象将等待2个设定的时间间隔进行下一次刷新，如果又一次一样，那么将等待4次，等等。不设定这个只，或者设置为1，将避免访问频率变慢。

4.16. Ajax.Updater 类
继承自 Ajax.Request

当请求的url返回一段HTML而你想把它直接放置到页面中一个特定的元素的时候被用到。如果url的返回将把 HTML 变为

Hello, Chief Wiggum. How's it going?4.23. Insertion.Top 类
继承自 Abstract.Insertion

在给定元素第一个子节点位置插入 HTML。内容将位于元素的开始标记的紧后面。

Table 25. Insertion.Top 类

方法类别参数描述
[ctor](element, content) constructor element: 元素对象或id, content: 被插入的HTML 继承自 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。

下面的代码

Hello, Wiggum. How's it going?

将把 HTML 变为

Hello, Mr. Wiggum. How's it going?4.24. Insertion.Bottom 类
继承自 Abstract.Insertion

在给定元素最后一个子节点位置插入 HTML。内容将位于元素的结束标记的紧前面。

Table 26. Insertion.Bottom 类

方法类别参数描述
[ctor](element, content) constructor element: 元素对象或id, content: 被插入的HTML 继承自 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。

下面的代码

Hello, Wiggum. How's it going?

将把 HTML 变为

Hello, Wiggum. How's it going? What's up?4.25. Insertion.After 类
继承自 Abstract.Insertion

在给定元素结束标记的后面插入HTML。

Table 27. Insertion.After 类

方法类别参数描述
[ctor](element, content) constructor element: 元素对象或id, content: 被插入的HTML 继承自 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。

下面的代码

Hello, Wiggum. How's it going?

将把 HTML 变为

Hello, Wiggum. How's it going? Are you there?4.26. Field 对象
这个对象提供操作表单中的输入项目的功能性方法。

Table 28. Field 对象

方法类别参数描述
clear(field1 [, field2 [, field3 [...]]]) instance fieldN: 元素对象或id 清除传入表单中项目元素的值。
present(field1 [, field2 [, field3 [...]]]) instance fieldN: 元素对象或id 只有在所有的表单项目都不为空时返回 true 。
focus(field) instance fieldN: 元素对象或id 移动焦点到给定的表单项目。
select(field) instance fieldN: 元素对象或id 选择支持项目值选择的表单项目的值。
activate(field) instance fieldN: 元素对象或id 移动焦点并且选择支持项目值选择的表单项目的值。

4.27. Form 对象
这个对象提供操作表单和他们的输入项目的功能性方法。

Table 29. Form 对象

方法类别参数描述
serialize(form) instance form: 表单元素或id 返回url参数格式的项目名和值的列表，如'field1=value1&field2=value2&field3=value3'。
getElements(form) instance form: 表单元素或id 返回包含所有在表单中输入项目的 Array 对象。
getInputs(form [, typeName [, name]]) instance form: 表单元素或id, typeName: 输入项目的类型, name: 输入项目的名称返回一个 Array 包含所有在表单中的元素。另外，这个列表可以对元素的类型或名字属性进行过滤。
disable(form) instance form: 表单元素或id 使表单中的所有输入项目无效。
enable(form) instance form: 表单元素或id 使表单中的所有输入项目有效。
focusFirstElement(form) instance form: 表单元素或id 激活第一个表单中可视的，有效的输入项目。
reset(form) instance form: 表单元素或id 重置表单。和调用表单对象的 reset() 方法一样。

4.28. Form.Element 对象
这个对象提供表单对象中的可视和非可视元素的功能性方法。

Table 30. Form.Element 对象

方法类别参数描述
serialize(element) instance element: 表单元素或id 返回元素的名称=值对, 如 'elementName=elementValue'。
getValue(element) instance element: 表单元素或id 返回元素的值。

4.29. Form.Element.Serializers 对象
这个对象提供了内部使用的用来协助解析出表单元素的当前值功能性方法。

Table 31. Form.Element.Serializers 对象

方法类别参数描述
inputSelector(element) instance element: 一个带有checked属性的表单元素或id，如 radio 或 checkbox。返回带有元素名称和值的 Array , 如 ['elementName', 'elementValue']
textarea(element) instance element: 一个带有value属性的表单元素或id，如 textbox, button 或 password 项目。返回带有元素名称和值的 Array , 如 ['elementName', 'elementValue']
select(element) instance element: 一个