prototype.js1.5.0开发者手册 译文+添加注释(五)
本人辛苦翻译的,转载或引用请短信通知下,谢谢!
自己没电脑,目前是借用别人的,没多少空闲时间翻译,但我一定会完成它
prototype.js1.5.0开发者手册 2007-09-22 by lin49940本人为学习的目的而翻译的
目录
12. Element 对象
Element.Methods 对象
Element.ClassNames 类
13. Abstract 对象
Abstract.Insertion 类
14. Insertion 对象
Insertion.Before 类
Insertion.Top 类
Insertion.Bottom 类
Insertion.After 类
top
Element 对象
这个对象提供在操作DOM中元素时使用的功能性方法。
Element.Methods 对象
这个对象提供在操作DOM中元素时使用的功能性方法。这些方法的最大特点是，你不是从Element.Methods 对象中直接调用，而是从Element 对象中调用，Element 对象拥有所有方法的拷贝。
这里所有定义的方法将自动地添加到任何被选取的使用$() 方法的对象。当这些方法被添加到元素中的时候，第一个参数(一般是element )将被移除，因为它一般是当前元素本身。所以，Element.show('myDiv'); 能简短地写出 $('myDiv').show(); ，两者的作用一样。
| 方法 | 类别 | 参数 | 描述 |
|---|---|---|---|
| addClassName(element, className) | instance | element: element object or id, 元素对象或id，className: name of a CSS class，CSS样式类名。 | 添加指定的CSS样式类名到元素的class属性中 |
| ancestors(element) | instance | element: element object or id | 返回由元素所有的祖宗(父节点)组成的数组. 这个数组由第一个直系的父元素开始, 通过所有路径一直到html元素. |
| childOf(element, ancestor) | instance | element: element object or id, ancestor: ancestor candidate element or id | Same as descendantOf. |
| classNames(element) | instance | element: element object or id | 返回一个表现指定元素关联的CSS样式类名的Element.ClassNames 对象 |
| cleanWhitespace(element) | instance | element: element object or id | 删除该元素的所有只有空格的子文本节点。 |
| descendantOf(element, ancestor) | instance | element: element object or id, ancestor: ancestor candidate element or id |
返回一个布尔值表示该元素是否是指定ancestor的子孙(孩子,孙子等). |
| descendants(element) | instance | element: element object or id | 返回一个由该元素所有子孙(子节点-孩子,孙子等)组成的数组. |
| down(element, expression, index) | instance | element: element object or id, expression: a CSS selection rule, index: index of the returned descendant | 检测该元素的子孙哪些匹配指定的规则, 并返回第一个检测到的子孙或者通过index(从0开始)参数指定位置的子孙. 索引(index)值越低意味着该子孙越接近该元素. |
| empty(element) | instance | element: element object or id | 返回一个布尔值表示该元素的标记是否为空(或者只是空格) |
| getDimensions(element) | instance | element: element object or id | 返回该元素的尺寸. 返回的值是一个带两个属性:height 和 width的对象 |
| getElementsByClassName(element, className) | instance | element: element object or id, className: CSS class name | 返回一个由该元素中所有把指定CSS样式类名作为class属性中的一个的子元素组成的数组. |
| getElementsBySelector(element, expression1 [, expression2 [, expression3]]) | instance | element: element object or id, expressionN: CSS selection rule |
返回一个由该元素中所有匹配指定CSS选择器其中一个的子元素组成的数组. |
| getHeight(element) | instance | element: element object or id | 返回该元素的偏移高度(offsetHeight) |
| getStyle(element, cssProperty) | instance | element: element object or id, cssProperty name of a CSS property (either format 'prop-name' or 'propName' works). | 返回指定元素的CSS中cssProperty参数指定的属性的值, 如果指定的cssProperty不存在,返回null
|
| hasClassName(element, className) | instance | element: element object or id, className: name of a CSS class | 返回true, 如果该元素有指定的CSS样式类名作为它class属性中的一个. |
| hide(element) | instance | element: element object or id | 通过设置元素的style.display 为'none '来隐藏该元素. |
| immediateDescendants(element) | instance | element: element object or id | 返回一个由该元素所有直系的子孙(只限于第一层的子节点)组成的数组. |
| inspect(element) | instance | element: element object or id | 返回一个该元素的标记的简单字符串表现. 这个方法在调试时很有用, 注意这个方法返回的标记只是包括元素的id和css类名, 像<p id="result" class="hilite numeric"> (上面的例子就是一个完整的返回结果,<p>里面有很多的标记,也只是显示id 和 class,如果没class,就只显示id) |
| makeClipping(element) | instance | element: element object or id | 设置该元素的 style.overflow值为 'hidden',通过这个方法设定元素内容溢出其区域时进行修剪. (英文原版是没对这个方法描述的,以上是在阅读源代码后,lin49940自己添加的,) |
| makePositioned(element) | instance | element: element object or id | 设置该元素的 style.position值为 'relative' (位置被设置为relative的元素，可将其移至相对于其正常位置的地方，因此"left:20"会将元素移至元素正常位置左边20个像素的位置。) |
| match(element, selector) | instance | element: element object or id, selector: string or Selector object of a CSS rule | 校验该元素是否匹配指定的CSS选择器规则. 例如, 带有一个id为'message' (<p id='message'>) 的段落元素将跟选择器'p#message' 匹配(跟'#message'也匹配,如果是<p id='message' class='abc'>,那就可以跟'.abc' 匹配了,好像只能匹配CSS id选择器和class选择器，派生选择器不行). 这个方法返回的结果是true 或 false; () |
| next(element, expression, index) | instance | element: element object or id, expression: a CSS selection rule, index: index of the returned sibilng | 检测该元素下面的同类型元素哪个匹配指定的规则，并返回检测到的第一个元素或第N个元素, N由index(从零开始)参数指定. 索引(index)值越低意味着返回的元素越接近该元素.(注意原文的sibilings写错了，应该是siblings) |
| nextSiblings(element) | instance | element: element object or id | 返回一个由该元素下面的同类型元素组成的数组. 这个列表是通过nextSibling属性递归地查找所有其它元素. |
| observe(element, name, observer, useCapture) | instance | element: object or id, name: event name (like 'click', 'load', etc), observer: function(evt) to handle the event, useCapture: if true, handles the event in the capture phase and if false in the bubbling phase. | Shortcut for Event.observe. |
| previous(element, expression, index) | instance | element: element object or id, expression: a CSS selection rule, index: index of the returned sibilng | 检测该元素上面的同类型元素哪个匹配指定的规则，并返回检测到的第一个元素或第N个元素, N由index(从零开始)参数指定. 索引(index)值越低意味着返回的元素越接近该元素.(注意原文的sibilings写错了，应该是siblings) |
| previousSiblings(element) | instance | element: element object or id | 返回一个由该元素上面的同类型元素组成的数组. 这个列表是通过previousSibling属性递归地查找所有其它元素. |
| remove(element) | instance | element: element object or id | 从document对象中删除指定的元素。 |
| removeClassName(element, className) | instance | element: element object or id, className: name of a CSS class | 从元素的类名中删除指定的类名. |
| replace(element, html) | instance | element: element object or id, html: html content | 通过指定的html参数替换该元素的整个html部分. 如果指定的html 包含<script>脚本块, 这些脚本块不会被包括进去, 但是他们将被执行. |
| scrollTo(element) | instance | element: element object or id | 滚动窗口到元素的位置. |
| setStyle(element, cssPropertyHash) | instance | element: element object or id, cssPropertyHash Hash object with the styles to be applied. | 通过cssPropertyHash 参数提供的值, 设置指定的元素的CSS属性的值 |
| show(element) | instance | element: element object or id | 通过设置元素的style.display 为 ' ' 显示元素. |
| siblings(element) | instance | element: element object or id | 返回一个由元素前后的同胞组成的数组. |
| stopObserving(element, name, observer, useCapture) | instance | element: object or id, name: event name (like 'click', 'load', etc), observer: function(evt) to handle the event, useCapture: if true, handles the event in the capture phase and if false in the bubbling phase. | Shortcut for Event.stopObserving. |
| toggle(element) | instance | element: element object or id | 切换元素的可视性.(其实还是通过display属性而不是visible属性) |
| toggleClassName(element, className) | instance | element: element object or id, className: CSS class | 对元素中存在的class属性的CSS名和指定的CSS名进行切换.(转化css样式,如果className是原来的css样式名,那就会切换为空的样式) |
| undoClipping(element) | instance | element: element object or id | style.overflow的值返回上一个设定值。(原文这里没说明, 这个函数是撤销makeClipping(element)的操作的) |
| undoPositioned(element) | instance | element: element object or id | 把元素的 style.position 设置为 ' '.(style.top,style.left,style.bottom,style.righty也一起设置为' ') |
| up(element, expression, index) | instance | element: element object or id, expression: a CSS selection rule, index: index of the returned ancestor | 检测元素的哪个祖先匹配指定的规则, 并返回第一个检测到的祖先,或者是通过index(从0开始)参数指定的第N个祖先. index 越低意味着返回的祖先越接近元素. |
| update(element, html) | instance | element: element object or id, html: html content | 通过html 参数指定的html内容替换元素的innerHtml(网页文本).如果指定的html内容包含<script>脚本, 这些脚本将不会被包含进来, 但是他们将会被执行. (如果html内容中有</script>要写成<//script>) |
| visible(element) | instance | element: element object or id | 返回一个布尔值标志元素是否可见 |
你能添加你增加的方法到 Element.Methods 对象中, 并且这些方法也会自动被拷贝到 Elements 对象中. 你所需要做的只是确保你的方法的第一个参数是element, (如果可能的话)并返回元素本身. 下面就是一个教你如何添加新方法的例子. 我将添加3个新的实用方法到元素中.
//
first a helper method
var
$CE
=
function
(tagName, attributes, styles)
...
{ //short for create element
var el = document.createElement(tagName);
if (attributes)
$H(attributes).each(function(pair)...{
eval("el." + pair.key + "='" + pair.value + "'");
});
if (styles)
$H(styles).each(function(pair)...{
el.style[pair.key] = pair.value;
});
return $(el);
}
;
//
adding he new methods
Element.addMethods(
...
{
//removes any child noes from the element
//example: <div id="myDiv"><b>hello</b></div>
// $('myDiv').clearChildren();
// ==> <div id="myDiv"></div>
clearChildren: function(element) ...{
element = $(element);
$A(element.childNodes).each(function(e)...{
e.parentNode.removeChild(e);
});
return element;
},
//method that creates a new element and appends to the current element
// example: <div id="myDiv">Please</div>
// $('myDiv').append('A',{href:'otherpage.html', className:'red'}).update('Continue...');
// ==> <div id="myDiv">Please<a href="otherpage.html" class="red">Continue...</a></div>
append: function(element, tagName, attributes, styles) ...{
element = $(element);
var newEl = $CE(tagName, attributes, styles);
element.appendChild(newEl);
return newEl;//<-- this one returns the new element
},
//appends a text node to the element
// example: <div id="myDiv"><b>hello</b></div>
// $('myDiv').appendText(', John');
// ==> <div id="myDiv"><b>hello</b>, John</div>
appendText: function(element, text)...{
element = $(element);
var t = document.createTextNode(text);
element.appendChild(t);
return element;
}
}
);
toc
Element.ClassNames 类
继承 Enumerable
表现跟元素关联的CSS class names的集合.
| 方法 | 类别 | 参数 | 描述 |
|---|---|---|---|
| [ctor](element) | constructor 构造器 |
element: any DOM element object or id | 创建一个Element.ClassNames 对象，这个对象将代表指定的元素的CSS class names |
| add(className) | instance | className: a CSS class name | 把指定的CSS class name包含到元素关联的class names列表中. |
| remove(className) | instance | className: a CSS class name | 从元素关联的class names列表中移除指定的CSS class name |
| set(className) | instance | className: a CSS class name | 把元素跟指定的CSS class name关联, 移除元素的其它class names. |
toc
Abstract 对象
这个对象是这个程序包中其他类的根。它没有任何属性和方法。在这个对象中定义的类可以被视为传统的抽象类。
toc
The Abstract.Insertion 类
这个类被用作其他提供动态内容插入功能的类的基类，它像一个抽象类一样被使用。
| 方法 | 类别 | 参数 | 描述 |
|---|---|---|---|
| [ctor](element, content) | constructor | element: 元素对象或id, content: 被插入的HTML | 创建一个可以帮助插入动态内容的对象 |
| contentFromAnonymousTable() | instance | (none) | (这里作者没做说明,这是个内部私方法,通过创建一个div,并把content放到匿名的table中,方法的返回值是content,所谓匿名就是<table></table>这样没有其它的table了) |
| 属性 | 类型 | 类别 | 描述 |
|---|---|---|---|
| adjacency | String | static, parameter | 这个参数指定插入的内容将被放置到相对于指定元素的哪个位置. 可选的值是: 'beforeBegin', 'afterBegin', 'beforeEnd' 和 'afterEnd'. |
| element | Object | instance | 与插入内容位置相对的元素对象。 |
| content | String | instance | 将被插入的 HTML 。 |
toc
Insertion 对象
这个对象是这个程序包中其他类的根。它没有任何属性和方法。在这个对象中定义的类仍然可以被视为传统的抽象类。(跟上面的 Abstract 对象 描述一模一样, 不知道作者有没搞错!)
toc
Insertion.Before 类
继承 Abstract.Insertion
在指定元素的标记<...>前面插入HTML.
| 方法 | 类别 | 参数 | 描述 |
|---|---|---|---|
| [ctor](element, content) | constructor | element: element object or id, content: HTML to be inserted | 继承 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。 |
下面的代码
<br/>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script> new Insertion.Before('person', 'Chief '); </script>
将把 HTML 变为
<br/>Hello, Chief <span id="person" style="color:red;">Wiggum. How's it going?</span>
toc
Insertion.Top 类
继承 Abstract.Insertion
在指定元素第一个子节点位置插入 HTML。内容将位于元素的开始标记<...> 的后面。
| 方法 | 类别 | 参数 | 描述 |
|---|---|---|---|
| [ctor](element, content) | constructor | element: element object or id, content: HTML to be inserted | 继承自 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。 |
下面的代码
<br/>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script> new Insertion.Top('person', 'Mr. '); </script>
将把 HTML 变为
<br/>Hello, <span id="person" style="color:red;">Mr. Wiggum. How's it going?</span>
toc
Insertion.Bottom 类
继承 Abstract.Insertion
在指定元素最后一个子节点位置插入 HTML。内容将位于元素的结束标记</..>的前面。
| 方法 | 类别 | 参数 | 描述 |
|---|---|---|---|
| [ctor](element, content) | constructor | element: element object or id, content: HTML to be inserted | 继承自 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。 |
下面的代码
<br/>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> <script> new Insertion.Bottom('person', " What's up?"); </script>
将把 HTML 变为
<br/>Hello, <span id="person" style="color:red;">Wiggum. How's it going? What's up?</span>
toc
Insertion.After 类
继承 Abstract.Insertion
在指定元素结束标记</...>的后面插入HTML。
| 方法 | 类别 | 参数 | 描述 |
|---|---|---|---|
| [ctor](element, content) | constructor | element: element object or id, content: HTML to be inserted | 继承自 Abstract.Insertion. 创建一个可以帮助插入动态内容的对象。 |
下面的代码
<br/>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>
<script> new Insertion.After('person', ' Are you there?'); </script>
将把 HTML 变为
<br/>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> Are you there?
toc
上一部分: 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