prototype.js1.5.0开发者手册 译文+添加注释(六)
本人辛苦翻译的,转载或引用请短信通知下,谢谢!
自己没电脑,目前是借用别人的,没多少空闲时间翻译,但我一定会完成它
prototype.js1.5.0开发者手册 2007-09-22 by lin49940本人为学习的目的而翻译的
目录
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