Teal TealUI

DOM 处理web/dom

提供统一的、高性能的 DOM 操作方法。

目的
为什么不用 jQuery/Zepto
内置特效
已知问题
API
全局
Point 接口
Size 接口
Rect 接口
ToggleAnimation 类型

目的

为什么不用 jQuery/Zepto

dom 和 jQuery 提供的接口相似，功能相当。 组件开发时用到 jQuery 的功能不多，引入完整的 jQuery 浪费体积和性能。

dom 所有接口功能单一、更接近底层，因此体积小很多、性能更高。
dom 主要为组件开发设计，可以大幅降低组件开发的代码量。

在项目中直接使用 dom 没有 jQuery 方便，但可以通过批量操作节点将 dom 封装成和 jQuery 相同的用法。

特性 dom 4 dom 2 Zepto jQuery 2.x jQuery 1.x
体积（压缩后） 16k 28k 29k 78k 160k
兼容性 IE10+ IE6+ IE9+ IE9+ IE6+
动画底层 CSS3 JS CSS3 JS JS
选择器 原生 扩展 原生 扩展 扩展
触屏事件 ✔ ✖ ✔ ✖ ✖
事件委托 ✔ ✔ ✔ ✔ ✔
事件名空间 ✖ ✖ ✔ ✔ ✔
CSS3前缀 ✔ ✖ ✖ ✖ ✖

内置特效

<select id="select" onchange="toggle(box, this.value, undefined, 1000)">
    <option>opacity</option>
    <option>height</option>
    <option>width</option>
    <option>scale</option>
    <option>scaleX</option>
    <option>scaleY</option>
    <option>top</option>
    <option>bottom</option>
    <option>left</option>
    <option>right</option>
    <option>slideDown</option>
    <option>slideRight</option>
    <option>slideUp</option>
    <option>slideLeft</option>
    <option>zoomIn</option>
    <option>zoomOut</option>
    <option>rotate</option>
</select>
<button onclick="select.onchange();">执行</button>
<div style="height: 100px; ">
    <div id="box" style="position: absolute; display: inline-block;">
        <div class="doc-box"></div>
    </div>
</div>
⏷

已知问题

由于历史原因，浏览器提供的原生 DOM 接口在有些情况可能和作者的预期不符。 dom 组件修复了常见的问题，但为了确保底层精简，仍有很多问题未被修复：

  1. 即使限定了根元素，但选择器仍然是针对全局的。如 dom.find(<div><a></div>, 'div>a') 可以找到 <a> 元素。
  2. 如果表单内存在 name="foo" 的元素，则 getAttr(form, "foo") 会返回该元素，而不是表单本身的 "foo" 属性。
  3. <select> 中只有一个 <option> 时，getAttr(<option>, "selected") 可能是 false。
  4. IE6-8：getAttr(<table>, "test:attrib") 在属性名有冒号时报错。
  5. setAttr(<datalist>, "list", "...") 在部分浏览器无效。
  6. setAttr(elem, "style", "...") 在部分浏览器无法使用。
  7. setAttr(<input>, "type", "...") 在部分浏览器无法使用。
  8. IE6-8：不支持 input 事件。

API

全局

函数 描述
⮞ parse(html, ...)(html:string, context?:Document):HTMLElement | Text | DocumentFragment

解析一段 HTML 并创建相应的节点。

参数 类型 描述 默认值
html* string —
context Document document

返回值

类型：HTMLElement | Text | DocumentFragment

返回创建的节点。如果 HTML 片段中有多个根节点，则返回一个文档片段。

解析一段 HTML 并创建相应的节点。
⮞ query(parent, ...)(parent:string | Document | NodeSelector | Element, selector?:string):any(2 重载)

在指定节点范围内查找 CSS 选择器匹配的所有元素。

参数 类型 描述 默认值
parent* Document | NodeSelector | Element —
selector* string —

返回值

类型：HTMLElement[]

返回匹配的元素列表。

在整个文档内查找 CSS 选择器匹配的所有元素。

参数 类型 描述 默认值
selector* string —

返回值

类型：HTMLElement[]

返回匹配的元素列表。

在指定节点范围内查找 CSS 选择器匹配的所有元素。
⮞ find(parent, ...)(parent:string | Document | NodeSelector | Element, selector?:string):Element | NodeListOf<Element>(2 重载)

在指定节点范围内查找 CSS 选择器匹配的第一个元素。

参数 类型 描述 默认值
parent* Document | NodeSelector | Element —
selector* string —

返回值

类型：HTMLElement

返回匹配的第一个元素。如果找不到则返回 null。

在整个文档内查找 CSS 选择器匹配的第一个元素。

参数 类型 描述 默认值
selector* string —

返回值

类型：HTMLElement

返回匹配的第一个元素。如果找不到则返回 null。

在指定节点范围内查找 CSS 选择器匹配的第一个元素。
⮞ match(elem, selector, ...)(elem:Element, selector:string, context?:Document | Element):boolean

判断元素是否匹配指定的 CSS 选择器。

参数 类型 描述 默认值
elem* Element —
selector* string —
context Document | Element —

返回值

类型：boolean

如果匹配则返回 true，否则返回 false。

示例

match(document.body, "body") // true

判断元素是否匹配指定的 CSS 选择器。
⮞ first(node, ...)(node:Node, selector?:string):HTMLElement

获取节点的第一个子元素。

参数 类型 描述 默认值
node* Node —
selector string —

返回值

类型：HTMLElement

返回一个元素。如果元素不存在或不匹配指定的 CSS 选择器则返回 null。

获取节点的第一个子元素。
⮞ last(node, ...)(node:Node, selector?:string):HTMLElement

获取节点的最后一个子元素。

参数 类型 描述 默认值
node* Node —
selector string —

返回值

类型：HTMLElement

返回一个元素。如果元素不存在或不匹配指定的 CSS 选择器则返回 null。

获取节点的最后一个子元素。
⮞ next(node, ...)(node:Node, selector?:string):HTMLElement

获取节点的下一个相邻元素。

参数 类型 描述 默认值
node* Node —
selector string —

返回值

类型：HTMLElement

返回一个元素。如果元素不存在或不匹配指定的 CSS 选择器则返回 null。

获取节点的下一个相邻元素。
⮞ prev(node, ...)(node:Node, selector?:string):HTMLElement

获取节点的上一个相邻元素。

参数 类型 描述 默认值
node* Node —
selector string —

返回值

类型：HTMLElement

返回一个元素。如果元素不存在或不匹配指定的 CSS 选择器则返回 null。

获取节点的上一个相邻元素。
⮞ parent(node, ...)(node:Node, selector?:string):HTMLElement

获取节点的父元素。

参数 类型 描述 默认值
node* Node —
selector string —

返回值

类型：HTMLElement

返回一个元素。如果元素不存在或不匹配指定的 CSS 选择器则返回 null。

获取节点的父元素。
⮞ closest(node, selector, ...)(node:Node, selector:string, context?:Document | Element):HTMLElement

从指定节点开始向父元素查找第一个匹配指定 CSS 选择器的元素。

参数 类型 描述 默认值
node* Node —
selector* string —
context Document | Element —

返回值

类型：HTMLElement

返回一个元素。如果找不到匹配的元素则返回 null。

示例

closest(document.body, "body")

从指定节点开始向父元素查找第一个匹配指定 CSS 选择器的元素。
⮞ children(node, ...)(node:Node, selector?:string):HTMLElement[]

获取节点的所有直接子元素。

参数 类型 描述 默认值
node* Node —
selector string —

返回值

类型：HTMLElement[]

返回包含所有子元素的数组。

获取节点的所有直接子元素。
⮞ contains(node, child)(node:Node, child:Node):boolean

判断节点是否包含另一个节点。

参数 类型 描述 默认值
node* Node —
child* Node —

返回值

类型：boolean

如果 child 同 node 或 child 是 node 的子节点则返回 true，否则返回 false。

示例

contains(document.body, document.body) // true

判断节点是否包含另一个节点。
⮞ index(node)(node:Node):number

获取节点在其父节点中的索引。

参数 类型 描述 默认值
node* Node —

返回值

类型：number

返回从 0 开始的索引。计算时忽略元素以外的节点。如果没有父节点则返回 0。

获取节点在其父节点中的索引。
⮞ append(node, content)(node:Node, content:string | Node):HTMLElement

在节点末尾插入一段 HTML 或一个节点。

参数 类型 描述 默认值
node* Node —
content* string | Node —

返回值

类型：HTMLElement

返回插入的新节点。

在节点末尾插入一段 HTML 或一个节点。
⮞ prepend(node, content)(node:Node, content:string | Node):HTMLElement

在节点开头插入一段 HTML 或一个节点。

参数 类型 描述 默认值
node* Node —
content* string | Node —

返回值

类型：HTMLElement

返回插入的新节点。

在节点开头插入一段 HTML 或一个节点。
⮞ before(node, content)(node:Node, content:string | Node):HTMLElement

在节点前插入一段 HTML 或一个节点。

参数 类型 描述 默认值
node* Node —
content* string | Node —

返回值

类型：HTMLElement

返回插入的新节点。

在节点前插入一段 HTML 或一个节点。
⮞ after(node, content)(node:Node, content:string | Node):HTMLElement

在节点后插入一段 HTML 或一个节点。

参数 类型 描述 默认值
node* Node —
content* string | Node —

返回值

类型：HTMLElement

返回插入的新节点。

在节点后插入一段 HTML 或一个节点。
⮞ remove(node)(node:Node):void

从文档中移除节点。

参数 类型 描述 默认值
node* Node —

返回值

类型：void

从文档中移除节点。
⮞ clone(node)<T>(node:T):T

复制节点。

泛型参数 约束类型 默认类型
T — —
参数 类型 描述 默认值
node* T —

返回值

类型：T

返回复制的新节点。

复制节点。
⮞ getAttr(elem, attrName)(elem:Element, attrName:string):any

获取元素的属性值。

参数 类型 描述 默认值
elem* Element —
attrName* string —

返回值

类型：any

返回属性值。如果属性不存在则返回 null。

示例

getAttr(document.body, "class")

获取元素的属性值。
⮞ setAttr(elem, attrName, value)(elem:Element, attrName:string, value:any):void

设置元素的属性值。

参数 类型 描述 默认值
elem* Element —
attrName* string —
value* any —

返回值

类型：void

示例

setAttr(document.body, "class", "red")
setAttr(document.body, "class", null)

设置元素的属性值。
⮞ getText(elem)(elem:Element):string

获取元素的文本内容。

参数 类型 描述 默认值
elem* Element —

返回值

类型：string

返回文本内容。对于输入框则返回其输入值。

示例

getText(document.body)

获取元素的文本内容。
⮞ setText(elem, value)(elem:Element, value:string):void

设置元素的文本内容。

参数 类型 描述 默认值
elem* Element —
value* string —

返回值

类型：void

示例

setText(document.body, "text")

设置元素的文本内容。
⮞ getHtml(elem)(elem:Element):string

获取元素的内部 HTML。

参数 类型 描述 默认值
elem* Element —

返回值

类型：string

返回内部 HTML。

示例

getHtml(document.body)

获取元素的内部 HTML。
⮞ setHtml(elem, value)(elem:Element, value:string):void

设置元素的内部 HTML。

参数 类型 描述 默认值
elem* Element —
value* string —

返回值

类型：void

示例

setHtml(document.body, "html")

设置元素的内部 HTML。
⮞ hasClass(elem, className)(elem:Element, className:string):boolean

判断元素是否已添加指定的 CSS 类名。

参数 类型 描述 默认值
elem* Element —
className* string —

返回值

类型：boolean

如果已添加则返回 true，否则返回 false。

判断元素是否已添加指定的 CSS 类名。
⮞ addClass(elem, className)(elem:Element, className:string):void

添加元素的 CSS 类名。

参数 类型 描述 默认值
elem* Element —
className* string —

返回值

类型：void

示例

addClass(document.body, "light")

添加元素的 CSS 类名。
⮞ removeClass(elem, className)(elem:Element, className:string):void

删除元素的 CSS 类名。

参数 类型 描述 默认值
elem* Element —
className* string —

返回值

类型：void

示例

removeClass(document.body, "light")

删除元素的 CSS 类名。
⮞ toggleClass(elem, className, ...)(elem:Element, className:string, value?:boolean):void

如果存在（不存在）则删除（添加）元素的 CSS 类名。

参数 类型 描述 默认值
elem* Element —
className* string —
value boolean —

返回值

类型：void

示例

toggleClass(document.body, "light")

如果存在（不存在）则删除（添加）元素的 CSS 类名。
⮞ vendor(propName)(propName:string):string

为指定的 CSS 属性添加当前浏览器特定的后缀（如 "webkit-")。

参数 类型 描述 默认值
propName* string —

返回值

类型：string

返回已添加后缀的 CSS 属性名。

示例

vendor("transform")

为指定的 CSS 属性添加当前浏览器特定的后缀（如 "webkit-")。
⮞ getStyle(elem, propName)(elem:Element, propName:string):string

获取元素的实际 CSS 属性值。

参数 类型 描述 默认值
elem* Element —
propName* string —

返回值

类型：string

返回计算后的 CSS 属性值。

示例

getStyle(document.body, "fontSize")

获取元素的实际 CSS 属性值。
⮞ setStyle(elem, propName, value)(elem:HTMLElement, propName:string, value:string | number):void

设置元素的 CSS 属性值。

参数 类型 描述 默认值
elem* HTMLElement —
propName* string —
value* string | number —

返回值

类型：void

示例

setStyle(document.body, "fontSize")

设置元素的 CSS 属性值。
⮞ computeStyle(elem, ...)(elem:Element, ...propNames:string[]):number

计算一个元素的样式值。

参数 类型 描述 默认值
elem* Element —
propNames string[] —

返回值

类型：number

返回所有 CSS 属性值的和。

示例

computeStyle(document.body, "fontSize", "lineHeight")

计算一个元素的样式值。
⮞ getScroll(elem)(elem:Document | Element):Point

获取元素的滚动距离。

参数 类型 描述 默认值
elem* Document | Element —

返回值

类型：Point

返回坐标。如果元素不可滚动则返回原点。

示例

getScroll(document.body)

获取元素的滚动距离。
⮞ setScroll(elem, value)(elem:Document | Element, value:Partial<Point>):void

设置元素的滚动距离。

参数 类型 描述 默认值
elem* Document | Element —
value* Partial<Point> —

返回值

类型：void

示例

setScroll(document.body, { x: 100, y: 500 });

设置元素的滚动距离。
⮞ getOffset(elem)(elem:HTMLElement):Point

获取元素和其定位父元素的偏移距离。

参数 类型 描述 默认值
elem* HTMLElement —

返回值

类型：Point

返回坐标。如果元素未设置定位信息则返回原点。

示例

getOffset(document.body)

获取元素和其定位父元素的偏移距离。
⮞ setOffset(elem, value)(elem:HTMLElement, value:Partial<Point>):void

设置元素和其定位父元素的偏移距离。

参数 类型 描述 默认值
elem* HTMLElement —
value* Partial<Point> —

返回值

类型：void

示例

setOffset(document.body, { x: 100 });

设置元素和其定位父元素的偏移距离。
⮞ offsetParent(elem)(elem:HTMLElement):HTMLElement

获取元素的定位父元素。

参数 类型 描述 默认值
elem* HTMLElement —

返回值

类型：HTMLElement

返回定位父元素。

示例

offsetParent(document.body)

获取元素的定位父元素。
⮞ getRect(elem)(elem:Document | Element):Rect

获取元素的区域。

参数 类型 描述 默认值
elem* Document | Element —

返回值

类型：Rect

返回元素实际占用区域（含内边距和边框、不含外边距）。如果元素不可见则返回空区域。

示例

getRect(document.body)

获取元素的区域。
⮞ setRect(elem, value)(elem:HTMLElement, value:Partial<Rect>):void

设置元素的区域。

参数 类型 描述 默认值
elem* HTMLElement —
value* Partial<Rect> —

返回值

类型：void

示例

setRect(document.body, {width: 200, height: 400})

设置元素的区域。
⮞ movable(elem)(elem:HTMLElement):void

确保指定的元素可移动。

参数 类型 描述 默认值
elem* HTMLElement —

返回值

类型：void

确保指定的元素可移动。
⮞ on(elem, eventName, selector, ...)(elem:Document | Element, eventName:string, selector:any, eventHandler?:any, thisArg?:any, eventOptions?:any):void(2 重载)

绑定事件。

参数 类型 描述 默认值
elem* Document | Element | Window —
eventName* string —
selector* string —
eventHandler* (e: Event, sender: HTMLElement) => void —
thisArg any —
eventOptions AddEventListenerOptions —

返回值

类型：void

示例

on(document.body, "mouseenter", "a", function(e){ this.firstChild.innerHTML = e.pageX; })

绑定事件。

参数 类型 描述 默认值
elem* Document | Element | Window —
eventName* string —
eventHandler* (e: Event, sender: any) => void —
thisArg any —
eventOptions AddEventListenerOptions —

返回值

类型：void

示例

on(document.body, "click", e => { alert("点击事件") })

绑定事件。
⮞ off(elem, eventName, ...)(elem:Document | Element, eventName:string, selector?:string | function, eventHandler?:function, thisArg?:any, eventOptions?:any):void(2 重载)

解绑事件。

参数 类型 描述 默认值
elem* Document | Element —
eventName* string —
selector* string —
eventHandler (e: Event, sender: HTMLElement) => void —
thisArg any —
eventOptions AddEventListenerOptions —

返回值

类型：void

示例

off(document.body, "mouseenter", "a", function(e) { this.firstChild.innerHTML = e.pageX; })

解绑事件。

参数 类型 描述 默认值
elem* Document | Element —
eventName* string —
eventHandler (e: Event, sender: any) => void —
thisArg any —
eventOptions AddEventListenerOptions —

返回值

类型：void

示例

off(document.body, "click", e => { alert("点击事件") })

解绑事件。
⮞ trigger(elem, eventName, selector, ...)(elem:Document | Element, eventName:string, selector:string | Partial<Event>, event?:Partial<Event>):void(2 重载)

触发事件。执行已绑定的所有事件处理函数。

参数 类型 描述 默认值
elem* Document | Element —
eventName* string —
selector* string —
event Partial<Event> —

返回值

类型：void

示例

trigger(document.body, "click")

触发事件。执行已绑定的所有事件处理函数。

参数 类型 描述 默认值
elem* Document | Element —
eventName* string —
event Partial<Event> —

返回值

类型：void

示例

trigger(document.body, "click")

触发事件。执行已绑定的所有事件处理函数。
⮞ animate(elem, propNames, ...)(elem:HTMLElement, propNames:object, callback?:function, duration?:number, timingFunction?:string):void

执行一个自定义渐变。

参数 类型 描述 默认值
elem* HTMLElement —
propNames* { [propName: string]: string | number; } —
callback () => void —
duration number 200
timingFunction string "ease"

返回值

类型：void

示例

animate(document.body, { height: 400 });

执行一个自定义渐变。
⮞ isHidden(elem)(elem:HTMLElement):boolean

判断指定的元素是否被隐藏。

参数 类型 描述 默认值
elem* HTMLElement —

返回值

类型：boolean

如果元素本身被隐藏或正在被隐藏则返回 true，否则返回 false。

示例

isHidden(document.body)

判断指定的元素是否被隐藏。
⮞ show(elem, ...)(elem:HTMLElement, animation?:ToggleAnimation, callback?:function, duration?:number, timingFunction?:string, target?:Element):void

显示元素。

参数 类型 描述 默认值
elem* HTMLElement —
animation ToggleAnimation —
callback (value: boolean) => void —
duration number —
timingFunction string —
target Element —

返回值

类型：void

显示元素。
⮞ hide(elem, ...)(elem:HTMLElement, animation?:ToggleAnimation, callback?:function, duration?:number, timingFunction?:string, target?:Element):void

隐藏元素。

参数 类型 描述 默认值
elem* HTMLElement —
animation ToggleAnimation —
callback (value: boolean) => void —
duration number —
timingFunction string —
target Element —

返回值

类型：void

隐藏元素。
⮞ toggle(elem, ...)(elem:HTMLElement, value?:string | number | boolean | Element | object | function, animation?:string | number | Element | object | function, callback?:string | number | Element | function, duration?:string | number | Element, timingFunction?:string | Element, target?:Element):void(2 重载)

切换显示或隐藏元素。

参数 类型 描述 默认值
elem* HTMLElement —
animation ToggleAnimation —
callback (value: boolean) => void —
duration number —
timingFunction string —
target Element —

返回值

类型：void

示例

// 折叠/展开
toggle(document.body, "height");

// 深入/淡出
toggle(document.body, "opacity");

// 缩小/放大
toggle(document.body, "scale");

切换显示或隐藏元素。

参数 类型 描述 默认值
elem* HTMLElement —
value* boolean —
animation ToggleAnimation —
callback (value: boolean) => void —
duration number —
timingFunction string —
target Element —

返回值

类型：void

切换显示或隐藏元素。
⮞ ready(callback, ...)(callback:function, context?:Document):void

确保在文档加载完成后再执行指定的函数。

参数 类型 描述 默认值
callback* (this: Document) => void —
context Document document

返回值

类型：void

确保在文档加载完成后再执行指定的函数。

Point 接口

表示一个坐标。

字段 类型 描述
⮞ x : number

相对于屏幕左上角的水平距离（单位为像素）。

 number

相对于屏幕左上角的水平距离（单位为像素）。
⮞ y : number

相对于屏幕左上角的垂直距离（单位为像素）。

 number

相对于屏幕左上角的垂直距离（单位为像素）。

Size 接口

表示一个大小。

字段 类型 描述
⮞ width : number

宽度（单位为像素）。

 number

宽度（单位为像素）。
⮞ height : number

高度（单位为像素）。

 number

高度（单位为像素）。

Rect 接口

继承自：Point, Size

表示一个矩形区域。

字段 类型 描述 继承自
⮞ x : number

相对于屏幕左上角的水平距离（单位为像素）。

继承自

Point

 number

相对于屏幕左上角的水平距离（单位为像素）。

 Point
⮞ y : number

相对于屏幕左上角的垂直距离（单位为像素）。

继承自

Point

 number

相对于屏幕左上角的垂直距离（单位为像素）。

 Point
⮞ width : number

宽度（单位为像素）。

继承自

Size

 number

宽度（单位为像素）。

 Size
⮞ height : number

高度（单位为像素）。

继承自

Size

 number

高度（单位为像素）。

 Size

ToggleAnimation 类型

表示一个切换动画。

同："opacity" | "height" | "width" | "top" | "bottom" | "left" | "right" | "scale" | "scaleX" | "scaleY" | "slideDown" | "slideRight" | "slideUp" | "slideLeft" | "zoomIn" | "zoomOut" | "rotate" | { [propName: string]: string | number; }