prototype.js1.5.0开发者手册 译文+添加注释(六)

table.reference tr td, table.reference tr th
{
font-family:'Courier New', Courier, Monospace;
font-size:1.0em;
padding:1px 3px;
WORD-BREAK: keep-all;
}

.abcddd{
WORD-WRAP: break-word;
width:782px;
table-layout: fixed;

}

table.reference tr td.refDescription{font-family:Verdana, Arial, Helvetica;}

table.reference tr th
{
text-align:left;
font-family:Verdana, Arial, Helvetica;
background-color:#800;
color:#fff;
}

table.reference
{
margin:.5em 0 0 .5em;
border-collapse:collapse;
border-color:#800;
}

table.reference tr.privateMember td
{
color:#888;
}

.titleCol
{
background-color:#fff5f5 !important;
}
本人辛苦翻译的,转载或引用请短信通知下,谢谢!
自己没电脑,目前是借用别人的,没多少空闲时间翻译,但我一定会完成它
prototype.js1.5.0开发者手册 2007-09-22 by lin49940本人为学习的目的而翻译的

目录 [/u]

15. Field 对象
Form 对象
Form.Methods 对象
Form.Element 对象
Form.Element.Methods 对象
Form.Element.Serializers 对象
16. Abstract.TimedObserver 类
Form.Element.Observer 类
Form.Observer 类
Abstract.EventObserver 类
Form.Element.EventObserver 类
Form.EventObserver 类
Position 对象

Field 对象

这个对象提供一些操作表单中的输入项的功能性方法。他仅仅是 Form.Element 对象的一个实例
toc

Form 对象

这个对象提供一些操作表单输入数据和输入项的功能性方法.

方法	类别	参数	描述
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中第一个可用的表单项的元素。
getElements(form)	instance	form: form element object or id	返回一个包含表单中所有输入项的数组.
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.	返回一个包含表单中所有<input>元素的数组. 它不是强制的,你可以通过<input>元素的 type或者 name属性来过滤这个列表.
disable(form)	instance	form: form element object or id	把表单中的所有输入项变为不可用(其实就是把disabled属性便为true).
enable(form)	instance	form: form element object or id	把表单中的所有输入项变为可用(其实就是把disabled属性便为false).
focusFirstElement(form)	instance	form: form element object or id	把焦点交给给表单中第一个可见, 可用的输入项. (从代码来看,只有<input>, <select>, <textarea>这些输入项)
reset(form)	instance	form: form element object or id	重置表单。和调用form对象的 reset() 方法一样。(这里的reset()方法是form本身带的方法)

toc

Form.Element 对象

这个对象提供一些操作表单元素的功能性方法。这些方法和原生的 DOM方法是差不多的, 不过这些原生的方法在被调用后不返回元素本身, 阻碍了方法的链式调用.
在运行时, 这个对象中的方法不仅仅只有下面的方法而已. 所有 Form.Element.Methods 对象中的方法都将被添加到这个对象中.

方法	类别	参数	描述
focus(element)	instance	element: element object or id of a form field	把输入焦点移到元素上.
select(element)	instance	element: element object or id of a form field	选中<select>元素中的选项 . (这个是针对<select>的,上面是针对输入框的,这两个方法是以前版本没有的, 以前版本的两个方法放到 Form.Element.Methods 中了. )

toc

Form.Element.Methods 对象

这个对象提供一些操作表单域元素的功能性方法, 这个对象将被拷贝到任何通过 $() 和 $$() 方法访问的域元素上.
类似 Element.Methods 的方法, 当这些方法被拷贝时, 方法中的第一个参数将被去掉, 并且变为元素本身. 这些方法也是会被拷贝到 Form.Element 对象, 所以你不用特意通过 Form.Element.Methods 直接调用这些方法, 而是通过 Form.Element 对象兼容性的调用.

方法	类别	参数	描述
activate(element)	instance	element: element object or id	把输入焦点移到表单项上或者选中它的内容. (选中是针对非<input>,或者type属性不为'button','reset' 和 'submit'的表单项)
clear(element)	instance	element: element object or id	清空表单项的值.
disable(element)	instance	element: element object or id	把输入项或按钮变为不可用, 让他们不能被改变或点击.
enable(element)	instance	element: element object or id	把输入项或按钮变为可用,让他们能被改变或点击. (英文版中用了of, 应该是作者写错了吧, or 写成 of)
getValue(element)	instance	element: element object or id	返回元素的值
present(element)	instance	element: element object or id	判断表单项的值是否为空, 变为空返回true,否则返回false.
serialize(element)	instance	element: element object or id	返回元素的 名称=值 对, 如 'elementName=elementValue'。

toc

Form.Element.Serializers 对象

这个对象提供一些在库的内部中用于帮忙提取表单元素当前值的功能性方法.

方法	类别	参数	描述
inputSelector(element)	instance	element: 一个带有checked属性的表单元素或id， 如 radio 或 checkbox。	返回一个由元素名和值组成的数组, 例 ['elementName', 'elementValue'] (注意, 这个方法是针对radio 和 checkbox的)
textarea(element)	instance	element: 一个带有value属性的表单元素或id， 如 textbox, button 或 password 项目。	返回一个由元素名和值组成的数组, 例 ['elementName', 'elementValue'] (注意, 这个方法是针对textbox 、按钮 和 密码输入框的)
select(element)	instance	element: 一个<select> 元素对象或id。	返回一个由元素名和所有被选择的选项的值或文本组成的数组, 例 ['elementName', 'selOpt1 selOpt4 selOpt9'] (注意, 这个方法是针对<select>的)

toc

Abstract.TimedObserver 类

这个类是用于其它监听一个元素的值(或者任何类中涉及的属性)变化的类的基类，这个类像一个抽象类一样被使用。
子类可以被创建来监听如输入项目值，或style属性，或表格的行数，或者其他任何对跟踪变化相关的东西。
子类必须实现这个方法来决定什么才是被监听的元素的当前值。

方法	类别	参数	描述
[ctor](element, frequency, callback)	constructor	element: 元素对象或id, frequency: 以秒为单位的间隔, callback: 当元素改变的时候调用的方法。	创建一个监听元素的对象。
getValue()	instance, abstract	(none)	Derived classes have to implement this method to determine what is the current value being monitored in the element.
registerCallback()	instance	(none)	This method is typically not called externally. It is called by the object itself to start monitoring the element.
onTimerEvent()	instance	(none)	This method is typically not called externally. It is called by the object itself periodically to check the element.

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

toc

Form.Element.Observer 类

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

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

toc

Form.Observer 类

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

方法	类别	参数	描述
[ctor](form, frequency, callback)	constructor	form: 表单对象或id, frequency: 以秒为单位的间隔, callback: 当表单中任何数据项改变的时候调用的方法	继承自 Abstract.TimedObserver. 创建一个监听表单变化的对象。
getValue()	instance	(none)	返回所有表单数据的 名称=值 对, 如 'elementName=elementValue'。

toc

Abstract.EventObserver 类

这个类被用作其他一些类的基类，这些类具有在一个元素的值改变事件发生的时候执行一个回调方法这样的功能。
类 Abstract.EventObserver 的多个对象可以绑定到一个元素上，而不是一个对象取代另一个对象在元素上. 回调方法将按照这些对象附在元素上的顺序执行.
单选按钮和复选框的触发事件是 onclick ，而文本框和下拉列表框/下拉列表框的是 onchange 。
子类必须实现这个方法来决定什么才是被监听的元素的当前值。

方法	类别	参数	描述
[ctor](element, callback)	constructor	element: 元素对象或id, callback: 当事件发生的时候调用的方法。	创建监听元素的对象。
getValue()	instance, abstract	(none)	Derived classes have to implement this method to determine what is the current value being monitored in the element.
registerCallback()	instance	(none)	This method is typically not called externally. It is called by the object to bind itself to the element's event.
registerFormCallbacks()	instance	(none)	This method is typically not called externally. It is called by the object to bind itself to the events of each data entry element in the form.
onElementEvent()	instance	(none)	This method is typically not called externally. It will be bound to the element's event.

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

toc

Form.Element.EventObserver 类

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

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

toc

Form.EventObserver 类

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

方法	类别	参数	描述
[ctor](form, callback)	constructor	form: 表单对象或id, callback: 当表单中任何数据项改变的时候调用的方法.(1.3,1.4的译文这里写错了)	继承自 Abstract.EventObserver. 创建一个监听表单变化的对象。
getValue()	instance	(none)	返回所有表单数据的 名称=值 对, 如 'elementName=elementValue'。

toc

Position 对象

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

方法	类别	参数	描述
absolutize(element)	instance	element: element object or id	把对象的位置变成绝对的, 但确保不改变对象原来的大小,和在页面上的位置.(作者原文中的postioning 应该为positioning, 这个方法主要是把元素的position属性变为'absolute' , element.style.position = 'absolute';)
clone(source, target [, cloneOptions])	instance	source: element object or id, target: element object or id, cloneOptions: allow fine tuning of the operation	Resizes and repositions the target element identically to the source element. Note that the target element will only be repositioned if it already has the position style attribute set to absolute , otherwise only the size will change. Check the cloneOptions reference below.
cumulativeOffset(element)	instance	element: object	返回这个元素总的偏移量的 Array 对象， 包含任何相对或绝对定位的父元素全部偏移量。结果数组类似 [total_offset_left, total_offset_top](1.3和1.4的译文这里有问题)
offsetParent(element)	instance	element: object	返回元素第一个 position 属性不是 static 的祖先. (返回位置非静态的祖先, 如果没这样的祖先, 最后将返回 document.body)
overlap(mode, element)	instance	mode: 'vertical' or 'horizontal', element: object	within() needs to be called right before calling this method. This method will return a decimal number between 0.0 and 1.0 representing the fraction of the coordinate that overlaps on the element. As an example, if the element is a square DIV with a 100px side and positioned at (300, 300), then within(divSquare, 330, 330); overlap('vertical', divSquare); should return 0.70, meaning that the point is at the 70% (100px - 30px = 70px) mark from the bottom border of the DIV. The easiest way to understand it is to think of the given coordinate pair as the top-left corner of another rectangle, overlapping the first one. The number will be the percentage of the width or height that is overlapped (assuming that the second rectangle is large enough.)
page(element)	instance	element: object	返回这个元素相对于页面的坐标 。结果数组类似 [left, top]
positionedOffset(element)	instance	element: object	返回这个元素相对于相对或绝对定位的父元素的正确偏差的 Array 对象。结果数组类似 [left_offset, top_offset]
prepare()	instance	(none)	调整 deltaX 和 deltaY 属性来协调在滚动位置中的变化。 记得在页面滚动之后的任何调用的withinIncludingScrolloffset 之前调用这个方法。
realOffset(element)	instance	element: object	返回这个元素的正确滚动偏差的 Array 对象， 包括所有影响元素的滚动偏差。结果数组类似 [total_scroll_left, total_scroll_top]
relativize(element)	instance	element: element object or id	把对象的位置变成相对的, 但确保不改变对象原来的大小,和在页面上的位置. 这个方法最好是应用在先前位置被绝对化的元素上. (作者原文中的postioning 应该为positioning, 这个方法主要是把元素的position属性变为'relative' , element.style.position = 'relative';)
within(element, x, y)	instance	element: 对象, x 和 y: 一个点的坐标	测试给定的点的坐标是否在给定的元素的外部矩形范围之内。
withinIncludingScrolloffsets(element, x, y)	instance	element: 对象, x 和 y: 一个点的坐标	测试给定的点的坐标是否在给定的元素的外部带有滚动条的矩形范围之内。

toc

The cloneOptions argument object

The clone() method of the Position object takes an optional third argument, used to more detailedly control the cloning operation.

Property	Type	Default	Description
offsetLeft	Number	0	Number of pixels to offset the target element from the left of the source.
offsetTop	Number	0	Number of pixels to offset the target element from the top of the source.
setHeight	Boolean	true	Causes the height of the source element to be copied over to the target element.
setLeft	Boolean	true	Causes the left position of the source element to be copied over to the target element.
setTop	Boolean	true	Causes the top position of the source element to be copied over to the target element.
setWidth	Boolean	true	Causes the width of the source element to be copied over to the target element.

toc

V1.5.0的文件还在不停地更新中. 本文档也会进行同步的更新. 如果你发现错误，过失或信息不完全，或平淡无意义的东西，请 通知作者 ，作者会尽可能快的修正它.
上一部分: prototype.js1.5.0开发者手册 译文+添加注释(五)
查考文章: https://compdoc2cn.dev.java.net/prototype/html/prototype.js.cn.html
http://thinhunan.cnblogs.com/archive/2006/04/01/DeveloperNotesForPrototype.html
英文原版: http://www.sergiopereira.com/articles/prototype.js.html