Taro 目前官方支持使用 React 或 Vue 構(gòu)建視圖,它們都是數(shù)據(jù)驅(qū)動(dòng)的聲明式渲染方式。
但在少數(shù)情況下,我們需要顯式地操縱 DOM,而小程序提供的 createQuerySelector
API 的用法又較為復(fù)雜難懂。在這樣的情況下,我們提供了類似 jQuery 的系列 API。使用這個(gè)系列 API 很簡(jiǎn)單,只需要通過 NPM 安裝依賴:
npm i @tarojs/extend
然后再需要使用文件引入 $
即可:
import { $ } from '@tarojs/extend'
:::info 了解更多 你還可以通過訪問 jQuery-like API RFC 了解更多實(shí)現(xiàn) jQuery-like API 背后的原因與設(shè)計(jì)。 :::
$(selector, [context]) ? collection
$(<collection>) ? same collection
$(<DOM nodes>) ? collection
$(htmlString) ? collection
$(htmlString, attributes) ? collection
通過執(zhí)行 CSS 選擇器,包裝 DOM 節(jié)點(diǎn),或者通過一個(gè) HTML 字符串創(chuàng)建多個(gè)元素 來創(chuàng)建一個(gè)集合對(duì)象。
collection
是一個(gè)類似數(shù)組的對(duì)象,它具有鏈?zhǔn)椒椒▉聿僮魉赶虻?DOM 節(jié)點(diǎn),除了 $()
對(duì)象上的直接方法外(如$.extend
),文檔對(duì)象中的所有方法都是集合方法。
如果選擇器中存在content參數(shù)(css選擇器,dom,或者集合對(duì)象),那么只在所給的節(jié)點(diǎn)背景下進(jìn)行css選擇器;這個(gè)功能和使用 $(context).find(selector)
是一樣的。
$('view') //=> 所有頁面中得p元素
$('#foo') //=> ID 為 "foo" 的元素
// 創(chuàng)建元素:
$("<text>Hello</text>") //=> 新的text元素
// 創(chuàng)建帶有屬性的元素:
$("<text />", { text:"Hello", id:"greeting", css:{color:'darkblue'} })
//=> <text id=greeting style="color:darkblue">Hello</p>
:::caution 請(qǐng)注意 此不支持 jQuery CSS 擴(kuò)展, 然而,可選的“selector”模塊有限提供了支持幾個(gè)最常用的偽選擇器,而且可以被丟棄,與現(xiàn)有的代碼或插件的兼容執(zhí)行。 :::
:::caution 請(qǐng)注意 和 React 或 Vue 不一樣的是,在 Taro 的 jQuery-like API
中可以使用像 div
這樣的 HTML 元素,但使用小程序規(guī)范的組件(例如 view
)在 Taro 應(yīng)用中運(yùn)行會(huì)更順暢。但在接下來的的案例中可能會(huì)出現(xiàn) HTML 元素,僅代表使用方法,不代表實(shí)際可用。 :::
$.fn 是一個(gè)對(duì)象,它擁有 jQuery 對(duì)象上所有可用的方法,如 addClass()
, attr()
,和其它方法。在這個(gè)對(duì)象添加一個(gè)方法,所有的 jQuery 對(duì)象上都能用到該方法。
這里有一個(gè)實(shí)現(xiàn) jQuery 的 empty()
方法的例子:
$.fn.empty = function(){
return this.each(function(){ this.innerHTML = '' })
}
addClass(name) ? self
addClass(function(index, oldClassName){ ... }) ? self
為每個(gè)匹配的元素添加指定的class類名。多個(gè)class類名使用空格分隔。
after(content) ? self
在每個(gè)匹配的元素后插入內(nèi)容(注:外部插入)。內(nèi)容可以為html字符串,dom節(jié)點(diǎn),或者節(jié)點(diǎn)組成的數(shù)組。
$('form label').after('<p>A note below the label</p>')
append(content) ? self
在每個(gè)匹配的元素末尾插入內(nèi)容(注:內(nèi)部插入)。內(nèi)容可以為html字符串,dom節(jié)點(diǎn),或者節(jié)點(diǎn)組成的數(shù)組。
$('ul').append('<li>new list item</li>')
attr(name) ? string
attr(name, value) ? self
attr(name, function(index, oldValue){ ... }) ? self
attr({ name: value, name2: value2, ... }) ? self
讀取或設(shè)置dom的屬性。如果沒有給定value參數(shù),則讀取對(duì)象集合中第一個(gè)元素的屬性值。當(dāng)給定了value參數(shù)。則設(shè)置對(duì)象集合中所有元素的該屬性的值。當(dāng)value參數(shù)為null
,那么這個(gè)屬性將被移除(類似removeAttr
),多個(gè)屬性可以通過對(duì)象鍵值對(duì)的方式進(jìn)行設(shè)置。
要讀取DOM的屬性如 checked
和selected
, 使用 prop
。
var form = $('form')
form.attr('action') //=> 讀取值
form.attr('action', '/create') //=> 設(shè)置值
form.attr('action', null) //=> 移除屬性
// 多個(gè)屬性:
form.attr({
action: '/create',
method: 'post'
})
before(content) ? self
在匹配每個(gè)元素的前面插入內(nèi)容(注:外部插入)。內(nèi)容可以為html字符串,dom節(jié)點(diǎn),或者節(jié)點(diǎn)組成的數(shù)組。
$('table').before('<p>See the following table:</p>')
children([selector]) ? collection
獲得每個(gè)匹配元素集合元素的直接子元素,如果給定selector,那么返回的結(jié)果中只包含符合css選擇器的元素。
$('ol').children('*:nth-child(2n)')
//=> every other list item from every ordered list
clone() ? collection
通過深度克隆來復(fù)制集合中的所有元素。
closest(selector, [context]) ? collection
closest(collection) ? collection
closest(element) ? collection
從元素本身開始,逐級(jí)向上級(jí)元素匹配,并返回最先匹配selector的元素。如果給定context節(jié)點(diǎn)參數(shù),那么只匹配該節(jié)點(diǎn)的后代元素。這個(gè)方法與 parents(selector)
有點(diǎn)相像,但它只返回最先匹配的祖先元素。
如果參數(shù)是一個(gè)jQuery對(duì)象集合或者一個(gè)元素,結(jié)果必須匹配給定的元素而不是選擇器。
var input = $('input[type=text]')
input.closest('form')
contents() ? collection
獲得每個(gè)匹配元素集合元素的子元素,包括文字和注釋節(jié)點(diǎn)。(注:.contents()
和.children()
方法類似,只不過前者包括文本節(jié)點(diǎn)以及jQuery對(duì)象中產(chǎn)生的HTML元素。)
css(property) ? value
css([property1, property2, ...]) ? object
css(property, value) ? self
css({ property: value, property2: value2, ... }) ? self
讀取或設(shè)置DOM元素的css屬性。當(dāng)value參數(shù)不存在的時(shí)候,返回對(duì)象集合中第一個(gè)元素的css屬性。當(dāng)value參數(shù)存在時(shí),設(shè)置對(duì)象集合中每一個(gè)元素的對(duì)應(yīng)css屬性。
多個(gè)屬性可以通過傳遞一個(gè)屬性名組成的數(shù)組一次性獲取。多個(gè)屬性可以利用對(duì)象鍵值對(duì)的方式進(jìn)行設(shè)置。
當(dāng)value為空(空字符串,null 或 undefined),那個(gè)css屬性將會(huì)被移出。當(dāng)value參數(shù)為一個(gè)無單位的數(shù)字,如果該css屬性需要單位,“px”將會(huì)自動(dòng)添加到該屬性上。
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(name) ? value
data(name, value) ? self
讀取或?qū)懭雂om的 data-*
屬性。行為有點(diǎn)像 attr ,但是屬性名稱前面加上 data-。
當(dāng)讀取屬性值時(shí),會(huì)有下列轉(zhuǎn)換:
each(function(index, item){ ... }) ? self
遍歷一個(gè)對(duì)象集合每個(gè)元素。在迭代函數(shù)中,this
關(guān)鍵字指向當(dāng)前項(xiàng)(作為函數(shù)的第二個(gè)參數(shù)傳遞)。如果迭代函數(shù)返回 false
,遍歷結(jié)束。
$('form input').each(function(index){
console.log('input %d is: %o', index, this)
})
empty() ? self
清空對(duì)象集合中每個(gè)元素的DOM內(nèi)容。
eq(index) ? collection
從當(dāng)前對(duì)象集合中獲取給定索引值(注:以0為基數(shù))的元素。
$('li').eq(0) //=> only the first list item
$('li').eq(-1) //=> only the last list item
filter(selector) ? collection
filter(function(index){ ... }) ? collection
過濾對(duì)象集合,返回對(duì)象集合中滿足css選擇器的項(xiàng)。如果參數(shù)為一個(gè)函數(shù),函數(shù)返回有實(shí)際值得時(shí)候,元素才會(huì)被返回。在函數(shù)中, this 關(guān)鍵字指向當(dāng)前的元素。
find(selector) ? collection
find(collection) ? collection v1.0+
find(element) ? collection v1.0+
在當(dāng)對(duì)象前集合內(nèi)查找符合CSS選擇器的每個(gè)元素的后代元素。
如果給定Zepto對(duì)象集合或者元素,過濾它們,只有當(dāng)它們?cè)诋?dāng)前Zepto集合對(duì)象中時(shí),才回被返回。
var form = $('#myform')
form.find('input, select')
first() ? collection
獲取當(dāng)前對(duì)象集合中的第一個(gè)元素。
$('form').first()
forEach(function(item, index, array){ ... }, [context])
遍歷對(duì)象集合中每個(gè)元素,有點(diǎn)類似 each,但是遍歷函數(shù)的參數(shù)不一樣,當(dāng)函數(shù)返回 false
的時(shí)候,遍歷不會(huì)停止。
get() ? array
get(index) ? DOM node
從當(dāng)前對(duì)象集合中獲取所有元素或單個(gè)元素。當(dāng)index參數(shù)不存在的時(shí),以普通數(shù)組的方式返回所有的元素。當(dāng)指定index時(shí),只返回該置的元素。這點(diǎn)與eq
不同,該方法返回的是DOM節(jié)點(diǎn),不是Zepto對(duì)象集合。
var elements = $('h2')
elements.get() //=> get all headings as an array
elements.get(0) //=> get first heading node
has(selector) ? collection
has(node) ? collection
判斷當(dāng)前對(duì)象集合的子元素是否有符合選擇器的元素,或者是否包含指定的DOM節(jié)點(diǎn),如果有,則返回新的對(duì)象集合,該對(duì)象過濾掉不含有選擇器匹配元素或者不含有指定DOM節(jié)點(diǎn)的對(duì)象。
$('ol > li').has('a[href]')
//=> get only LI elements that contain links
hasClass(name) ? boolean
檢查對(duì)象集合中是否有元素含有指定的class。
$("li").hasClass("test")
height() ? Promise<number>
height(value) ? self
height(function(index, oldHeight){ ... }) ? self
獲取對(duì)象集合中第一個(gè)元素的高度;或者設(shè)置對(duì)象集合中所有元素的高度。
const height = await $('#foo').height() // => 123
:::caution 請(qǐng)注意 height()
返回的 Promise
對(duì)象。 :::
hide() ? self
通過設(shè)置css的屬性 display
為 none
來將對(duì)象集合中的元素隱藏。
html() ? string
html(content) ? self
html(function(index, oldHtml){ ... }) ? self
獲取或設(shè)置對(duì)象集合中元素的HTML內(nèi)容。當(dāng)沒有給定content參數(shù)時(shí),返回對(duì)象集合中第一個(gè)元素的innerHtml。當(dāng)給定content參數(shù)時(shí),用其替換對(duì)象集合中每個(gè)元素的內(nèi)容。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 rel="external nofollow" target="_blank" >$2</a>')
})
index([element]) ? number
獲取一個(gè)元素的索引值(注:從0開始計(jì)數(shù))。當(dāng)elemen參數(shù)沒有給出時(shí),返回當(dāng)前元素在兄弟節(jié)點(diǎn)中的位置。當(dāng)element參數(shù)給出時(shí),返回它在當(dāng)前對(duì)象集合中的位置。如果沒有找到該元素,則返回-1。
$('li:nth-child(2)').index() //=> 1
insertAfter(target) ? self
將集合中的元素插入到指定的目標(biāo)元素后面(注:外部插入)。這個(gè)有點(diǎn)像 after
,但是使用方式相反。
$('<p>Emphasis mine.</p>').insertAfter('blockquote')
insertBefore(target) ? self
將集合中的元素插入到指定的目標(biāo)元素前面(注:外部插入)。這個(gè)有點(diǎn)像 before
,但是使用方式相反。
$('<p>See the following table:</p>').insertBefore('table')
last() ? collection
獲取對(duì)象集合中最后一個(gè)元素。
$('li').last()
map(function(index, item){ ... }) ? collection
遍歷對(duì)象集合中的所有元素。通過遍歷函數(shù)返回值形成一個(gè)新的集合對(duì)象。在遍歷函數(shù)中this關(guān)鍵之指向當(dāng)前循環(huán)的項(xiàng)(遍歷函數(shù)中的第二個(gè)參數(shù))。
遍歷中返回 null和undefined,遍歷將結(jié)束。
elements.map(function(){ return $(this).text() }).get().join(', ')
next() ? collection
next(selector) ? collection
獲取對(duì)象集合中每一個(gè)元素的下一個(gè)兄弟節(jié)點(diǎn)(可以選擇性的帶上過濾選擇器)。
not(selector) ? collection
not(collection) ? collection
not(function(index){ ... }) ? collection
過濾當(dāng)前對(duì)象集合,獲取一個(gè)新的對(duì)象集合,它里面的元素不能匹配css選擇器。如果另一個(gè)參數(shù)為Zepto對(duì)象集合,那么返回的新Zepto對(duì)象中的元素都不包含在該參數(shù)對(duì)象中。如果參數(shù)是一個(gè)函數(shù)。僅僅包含函數(shù)執(zhí)行為false
值得時(shí)候的元素,函數(shù)的 this
關(guān)鍵字指向當(dāng)前循環(huán)元素。
與它相反的功能,查看 filter
。
offset() ? Promise<object>
offset(coordinates) ? self
offset(function(index, oldOffset){ ... }) ? self
獲得當(dāng)前元素相對(duì)于document的位置。返回一個(gè)對(duì)象含有: top
, left
, width
和height
。
offsetParent() ? collection
找到第一個(gè)定位過的祖先元素,意味著它的css中的 position
屬性值為“relative”, “absolute” or “fixed”
parent([selector]) ? collection
獲取對(duì)象集合中每個(gè)元素的直接父元素。如果css選擇器參數(shù)給出。過濾出符合條件的元素。
parents([selector]) ? collection
獲取對(duì)象集合每個(gè)元素所有的祖先元素。如果css選擇器參數(shù)給出,過濾出符合條件的元素。
如果想獲取直接父級(jí)元素,使用 parent
。如果只想獲取到第一個(gè)符合css選擇器的元素,使用closest
。
$('h1').parents() //=> [<div#container>, <body>, <html>]
position() ? object
獲取對(duì)象集合中第一個(gè)元素的位置。相對(duì)于 offsetParent
。當(dāng)絕對(duì)定位的一個(gè)元素靠近另一個(gè)元素的時(shí)候,這個(gè)方法是有用的。
var pos = element.position()
// position a tooltip relative to the element
$('#tooltip').css({
position: 'absolute',
top: pos.top - 30,
left: pos.left
})
prepend(content) ? self
將參數(shù)內(nèi)容插入到每個(gè)匹配元素的前面(注:元素內(nèi)部插入)。插入d的元素可以試html字符串片段,一個(gè)dom節(jié)點(diǎn),或者一個(gè)節(jié)點(diǎn)的數(shù)組。
$('ul').prepend('<li>first list item</li>')
prependTo(target) ? self
將所有元素插入到目標(biāo)前面(注:元素內(nèi)部插入)。這有點(diǎn)像prepend
,但是是相反的方式。
$('<li>first list item</li>').prependTo('ul')
prev() ? collection
prev(selector) ? collection
獲取對(duì)象集合中每一個(gè)元素的前一個(gè)兄弟節(jié)點(diǎn),通過選擇器來進(jìn)行過濾。
prop(name) ? value
prop(name, value) ? self
prop(name, function(index, oldValue){ ... }) ? self
讀取或設(shè)置dom元素的屬性值。它在讀取屬性值的情況下優(yōu)先于 attr
,因?yàn)檫@些屬性值會(huì)因?yàn)橛脩舻慕换グl(fā)生改變,如checked
和 selected
。
簡(jiǎn)寫或小寫名稱,比如for
, class
, readonly
及類似的屬性,將被映射到實(shí)際的屬性上,比如htmlFor
, className
, readOnly
, 等等。
remove() ? self
從其父節(jié)點(diǎn)中刪除當(dāng)前集合中的元素,有效的從dom中移除。
removeAttr(name) ? self
移除當(dāng)前對(duì)象集合中所有元素的指定屬性。
removeClass([name]) ? self
removeClass(function(index, oldClassName){ ... }) ? self
移除當(dāng)前對(duì)象集合中所有元素的指定class。如果沒有指定name參數(shù),將移出所有的class。多個(gè)class參數(shù)名稱可以利用空格分隔。下例移除了兩個(gè)class。
$("#check1").removeClass("test")
removeProp(name) ? self
從集合的每個(gè)DOM節(jié)點(diǎn)中刪除一個(gè)屬性。這是用JavaScript的delete
操作符完成。值得注意的是如果嘗試刪除DOM的一些內(nèi)置屬性,如className
或maxLength
,將不會(huì)有任何效果,因?yàn)闉g覽器禁止刪除這些屬性。
replaceWith(content) ? self
用給定的內(nèi)容替換所有匹配的元素。(包含元素本身)。content參數(shù)可以為 before
中描述的類型。
scrollLeft() => Promise<number>
scrollLeft(value) ? self
獲取或設(shè)置頁面上的滾動(dòng)元素或者整個(gè)窗口向右滾動(dòng)的像素值。
const height = await $('#foo').scrollLeft() // => 123
scrollTop() => Promise<number>
scrollTop(value) ? self
獲取或設(shè)置頁面上的滾動(dòng)元素或者整個(gè)窗口向下滾動(dòng)的像素值。
const height = await $('#foo').scrollTop() // => 123
show() ? self
siblings([selector]) ? collection
獲取對(duì)象集合中所有元素的兄弟節(jié)點(diǎn)。如果給定CSS選擇器參數(shù),過濾出符合選擇器的元素。
size() ? number
獲取對(duì)象集合中元素的數(shù)量。
slice(start, [end]) ? array
提取這個(gè)數(shù)組array的子集,從start
開始,如果給定end
,提取從從start
開始到end
結(jié)束的元素,但是不包含end
位置的元素。
text() ? string
text(content) ? self
text(function(index, oldText){ ... }) ? self
獲取或者設(shè)置所有對(duì)象集合中元素的文本內(nèi)容。當(dāng)沒有給定content參數(shù)時(shí),返回當(dāng)前對(duì)象集合中第一個(gè)元素的文本內(nèi)容(包含子節(jié)點(diǎn)中的文本內(nèi)容)。當(dāng)給定content參數(shù)時(shí),使用它替換對(duì)象集合中所有元素的文本內(nèi)容。它有待點(diǎn)似 html,與它不同的是它不能用來獲取或設(shè)置 HTML。
toggle([setting]) ? self
顯示或隱藏匹配元素。如果 setting
為 true
,相當(dāng)于 show()
。如果setting
為false
。相當(dāng)于 hide()
。
toggleClass(names, [setting]) ? self
toggleClass(function(index, oldClassNames){ ... }, [setting]) ? self
在匹配的元素集合中的每個(gè)元素上添加或刪除一個(gè)或多個(gè)樣式類。如果class的名稱存在則刪除它,如果不存在,就添加它。如果 setting的值為真,這個(gè)功能類似于 addClass,如果為假,這個(gè)功能類似與 removeClass。
unwrap() ? self
移除集合中每個(gè)元素的直接父節(jié)點(diǎn),并把他們的子元素保留在原來的位置。 基本上,這種方法刪除上一的祖先元素,同時(shí)保持DOM中的當(dāng)前元素。
val() ? string
val(value) ? self
val(function(index, oldValue){ ... }) ? self
獲取或設(shè)置匹配元素的值。當(dāng)沒有給定value參數(shù),返回第一個(gè)元素的值。當(dāng)給定value參數(shù),那么將設(shè)置所有元素的值。
width() ? Promise<number>
width(value) ? self
width(function(index, oldWidth){ ... }) ? self
獲取對(duì)象集合中第一個(gè)元素的寬;或者設(shè)置對(duì)象集合中所有元素的寬。
await $('#foo').width() // => 123
off(type, [selector], function(e){ ... }) ? self
off({ type: handler, type2: handler2, ... }, [selector]) ? self
off(type, [selector]) ? self
off() ? self
移除通過 on 添加的事件.移除一個(gè)特定的事件處理程序, 必須通過用on()
添加的那個(gè)相同的函數(shù)。否則,只通過事件類型調(diào)用此方法將移除該類型的所有處理程序。如果沒有參數(shù),將移出當(dāng)前元素上全部的注冊(cè)事件。
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
添加事件處理程序到對(duì)象集合中得元素上。多個(gè)事件可以通過空格的字符串方式添加,或者以事件類型為鍵、以函數(shù)為值的對(duì)象 方式。如果給定css選擇器,當(dāng)事件在匹配該選擇器的元素上發(fā)起時(shí),事件才會(huì)被觸發(fā)(注:即事件委派,或者說事件代理)。
如果給定data
參數(shù),這個(gè)值將在事件處理程序執(zhí)行期間被作為有用的 event.data
屬性
事件處理程序在添加該處理程序的元素、或在給定選擇器情況下匹配該選擇器的元素的上下文中執(zhí)行(注:this指向觸發(fā)事件的元素)。 當(dāng)一個(gè)事件處理程序返回false,preventDefault() 和 stopPropagation()被當(dāng)前事件調(diào)用的情況下, 將防止默認(rèn)瀏覽器操作,如鏈接。
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(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()
一樣,添加一個(gè)處理事件到元素,當(dāng)?shù)谝淮螆?zhí)行事件以后,該事件將自動(dòng)解除綁定,保證處理函數(shù)在每個(gè)元素上最多執(zhí)行一次。
trigger(event, [args]) ? self
在對(duì)象集合的元素上觸發(fā)指定的事件。如果給定args參數(shù),它會(huì)作為參數(shù)傳遞給事件函數(shù)。
$('#test').trigger('tap', ['one', 'two'])
和 trigger
一樣,它只在當(dāng)前元素上觸發(fā)事件,但不冒泡。
更多建議: