prototype.js 开发笔记 （二）

Chapter 2. prototype.js参考

2.1. JavaScript 类的扩展

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

2.2. 对 Object 类的扩展

Table 2.1. Object 类的扩展

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

2.3. 对 Number 类的扩展

Table 2.2. Number 类的扩展

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

2.4. 对 Function 类的扩展

Table 2.3. 对 Function 类的扩展

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

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

 Test?

2.5. 对 String 类的扩展

Table 2.4. String 类的扩展

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

2.6. 对 document DOM 对象的扩展

Table 2.5. document DOM 对象的扩展

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

2.7. 对 Event 对象的扩展

Table 2.6. Event 对象的扩展

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

Table 2.7. Event 对象的扩展

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

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

2.8. 在 prototype.js中定义的新对象和类

另一个这个程序包帮助你的地方就是提供许多既支持面向对象设计理念又有共通功能的许多对象。

2.9. PeriodicalExecuter 对象

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

Table 2.8. PeriodicalExecuter 对象

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

Table 2.9. PeriodicalExecuter 对象

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

2.10. Prototype 对象

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

Table 2.10. The Prototype object

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

2.11. Class 对象

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

看下面的例子

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

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

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

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

Table 2.11. Class 对象

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

2.12. Ajax 对象

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

Table 2.12. Ajax 对象

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

2.13. Ajax.Base 类

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

Table 2.13. Ajax.Base 类

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

2.14. Ajax.Request 类

继承自 Ajax.Base

封装 AJAX 操作

Table 2.14. Ajax.Request 类

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

Table 2.15. Ajax.Request 类

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

2.15. options 参数对象

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

Table 2.16. options 参数对象

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

2.16. Ajax.Updater 类

继承自 Ajax.Request

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

将把 HTML 变为

Hello, Chief Wiggum. How's it going?

2.23. Insertion.Top 类

继承自 Abstract.Insertion

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

Table 2.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?

2.24. Insertion.Bottom 类

继承自 Abstract.Insertion

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

Table 2.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?

2.25. Insertion.After 类

继承自 Abstract.Insertion

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

Table 2.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?

2.26. Field 对象

这个对象提供操作表单中的输入项目的功能性方法。

Table 2.28. Field 对象

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

2.27. Form 对象

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

Table 2.29. Form 对象

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

2.28. Form.Element 对象

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

Table 2.30. Form.Element 对象

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

2.29. Form.Element.Serializers 对象

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

Table 2.31. Form.Element.Serializers 对象

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

2.30. Abstract.TimedObserver 类

这个类是用于其它监听一个元素的值(或者任何类中涉及的属性)变化的类的基类，这个类像一个抽象类一样被使用。

子类可以被创建来监听如输入项目值，或style属性，或表格的行数，或者其他任何对跟踪变化相关的东西。

子类必须实现这个方法来决定什么才是被监听的元素的当前值。

Table 2.32. Abstract.TimedObserver 类

方法	类别	参数	描述
[ctor](element, frequency, callback)	constructor	element: 元素对象或id, frequency: 以秒为单位的间隔, callback: 当元素改变的时候调用的方法。	创建一个监听元素的对象。
registerCallback()	instance	(none)	这个方法通常不会被外部调用。 被这个对象自己调用来开始监听那个元素。
onTimerEvent()	instance	(none)	这个方法通常不会被外部调用。 被这个对象自己调用来周期性的检查那个元素。

Table 2.33. Abstract.TimedObserver 类

属性	类型	描述
element	Object	被监听的元素对象。
frequency	Number	每次检查中的以秒为单位的时间间隔。
callback	Function(Object, String)	只要元素改变这个方法就会被调用。 会接收到元素对象和新值作为参数。
lastValue	String	元素被核实的最后一个值。

2.31. Form.Element.Observer 类

继承自 Abstract.TimedObserver

Abstract.TimedObserver 的一个实现类用来监听表单输入项目的值的变化。当你想监听一个没有带报告值变化事件的元素的时候使用这个类。否则的话使用 Form.Element.EventObserver 类代替。

Table 2.34. Form.Element.Observer 类

方法	类别	参数	描述
[ctor](element, frequency, callback)	constructor	element: 元素对象或id, frequency: 以秒为单位的间隔, callback: 当元素改变的时候调用的方法。	继承自 Abstract.TimedObserver. 创建一个监听元素值属性的对象。
getValue()	instance	(none)	返回元素的值。

2.32. Form.Observer 类

继承自 Abstract.TimedObserver

Abstract.TimedObserver 的一个实现类用来监听表单中任何数据项的值的变化。当你想监听一个没有带报告值变化事件的元素的时候使用这个类。 否则的话使用类 Form.EventObserver 代替。

Table 2.35. Form.Observer 类

方法	类别	参数	描述
[ctor](form, frequency, callback)	constructor	form: 表单对象或id,	继承自 Abstract.TimedObserver. 创建一个监听表单变化的对象。
getValue()	instance	(none)	返回所有表单数据的一系列值。

2.33. Abstract.EventObserver 类

这个类被用作其他一些类的基类，这些类具有在一个元素的值改变事件发生的时候执行一个回调方法这样的功能。

类 Abstract.EventObserver 的多个对象可以绑定到一个元素上，不是一个帮其他的擦出了，而是按照他们付给元素的顺序执行这些回调方法。

单选按钮和复选框的触发事件是 onclick ，而文本框和下拉列表框/下拉列表框的是 onchange 。

子类必须实现这个方法来决定什么才是被监听的元素的当前值。

Table 2.36. Abstract.EventObserver 类

方法	类别	参数	描述
[ctor](element, callback)	constructor	element: 元素对象或id, callback: 当事件发生的时候调用的方法。	创建监听元素的对象。
registerCallback()	instance	(none)	这个方法通常不会被外部调用。 被对象调用来把自己绑定到元素的事件上。
registerFormCallbacks()	instance	(none)	这个方法通常不会被外部调用。 被对象调用来把自己绑定到表单中的每一个数据项元素的事件上。
onElementEvent()	instance	(none)	这个方法通常不会被外部调用。 将被绑定到元素的事件上。

Table 2.37. Abstract.EventObserver 类

属性	类型	描述
element	Object	被监听的元素对象。
callback	Function(Object, String)	只要元素改变就调用的方法。会接收到元素对象和新值作为参数。
lastValue	String	元素被核实的最后一个值。

2.34. Form.Element.EventObserver 类

继承自 Abstract.EventObserver

Abstract.EventObserver 的一个实现类，它在监测到表单中数据项元素的值改变的相应事件时候执行一个回调方法。 如果元素没有任何报告变化的事件，那么你可以使用 Form.Element.Observer 类代替。

Table 2.38. Form.Element.EventObserver 类

方法	类别	参数	描述
[ctor](element, callback)	constructor	element: 元素对象或id, callback: 当事件发生的时候调用的方法。	继承自 Abstract.EventObserver。 创建一个监听元素值属性的对象。
getValue()	instance	(none)	返回元素的值。

2.35. Form.EventObserver 类

继承自 Abstract.EventObserver

Abstract.EventObserver 的一个实现类，监听表单对象中包含的任何对象的任何变化，用元素的事件检测值的变化。如果元素没有任何报告变化的事件， 那么你可以使用 Form.Observer 类代替。

Table 2.39. Form.Element.EventObserver 类

方法	类别	参数	描述
[ctor](form, callback)	constructor	form: 元素对象或id, callback: 当表单中任何数据项改变的时候调用的方法	继承自 Abstract.EventObserver。 创建一个监听元素值属性的对象。
getValue()	instance	(none)	返回所有表单数据的一系列值。

2.36. Position 对象 (预备文档)

这个对象提供许多和元素位置相关的方法。

Table 2.40. Position 对象 (预备文档)

方法	类别	参数	描述
prepare()	instance	(none)	调整 deltaX 和 deltaY 属性来协调在滚动位置中的变化。 记得在页面滚动之后的任何调用的withinIncludingScrolloffset 之前调用这个方法。
realOffset(element)	instance	element: 对象或id	返回这个元素的正确滚动偏差的 Array 对象， 包括所有影响元素的滚动偏差。结果数组类似 [total_scroll_left, total_scroll_top]
cumulativeOffset(element)	instance	element: 对象或id	回这个元素的正确滚动偏差的 Array 对象， 包含任何被放置的父元素强加偏差。结果数组类似 [total_offset_left, total_offset_top]
within(element, x, y)	instance	element: 对象, x 和 y: 一个点的坐标	测试给定的点的坐标是否在给定的元素的外部矩形范围之内。
withinIncludingScrolloffsets(element, x, y)	instance	element: object, x and y: coordinates of a point
overlap(mode, element)	instance	mode: 'vertical' 或 'horizontal', element: 对象	在调用这个方法之前需要调用within() 。这个方法返回0.0到1.0之间的数字，来表示坐标在元素重叠的分数。 举个例子，如果元素是一个边长是100px的正方形的DIV，并且位于(300, 300), 然后 within(divSquare, 330, 330)；overlap('vertical', divSquare); 会返回 0.10，意思是那个点位于DIV顶部边框以下 10% (30px) 的位置上。
clone(source, target)	instance	source: 元素对象或 id, target: 元素对象或id	改变目标元素的大小尺寸和位置与源元素的相同。

如果你发现错误，过失或信息不完全，或平淡无意义的东西，请 ，作者会尽可能快的修正它，作者仍然在写其他没写的类，来保持一致。 任何翻译的过失，不足，词不达意，表达含糊等请，我会再加斟酌，找到合适的描述。