Element.Methods - Prototype JavaScript 框架

absolutize(element) -> HTMLElement

转换元素的定位方式为绝对定位，并且不改变元素在页面中的位置。
译注：该方法使用代码 element.style.position = 'absolute' 改变定位方式。在改变定位方式后， 元素左上角的坐标仍会保持原来的位置，如果元素未设置初始的 width 和 height 属性，则调用该方法后， 元素的宽度和高度会改变为系统预设值。

addClassName(element, className) -> HTMLElement 

增加一个 CSS 类到 element 中。

Element.adjacent(element[, selectors...]) -> [HTMLElement...]
someElement.adjacent([selectors...]) -> [HTMLElement...]

查找当前元素的所有兄弟节点，若指定选择器，则这些节点必须与给定的选择器（selectors）相匹配。
译注：该方法可同时查询前导兄弟节点和后继兄弟节点。

ancestors(element) -> [HTMLElement...]

返回 element 的所有先代节点（父节点、父节点的父节点...一直到最顶层节点），结果为一个数组，数组元素已经过 扩展。

childElements(element) -> [HTMLElement...]

返回元素的所有子元素，结果为一个数组，数组元素已经过 扩展。

classNames(element) -> Enumerable

返回一个新的 ClassNames 的实例，该实例是一个 Enumerable 对象，用于读写元素的 CSS 类名称。

cleanWhitespace(element) -> HTMLElement

移除元素中所有仅包含空白的文本节点，返回移除空白文本节点后的元素。
译注：所谓空白文本节点，是根据 XML 中的概念得来的，例如，有以下 HTML 代码：

<div>
	<p>第一段</p>
</div>

<div> 的子节点（element.childNodes）包括 <p> 和空白文本节点（对于空白文本节点，各种浏览器的处理方式不一样）, 这些空白文本节点有时对处理节点的顺序关系会造成影响，如上述 HTML 代码中我们通常认为 <p> 没有前导和后继兄弟节点， 但因为空白文本节点的干扰，程序可能会认为 <p> 有一个前导兄弟节点和一个后继兄弟节点。为消除这些干扰因素，Prototype 提供了 cleanWhitespace 方法，用于去除无用的空白文本节点。

clonePosition(element, source[, options]) -> HTMLElement

从 source 中复制参数 options 指定的位置和/或尺寸的相关信息到 element。

cumulativeOffset(element) -> [Number, Number] 或 { left: Number, top: Number }

返回 element 相对于页面左上角的坐标。
译注：假定返回值为 offset，则 X 轴坐标可通过 offset[0] 获取，也可以通过 offset.left 获取，Y 轴坐标可通过 offset[1] 获取，也可通过 offset.top 获取。

cumulativeScrollOffset(element) -> [Number, Number] 或 { left: Number, top: Number }

在内含滚动条的容器中计算元素的累积滚动偏移值。
译注：假定返回值为 offset，则 X 轴坐标可通过 offset[0] 获取，也可以通过 offset.left 获取，Y 轴坐标可通过 offset[1] 获取，也可通过 offset.top 获取。

descendantOf(element, ancestor) -> Boolean 

判断 element 是否是参数 ancestor 指定元素的后代节点。

descendants(element) -> [HTMLElement...]

返回 element 的所有后代节点，结果为一个数组，数组元素已经过 扩展。

down(element[, cssRule][, index = 0]) -> HTMLElement | undefined

返回 element 下与 cssRule 相匹配的第一个后代节点（如果指定 index 参数，则返回第 index 个）。如果未指定 cssRule，则默认匹配所有后代节点。如果没有符合条件的后代节点，返回 undefined。

empty(element) -> Boolean

测试 element 是否为空（例如仅包含空白）。

fire(eventName[, memo]) -> Event

在当前元素上触发一个自定义事件。

firstDescendant(element) -> HTMLElement

返回第一个子元素。与 DOM 属性 firstChild 不同，firstChild 返回任意类型的节点（在很多情形下， 经常是一个空白文本节点[译注：这种情况在 Firefox 中较为常见]）。

getDimensions(element) -> {height: Number, width: Number}

获取 element 的 width 和 height，并返回一个对象，包括宽高的名值对。

getElementsByClassName(element, className) -> [HTMLElement...]

查询 element 下所有具有参数 className 指定的 CSS 类名称的后代节点，并返回一个数组， 数组中的元素已经过 扩展。

getElementsBySelector(element, selector...) -> [HTMLElement...]

根据一个或多个指定的 CSS 选择器（字符串），在 element 中查找匹配其中任何一个选择器的后代节点， 并返回一个数组，数组中的元素已经过 扩展。

getHeight(element) -> Number

获取 element 的高度。

getOffsetParent(element) -> HTMLElement

返回 element 的容器块（Containing Block）（译注：距离元素最近的 CSS position 属性为 relative 或 absolute 的先代节点）节点，如果不存在这样一个节点，则返回 body 元素。

getStyle(element, property) -> String | null

返回 element 的指定 CSS 属性值。property 可以用标准的 CSS 名称指定，也可以使用 camelized 命名方式指定（译注：例如 CSS 属性 border-width 可以用 border-width 指代，也可用 borderWidth 指代）。

getWidth(element) -> Number

获取 element 的宽度。

hasClassName(element, className) -> Boolean

判断 element 是否包含参数 className 指定的 CSS 类名称。

hide(element) -> HTMLElement

将 element 隐藏，并返回该元素。

identify(element) -> id

如果 element 存在 id 属性，则返回 id 属性值，否则自动为元素生成一个唯一的 id，并返回该 id 值。

immediateDescendants(element) -> [HTMLElement...]

获取元素的直接后代（即子元素），返回一个数组，数组中的元素已经过 扩展。

insert(element, { position: content }) -> HTMLElement 
insert(element, content) -> HTMLElement

根据第二个参数 position 属性指定的位置，插入 content 到元素的前面、后面、顶部或底部。 如果第二个参数仅包括 content，则将 content 追加到 element 中。
译注：position 取值为：before、after、top 或 bottom。

inspect(element) -> String

返回 element 的字符描述形式，该方法主要用于调试。

makeClipping(element) -> HTMLElement

通过将超出元素边界的内容设置为 'hidden'，来虚拟仅有少数浏览器支持的 CSS clip 属性。返回 element。

makePositioned(element) -> HTMLElement

该方法使你能够方便的创建 CSS 容器块（block），如果 element 的 CSS position 属性初始值为 'static' 或 undefined，它将设置 position 属性为 'relative'。该方法返回元素本身。

match(element, selector) -> Boolean

判断 element 是否匹配参数 selector 指定的 CSS 选择器。

next(element[, cssRule][, index = 0]) -> HTMLElement | undefined

返回匹配 cssRule 指定规则的 element 的下一个兄弟节点（如果指定 index 参数，则返回第 index 个）。如果未指定 cssRule 参数，则默认匹配所有后继兄弟节点。 如果没有符合条件的节点，返回 undefined。

nextSiblings(element) -> [HTMLElement...]

返回 element 的所有后继兄弟节点，结果为一个数组，数组元素已经过 扩展。

observe(element, eventName, handler[, useCapture = false]) -> HTMLElement

为 element 注册一个事件处理程序，返回元素本身。

positionedOffset(element) -> [Number, Number] 或 { left: Number, top: Number }

以 element 的容器块（Containing Block）节点（译注：距离元素最近的 CSS position 属性为 relative 或 absolute 的先代节点）为坐标原点，返回 element 的坐标偏移值（元素的容器块节点可通过 Element#getOffsetParent 方法获取）。
译注：假定返回值为 offset，则 X 轴坐标可通过 offset[0] 获取，也可以通过 offset.left 获取，Y 轴坐标可通过 offset[1] 获取，也可通过 offset.top 获取。

previous(element[, cssRule][, index = 0]) -> HTMLElement | undefined

返回匹配 cssRule 指定规则的 element 的前一个兄弟节点（如果指定 index 参数，则返回第 index 个）。如果未指定 cssRule 参数，则默认匹配所有前导兄弟节点。 如果没有符合条件的节点，返回 undefined。

previousSiblings(element) -> [HTMLElement...]

返回 element 的所有前导兄弟节点，结果为一个数组，数组元素已经过 扩展。

readAttribute(element, attribute) -> String | null

返回 elemnet 由参数 attribute 指定的属性值，若不存在指定的属性值，返回 null。

recursivelyCollect(element, property) -> [HTMLElement...]

通过递归获取和 element 相关的元素集合，元素的相关性由 property 参数指定，property 必须是 element 的一个属性（不能为方法！），指向单个 DOM 节点。该方法返回一个数组，数组元素已经过 扩展。

relativize(element) -> HTMLElement

转换元素的定位方式为相对定位，并且不改变元素在页面中的位置。
译注：该方法使用代码 element.style.position = 'relative' 改变定位方式。在改变定位方式后， 元素左上角的坐标仍会保持原来的位置，如果元素未设置初始的 width 和 height 属性，则调用该方法后， 元素的宽度和高度会改变为系统预设值。
注意：在 1.6.0.3 版本中，该方法会引发异常，需要在第 2066 行后插入代码：

element._originalWidth  = element.style.width;
element._originalHeight = element.style.height;

remove(element) -> HTMLElement

从文档中彻底移除 element，返回移除的元素。

removeClassName(element, className) -> HTMLElement

从 element 中移除参数 className 指定的 CSS 类，返回元素本身。

replace(element[, html]) -> HTMLElement

使用 html 参数指定的内容替换 element，返回被替换的 element。
译注：该方法类似于 IE 下的 element.outerHTML = html。

scrollTo(element) -> HTMLElement

滚动窗口以便 elemnet 显示在窗口可视区域的顶部，返回元素本身。

select(element, selector...) -> [HTMLElement...]

根据一个或多个指定的 CSS 选择器（字符串），在 element 中查找匹配其中任何一个选择器的后代节点， 返回数组，数组元素已经过 扩展。

Element.setOpacity(element, opacity) -> [HTMLElement...] 
someElement.setOpacity(opacity) -> [HTMLElement...]

设置 element 的透明度，该方法可在多种浏览器中正常工作。参数 opacity 是一个介于 0 和 1 之间的浮点数，0 表示完全透明，1 表示完全不透明。

setStyle(element, styles) -> HTMLElement

修改 element 的 CSS 样式属性。参数 styles 是一个包含属性名/值对的 Hash 对象， 属性名必须使用 camelized 命名方式指定（译注：例如 CSS 属性 border-width 应写成 borderWidth，而不能写成 border-width）。

show(element) -> HTMLElement

显示 element，并返回元素本身。

siblings(element) -> [HTMLElement...]

获取 element 的所有兄弟节点，并返回一个数组，数组元素已经过 扩展。

stopObserving(element, eventName, handler) -> HTMLElement

为 element 注销指定的事件处理程序。

toggle(element) -> HTMLElement

切换 element 的可视性（在隐藏和显示间进行切换）。

toggleClassName(element, className) -> HTMLElement

切换 element 的 CSS className（在有和无该类名称间切换），并返回元素本身。

undoClipping(element) -> HTMLElement

设置 element 的 CSS overflow 属性，重置其值为应用 Element.makeClipping() 之前的值，返回元素本身。

undoPositioned(element) -> HTMLElement

设置 element 返回到在元素上应用 Element.makePositioned 方法之前的状态，返回元素本身。

up(element, [cssRule][, index = 0]) -> HTMLElement | undefined

返回 element 的与 cssRule 相匹配的第一个先代节点（如果指定 index 参数，则返回第 index 个）。如果未指定 cssRule，则默认匹配所有先代节点。如果没有符合条件的先代节点，返回 undefined。

update(element[, newContent]) -> HTMLElement

替换 element 的内容为参数 newContent 指定的内容，返回元素本身。
译注：该方法类似于 element.innerHTML = newContent。

viewportOffset(element) -> [Number, Number] 或 { left: Number, top: Number }

返回 element 相对于浏览器可视区域左上角的坐标值。（译注：坐标原点以浏览器当前可见的部分为基准， 意即当滚动条滚动后，坐标原点也随之改变，坐标原点在当前窗口中永远可见。）
译注：假定返回值为 offset，则 X 轴坐标可通过 offset[0] 获取，也可以通过 offset.left 获取，Y 轴坐标可通过 offset[1] 获取，也可通过 offset.top 获取。

visible(element) -> Boolean

返回 Boolean 值，指示 element 是否可见（即判断元素内联的 style 属性是否设置为 "display:none;"）。

Element.wrap(element, wrapper[, attributes]) -> HTMLElement
someElement.wrap(wrapper[, attributes]) -> HTMLElement

将 element 表示的元素放入到参数 wrapper 指定的元素内部，返回 wrapper。

writeAttribute(element, attribute[, value = true]) -> HTMLElement
writeAttribute(element, attributes) -> HTMLElement

新增、修改或移除指定的 element 属性。属性参数可以是一个 hash 对象，也可以是一个名/值对。