Element.Methods - Prototype JavaScript 框架

Xunxin Prototype API

Element.Methods

Element.Methods 是一个针对 DOM 元素的混入对象。这个对象所具有的方法不能直接访问,必须通过 $() 工具函数或 Element 对象进行访问。

样例

// 隐藏元素 
$(element).hide(); 
//返回一个 Enumerable:包含 ID 为 "article" 的元素的所有后代节点
$('articles').descendants();

方法

absolutize
1.6

absolutize(element) -> HTMLElement

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

addClassName

addClassName(element, className) -> HTMLElement 

增加一个 CSS 类到 element 中。

adjacent
1.6

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

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

ancestors

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

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

childElements
1.5.1

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

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

classNames
不推荐

classNames(element) -> Enumerable

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

cleanWhitespace

cleanWhitespace(element) -> HTMLElement

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

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

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

clonePosition
1.6

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

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

cumulativeOffset
1.6

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

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

cumulativeScrollOffset
1.6

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

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

descendantOf

descendantOf(element, ancestor) -> Boolean 

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

descendants

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

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

down

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

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

empty

empty(element) -> Boolean

测试 element 是否为空(例如仅包含空白)。

fire
1.6.0

fire(eventName[, memo]) -> Event

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

firstDescendant
1.5.1

firstDescendant(element) -> HTMLElement

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

getDimensions

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

获取 elementwidthheight,并返回一个对象,包括宽高的名值对。

getElementsByClassName
不推荐

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

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

getElementsBySelector
不推荐

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

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

getHeight

getHeight(element) -> Number

获取 element 的高度。

getOffsetParent
1.6

getOffsetParent(element) -> HTMLElement

返回 element 的容器块(Containing Block)(译注:距离元素最近的 CSS position 属性为 relativeabsolute 的先代节点)节点,如果不存在这样一个节点,则返回 body 元素。

getStyle

getStyle(element, property) -> String | null

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

getWidth

getWidth(element) -> Number

获取 element 的宽度。

hasClassName

hasClassName(element, className) -> Boolean

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

hide

hide(element) -> HTMLElement

element 隐藏,并返回该元素。

identify
1.6

identify(element) -> id

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

immediateDescendants
deprecated

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

获取元素的直接后代(即子元素),返回一个数组,数组中的元素已经过 扩展

insert
1.6

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

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

inspect

inspect(element) -> String

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

makeClipping

makeClipping(element) -> HTMLElement

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

makePositioned

makePositioned(element) -> HTMLElement

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

match

match(element, selector) -> Boolean

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

next

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

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

nextSiblings

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

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

observe

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

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

positionedOffset
1.6

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

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

previous

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

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

previousSiblings

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

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

readAttribute

readAttribute(element, attribute) -> String | null

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

recursivelyCollect

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

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

relativize
1.6

relativize(element) -> HTMLElement

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

element._originalWidth  = element.style.width;
element._originalHeight = element.style.height;
其它版本未知。

remove

remove(element) -> HTMLElement

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

removeClassName

removeClassName(element, className) -> HTMLElement

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

replace

replace(element[, html]) -> HTMLElement

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

scrollTo

scrollTo(element) -> HTMLElement

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

select
1.6

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

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

setOpacity
1.5.1

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

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

setStyle

setStyle(element, styles) -> HTMLElement

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

show

show(element) -> HTMLElement

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

siblings

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

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

stopObserving

stopObserving(element, eventName, handler) -> HTMLElement

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

toggle

toggle(element) -> HTMLElement

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

toggleClassName

toggleClassName(element, className) -> HTMLElement

切换 element 的 CSS className(在有和无该类名称间切换),并返回元素本身。

undoClipping

undoClipping(element) -> HTMLElement

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

undoPositioned

undoPositioned(element) -> HTMLElement

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

up

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

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

update

update(element[, newContent]) -> HTMLElement

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

viewportOffset
1.6

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

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

visible

visible(element) -> Boolean

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

wrap
1.6

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

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

writeAttribute
1.6

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

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