jQuery-like API
Taro 目前官方支持使用 React 或 Vue 构建视图,它们都是数据驱动的声明式渲染方式。
但在少数情况下,我们需要显式地操纵 DOM,而小程序提供的 createQuerySelector
API 的用法又较为复杂难懂。在这样的情况下,我们提供了类似 jQuery 的系列 API。使用这个系列 API 很简单,只需要通过 NPM 安装依赖:
npm i @tarojs/extend
然后再需要使用文件引入 $
即可:
import { $ } from '@tarojs/extend'
你还可以通过访问 jQuery-like API RFC 了解更多实现 jQuery-like API 背后的原因与设计。
核心方法
$()
$(selector, [context]) ⇒ collection
$(<collection>) ⇒ same collection
$(<DOM nodes>) ⇒ collection
$(htmlString) ⇒ collection
$(htmlString, attributes) ⇒ collection
通过执行 CSS 选择器,包装 DOM 节点,或者通过一个 HTML 字符串创建多个元素 来创建一个集合对象。
collection
是一个类似数组的对象,它具有链式方法来操作它指向的 DOM 节点,除了 $()
对象上的直接方法外(如$.extend
),文档对象中的所有方法都是集合方法。
如果选择器中存在 content 参数(css 选择器,dom,或者集合对象),那么只在所给的节点背景下进行 css 选择器;这个功能和使用 $(context).find(selector)
是一样的。
$('view') //=> 所有页面中得p元素
$('#foo') //=> ID 为 "foo" 的元素
// 创建元素:
$('<text>Hello</text>') //=> 新的text元素
// 创建带有属性的元素:
$('<text />', { text: 'Hello', id: 'greeting', css: { color: 'darkblue' } })
//=> <text id=greeting style="color:darkblue">Hello</p>
此不支持 jQuery CSS 扩展, 然而,可选的“selector”模块有限提供了支持几个最常用的伪选择器,而且可以被丢弃,与现有的代码或插件的兼容执行。
和 React 或 Vue 不一样的是,在 Taro 的 jQuery-like API
中可以使用像 div
这样的 HTML 元素,但使用小程序规范的组件(例如 view
)在 Taro 应用中运行会更顺畅。但在接下来的的案例中可能会出现 HTML 元素,仅代表使用方法,不代表实际可用。
$.fn
$.fn 是一个对象,它拥有 jQuery 对象上所有可用的方法,如 addClass()
, attr()
,和其它方法。在这个对象添加一个方法,所有的 jQuery 对象上都能用到该方法。
这里有一个实现 jQuery 的 empty()
方法的例子:
$.fn.empty = function () {
return this.each(function () {
this.innerHTML = ''
})
}
addClass
addClass(name) ⇒ self
addClass(function(index, oldClassName){ ... }) ⇒ self
为每个匹配的元素添加指定的 class 类名。多个 class 类名使用空格分隔。
after
after(content) ⇒ self
在每个匹配的元素后插入内容(注:外部插入)。内容可以为 html 字符串,dom 节点,或者节点组成的数组。
$('form label').after('<p>A note below the label</p>')
append
append(content) ⇒ self
在每个匹配的元素末尾插入内容(注:内部插入)。内容可以为 html 字符串,dom 节点,或者节点组成的数组。
$('ul').append('<li>new list item</li>')
attr
attr(name) ⇒ string
attr(name, value) ⇒ self
attr(name, function(index, oldValue){ ... }) ⇒ self
attr({ name: value, name2: value2, ... }) ⇒ self
读取或设置 dom 的属性。如果没有给定 value 参数,则读取对象集合中第一个元素的属性值。当给定了 value 参数。则设置对象集合中所有元素的该属性的值。当 value 参数为null
,那么这个属性将被移除(类似removeAttr
),多个属性可以通过对象键值对的方式进行设置。
要读取 DOM 的属性如 checked
和selected
, 使用 prop
。
var form = $('form')
form.attr('action') //=> 读取值
form.attr('action', '/create') //=> 设置值
form.attr('action', null) //=> 移除属性
// 多个属性:
form.attr({
action: '/create',
method: 'post',
})
before
before(content) ⇒ self
在匹配每个元素的前面插入内容(注:外部插入)。内容可以为 html 字符串,dom 节点,或者节点组成的数组。
$('table').before('<p>See the following table:</p>')
children
children([selector]) ⇒ collection
获得每个匹配元素集合元素的直接子元素,如果给定 selector,那么返回的结果中只包含符合 css 选择器的元素。
$('ol').children('*:nth-child(2n)')
//=> every other list item from every ordered list
clone (3.0.0-rc.6
)
clone() ⇒ collection
通过深度克隆来复制集合中的所有元素。
closest
closest(selector, [context]) ⇒ collection
closest(collection) ⇒ collection
closest(element) ⇒ collection
从元素本身开始,逐级向上级元素匹配,并返回最先匹配 selector 的元素。如果给定 context 节点参数,那么只匹配该节点的后代元素。这个方法与 parents(selector)
有点相像,但它只返回最先匹配的祖先元素。
如果参数是一个 jQuery 对象集合或者一个元素,结果必须匹配给定的元素而不是选择器。
var input = $('input[type=text]')
input.closest('form')
contents
contents() ⇒ collection
获得每个匹配元素集合元素的子元素,包括文字和注释节点。(注:.contents()
和.children()
方法类似,只不过前者包括文本节点以及 jQuery 对象中产生的 HTML 元素。)
css
css(property) ⇒ value
css([property1, property2, ...]) ⇒ object
css(property, value) ⇒ self
css({ property: value, property2: value2, ... }) ⇒ self
读取或设置 DOM 元素的 css 属性。当 value 参数不存在的时候,返回对象集合中第一个元素的 css 属性。当 value 参数存在时,设置对象集合中每一个元素的对应 css 属性。
多个属性可以通过传递一个属性名组成的数组一次性获取。多个属性可以利用对象键值对的方式进行设置。
当 value 为空(空字符串,null 或 undefined),那个 css 属性将会被移出。当 value 参数为一个无单位的数字,如果该 css 属性需要单位,“px”将会自动添加到该属性上。
var elem = $('h1')
elem.css('background-color') // read property
elem.css('background-color', '#369') // set property
elem.css('background-color', '') // remove property
// set multiple properties:
elem.css({ backgroundColor: '#8EE', fontSize: 28 })
// read multiple properties:
elem.css(['backgroundColor', 'fontSize'])['fontSize']
data
data(name) ⇒ value
data(name, value) ⇒ self
读取或写入 dom 的 data-*
属性。行为有点像 attr ,但是属性名称前面加上 data-。
当读取属性值时,会有下列转换:
- “true”, “false”, and “null” 被转换为相应的类型;
- 数字值转换为实际的数字类型;
- JSON 值将会被解析,如果它是有效的 JSON;
- 其它的一切作为字符串返回。
each
each(function(index, item){ ... }) ⇒ self
遍历一个对象集合每个元素。在迭代函数中,this
关键字指向当前项(作为函数的第二个参数传递)。如果迭代函数返回 false
,遍历结束。
$('form input').each(function (index) {
console.log('input %d is: %o', index, this)
})
empty
empty() ⇒ self
清空对象集合中每个元素的 DOM 内容。
eq
eq(index) ⇒ collection
从当前对象集合中获取给定索引值(注:以 0 为基数)的元素。
$('li').eq(0) //=> only the first list item
$('li').eq(-1) //=> only the last list item
filter
filter(selector) ⇒ collection
filter(function(index){ ... }) ⇒ collection
过滤对象集合,返回对象集合中满足 css 选择器的项。如果参数为一个函数,函数返回有实际值得时候,元素才会被返回。在函数中, this 关键字指向当前的元素。
find
find(selector) ⇒ collection
find(collection) ⇒ collection v1.0+
find(element) ⇒ collection v1.0+
在当对象前集合内查找符合 CSS 选择器的每个元素的后代元素。
如果给定 Zepto 对象集合或者元素,过滤它们,只有当它们在当前 Zepto 集合对象中时,才回被返回。
var form = $('#myform')
form.find('input, select')
first
first() ⇒ collection
获取当前对象集合中的第一个元素。
$('form').first()
forEach
forEach(function(item, index, array){ ... }, [context])
遍历对象集合中每个元素,有点类似 each,但是遍历函数的参数不一样,当函数返回 false
的时候,遍历不会停止。
get
get() ⇒ array
get(index) ⇒ DOM node
从当前对象集合中获取所有元素或单个元素。当 index 参数不存在的时,以普通数组的方式返回所有的元素。当指定 index 时,只返回该置的元素。这点与eq
不同,该方法返回的是 DOM 节点,不是 Zepto 对象集合。
var elements = $('h2')
elements.get() //=> get all headings as an array
elements.get(0) //=> get first heading node
has
has(selector) ⇒ collection
has(node) ⇒ collection
判断当前对象集合的子元素是否有符合选择器的元素,或者是否包含指定的 DOM 节点,如果有,则返回新的对象集合,该对象过滤掉不含有选择器匹配元素或者不含有指定 DOM 节点的对象。
$('ol > li').has('a[href]')
//=> get only LI elements that contain links
hasClass
hasClass(name) ⇒ boolean
检查对象集合中是否有元素含有指定的 class。
$('li').hasClass('test')
height
height() ⇒ Promise<number>
height(value) ⇒ self
height(function(index, oldHeight){ ... }) ⇒ self
获取对象集合中第一个元素的高度;或者设置对象集合中所有元素的高度。
const height = await $('#foo').height() // => 123
height()
返回的 Promise
对象。
hide
hide() ⇒ self
通过设置 css 的属性 display
为 none
来将对象集合中的元素隐藏。
html
html() ⇒ string
html(content) ⇒ self
html(function(index, oldHtml){ ... }) ⇒ self
获取或设置对象集合中元素的 HTML 内容。当没有给定 content 参数时,返回对象集合中第一个元素的 innerHtml。当给定 content 参数时,用其替换对象集合中每个元素的内容。content 可以是 append 中描述的所有类型。
// autolink everything that looks like a Twitter username
$('.comment p').html(function (idx, oldHtml) {
return oldHtml.replace(/(^|\W)@(\w{1,15})/g, '$1@<a href="https://twitter.com/$2">$2</a>')
})
index
index([element]) ⇒ number
获取一个元素的索引值(注:从 0 开始计数)。当 elemen 参数没有给出时,返回当前元素在兄弟节点中的位置。当 element 参数给出时,返回它在当前对象集合中的位置。如果没有找到该元素,则返回-1。
$('li:nth-child(2)').index() //=> 1
insertAfter
insertAfter(target) ⇒ self
将集合中的元素插入到指定的目标元素后面(注:外部插入)。这个有点像 after
,但是使用方式相反。
$('<p>Emphasis mine.</p>').insertAfter('blockquote')
insertBefore
insertBefore(target) ⇒ self
将集合中的元素插入到指定的目标元素前面(注:外部插入)。这个有点像 before
,但是使用方式相反。
$('<p>See the following table:</p>').insertBefore('table')
last
last() ⇒ collection
获取对象集合中最后一个元素。
$('li').last()
map
map(function(index, item){ ... }) ⇒ collection
遍历对象集合中的所有元素。通过遍历函数返回值形成一个新的集合对象。在遍历函数中 this 关键之指向当前循环的项(遍历函数中的第二个参数)。
遍历中返回 null 和 undefined,遍历将结束。
elements
.map(function () {
return $(this).text()
})
.get()
.join(', ')
next
next() ⇒ collection
next(selector) ⇒ collection
获取对象集合中每一个元素的下一个兄弟节点(可以选择性的带上过滤选择器)。
not
not(selector) ⇒ collection
not(collection) ⇒ collection
not(function(index){ ... }) ⇒ collection
过滤当前对象集合,获取一个新的对象集合,它里面的元素不能匹配 css 选择器。如果另一个参数为 Zepto 对象集合,那么返回的新 Zepto 对象中的元素都不包含在该参数对象中。如果参数是一个函数。仅仅包含函数执行为false
值得时候的元素,函数的 this
关键字指向当前循环元素。
与它相反的功能,查看 filter
。
offset
offset() ⇒ Promise<object>
offset(coordinates) ⇒ self
offset(function(index, oldOffset){ ... }) ⇒ self
获得当前元素相对于 document 的位置。返回一个对象含有: top
, left
, width
和height
。
offsetParent
offsetParent() ⇒ collection
找到第一个定位过的祖先元素,意味着它的 css 中的 position
属性值为“relative”, “absolute” or “fixed”
parent
parent([selector]) ⇒ collection
获取对象集合中每个元素的直接父元素。如果 css 选择器参数给出。过滤出符合条件的元素。
parents
parents([selector]) ⇒ collection
获取对象集合每个元素所有的祖先元素。如果 css 选择器参数给出,过滤出符合条件的元素。
如果想获取直接父级元素,使用 parent
。如果只想获取到第一个符合 css 选择器的元素,使用closest
。
$('h1').parents() //=> [<div#container>, <body>, <html>]
position
position() ⇒ object
获取对象集合中第一个元素的位置。相对于 offsetParent
。当绝对定位的一个元素靠近另一个元素的时候,这个方法是有用的。
var pos = element.position()
// position a tooltip relative to the element
$('#tooltip').css({
position: 'absolute',
top: pos.top - 30,
left: pos.left,
})
prepend
prepend(content) ⇒ self
将参数内容插入到每个匹配元素的前面(注:元素内部插入)。插入 d 的元素可以试 html 字符串片段,一个 dom 节点,或者一个节点的数组。
$('ul').prepend('<li>first list item</li>')
prependTo
prependTo(target) ⇒ self
将所有元素插入到目标前面(注:元素内部插入)。这有点像prepend
,但是是相反的方式。
$('<li>first list item</li>').prependTo('ul')
prev
prev() ⇒ collection
prev(selector) ⇒ collection
获取对象集合中每一个元素的前一个兄弟节点,通过选择器来进行过滤。
prop
prop(name) ⇒ value
prop(name, value) ⇒ self
prop(name, function(index, oldValue){ ... }) ⇒ self
读取或设置 dom 元素的属性值。它在读取属性值的情况下优先于 attr
,因为这些属性值会因为用户的交互发生改变,如checked
和 selected
。
简写或小写名称,比如for
, class
, readonly
及类似的属性,将被映射到实际的属性上,比如htmlFor
, className
, readOnly
, 等等。
remove
remove() ⇒ self
从其父节点中删除当前集合中的元素,有效的从 dom 中移除。
removeAttr
removeAttr(name) ⇒ self
移除当前对象集合中所有元素的指定属性。
removeClass
removeClass([name]) ⇒ self
removeClass(function(index, oldClassName){ ... }) ⇒ self
移除当前对象集合中所有元素的指定 class。如果没有指定 name 参数,将移出所有的 class。多个 class 参数名称可以利用空格分隔。下例移除了两个 class。
$('#check1').removeClass('test')
removeProp
removeProp(name) ⇒ self
从集合的每个 DOM 节点中删除一个属性。这是用 JavaScript 的delete
操作符完成。值得注意的是如果尝试删除 DOM 的一些内置属性,如className
或maxLength
,将不会有任何效果,因为浏览器禁止删除这些属性。
replaceWith
replaceWith(content) ⇒ self
用给定的内容替换所有匹配的元素。(包含元素本身)。content 参数可以为 before
中描述的类型。
scrollLeft
scrollLeft() => Promise<number>
scrollLeft(value) ⇒ self
获取或设置页面上的滚动元素或者整个窗口向右滚动的像素值。
const height = await $('#foo').scrollLeft() // => 123
scrollTop
scrollTop() => Promise<number>
scrollTop(value) ⇒ self
获取或设置页面上的滚动元素或者整个窗口向下滚动的像素值。
const height = await $('#foo').scrollTop() // => 123
show
show() ⇒ self
siblings
siblings([selector]) ⇒ collection
获取对象集合中所有元素的兄弟节点。如果给定 CSS 选择器参数,过滤出符合选择器的元素。
size
size() ⇒ number
获取对象集合中元素的数量。
slice
slice(start, [end]) ⇒ array
提取这个数组 array 的子集,从start
开始,如果给定end
,提取从从start
开始到end
结束的元素,但是不包含end
位置的元素。
text
text() ⇒ string
text(content) ⇒ self
text(function(index, oldText){ ... }) ⇒ self
获取或者设置所有对象集合中元素的文本内容。当没有给定 content 参数时,返回当前对象集合中第一个元素的文本内容(包含子节点中的文本内容)。当给定 content 参数时,使用它替换对象集合中所有元素的文本内容。它有待点似 html,与它不同的是它不能用来获取或设置 HTML。
toggle
toggle([setting]) ⇒ self
显示或隐藏匹配元素。如果 setting
为 true
,相当于 show()
。如果setting
为false
。相当于 hide()
。
toggleClass
toggleClass(names, [setting]) ⇒ self
toggleClass(function(index, oldClassNames){ ... }, [setting]) ⇒ self
在匹配的元素集合中的每个元素上添加或删除一个或多个样式类。如果 class 的名称存在则删除它,如果不存在,就添加它。如果 setting 的值为真,这个功能类似于 addClass,如果为假,这个功能类似与 removeClass。
unwrap
unwrap() ⇒ self
移除集合中每个元素的直接父节点,并把他们的子元素保留在原来的位置。 基本上,这种方法删除上一的祖先元素,同时保持 DOM 中的当前元素。
val
val() ⇒ string
val(value) ⇒ self
val(function(index, oldValue){ ... }) ⇒ self
获取或设置匹配元素的值。当没有给定 value 参数,返回第一个元素的值。当给定 value 参数,那么将设置所有元素的值。
width
width() ⇒ Promise<number>
width(value) ⇒ self
width(function(index, oldWidth){ ... }) ⇒ self
获取对象集合中第一个元素的宽;或者设置对象集合中所有元素的宽。
await $('#foo').width() // => 123
事件
off
off(type, [selector], function(e){ ... }) ⇒ self
off({ type: handler, type2: handler2, ... }, [selector]) ⇒ self
off(type, [selector]) ⇒ self
off() ⇒ self
移除通过 on 添加的事件.移除一个特定的事件处理程序, 必须通过用on()
添加的那个相同的函数。否则,只通过事件类型调用此方法将移除该类型的所有处理程序。如果没有参数,将移出当前元素上全部的注册事件。
on
on(type, [selector], function(e){ ... }) ⇒ self
on(type, [selector], [data], function(e){ ... }) ⇒ self
on({ type: handler, type2: handler2, ... }, [selector]) ⇒ self
on({ type: handler, type2: handler2, ... }, [selector], [data]) ⇒ self
添加事件处理程序到对象集合中得元素上。多个事件可以通过空格的字符串方式添加,或者以事件类型为键、以函数为值的对象 方式。如果给定 css 选择器,当事件在匹配该选择器的元素上发起时,事件才会被触发(注:即事件委派,或者说事件代理)。
如果给定data
参数,这个值将在事件处理程序执行期间被作为有用的 event.data
属性
事件处理程序在添加该处理程序的元素、或在给定选择器情况下匹配该选择器的元素的上下文中执行(注:this 指向触发事件的元素)。 当一个事件处理程序返回 false,preventDefault() 和 stopPropagation()被当前事件调用的情况下, 将防止默认浏览器操作,如链接。
var elem = $('#content')
// observe all clicks inside #content:
elem.on('click', function(e){ ... })
// observe clicks inside navigation links in #content
elem.on('click', 'nav a', function(e){ ... })
// all clicks inside links in the document
$('#test').on('click', 'a', function(e){ ... })
// disable following any navigation link on the page
$('#test').on('click', 'nav a', false)
one
one(type, [selector], function(e){ ... }) ⇒ self
one(type, [selector], [data], function(e){ ... }) ⇒ self
one({ type: handler, type2: handler2, ... }, [selector]) ⇒ self
one({ type: handler, type2: handler2, ... }, [selector], [data]) ⇒ self
和 on()
一样,添加一个处理事件到元素,当第一次执行事件以后,该事件将自动解除绑定,保证处理函数在每个元素上最多执行一次。
trigger
trigger(event, [args]) ⇒ self
在对象集合的元素上触发指定的事件。如果给定 args 参数,它会作为参数传递给事件函数。
$('#test').trigger('tap', ['one', 'two'])
triggerHandler
- triggerHandler(event, [args]) ⇒ self
和 trigger
一样,它只在当前元素上触发事件,但不冒泡。