Taro 目前官方支持使用 React 或 Vue 構(gòu)建視圖，它們都是數(shù)據(jù)驅(qū)動的聲明式渲染方式。

但在少數(shù)情況下，我們需要顯式地操縱 DOM，而小程序提供的 createQuerySelector API 的用法又較為復(fù)雜難懂。在這樣的情況下，我們提供了類似 jQuery 的系列 API。使用這個系列 API 很簡單，只需要通過 NPM 安裝依賴：

npm i @tarojs/extend

然后再需要使用文件引入 $ 即可：

import { $ } from '@tarojs/extend'

:::info 了解更多 你還可以通過訪問 jQuery-like API RFC 了解更多實現(xiàn) jQuery-like API 背后的原因與設(shè)計。 :::

核心方法

$()

• $(selector, [context]) ? collection
• $(<collection>) ? same collection
• $(<DOM nodes>) ? collection
• $(htmlString) ? collection
• $(htmlString, attributes) ? collection

通過執(zhí)行 CSS 選擇器，包裝 DOM 節(jié)點，或者通過一個 HTML 字符串創(chuàng)建多個元素 來創(chuàng)建一個集合對象。

collection 是一個類似數(shù)組的對象，它具有鏈?zhǔn)椒椒▉聿僮魉赶虻?DOM 節(jié)點，除了 $() 對象上的直接方法外(如$.extend)，文檔對象中的所有方法都是集合方法。

如果選擇器中存在content參數(shù)(css選擇器，dom，或者集合對象)，那么只在所給的節(jié)點背景下進行css選擇器；這個功能和使用 $(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 請注意 此不支持 jQuery CSS 擴展， 然而，可選的“selector”模塊有限提供了支持幾個最常用的偽選擇器，而且可以被丟棄，與現(xiàn)有的代碼或插件的兼容執(zhí)行。 :::

:::caution 請注意 和 React 或 Vue 不一樣的是，在 Taro 的 jQuery-like API 中可以使用像 div 這樣的 HTML 元素，但使用小程序規(guī)范的組件（例如 view）在 Taro 應(yīng)用中運行會更順暢。但在接下來的的案例中可能會出現(xiàn) HTML 元素，僅代表使用方法，不代表實際可用。 :::

$.fn

$.fn 是一個對象，它擁有 jQuery 對象上所有可用的方法，如 addClass()， attr()，和其它方法。在這個對象添加一個方法，所有的 jQuery 對象上都能用到該方法。

這里有一個實現(xiàn) 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

在每個匹配的元素后插入內(nèi)容（注：外部插入）。內(nèi)容可以為html字符串，dom節(jié)點，或者節(jié)點組成的數(shù)組。

$('form label').after('<p>A note below the label</p>')

append

• append(content) ? self

在每個匹配的元素末尾插入內(nèi)容（注：內(nèi)部插入）。內(nèi)容可以為html字符串，dom節(jié)點，或者節(jié)點組成的數(shù)組。

$('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

讀取或設(shè)置dom的屬性。如果沒有給定value參數(shù)，則讀取對象集合中第一個元素的屬性值。當(dāng)給定了value參數(shù)。則設(shè)置對象集合中所有元素的該屬性的值。當(dāng)value參數(shù)為null，那么這個屬性將被移除(類似removeAttr)，多個屬性可以通過對象鍵值對的方式進行設(shè)置。

要讀取DOM的屬性如 checked和selected, 使用 prop。

var form = $('form')
form.attr('action')             //=> 讀取值
form.attr('action', '/create')  //=> 設(shè)置值
form.attr('action', null)       //=> 移除屬性
// 多個屬性:
form.attr({
  action: '/create',
  method: 'post'
})

before

• before(content) ? self

在匹配每個元素的前面插入內(nèi)容（注：外部插入）。內(nèi)容可以為html字符串，dom節(jié)點，或者節(jié)點組成的數(shù)組。

$('table').before('<p>See the following table:</p>')

children

• children([selector]) ? collection

獲得每個匹配元素集合元素的直接子元素，如果給定selector，那么返回的結(jié)果中只包含符合css選擇器的元素。

$('ol').children('*:nth-child(2n)')
//=> every other list item from every ordered list

clone (3.0.0-rc.6)

• clone() ? collection

通過深度克隆來復(fù)制集合中的所有元素。

closest

• closest(selector, [context]) ? collection
• closest(collection) ? collection
• closest(element) ? collection

從元素本身開始，逐級向上級元素匹配，并返回最先匹配selector的元素。如果給定context節(jié)點參數(shù)，那么只匹配該節(jié)點的后代元素。這個方法與 parents(selector)有點相像，但它只返回最先匹配的祖先元素。

如果參數(shù)是一個jQuery對象集合或者一個元素，結(jié)果必須匹配給定的元素而不是選擇器。

var input = $('input[type=text]')
input.closest('form')

contents

• contents() ? collection

獲得每個匹配元素集合元素的子元素，包括文字和注釋節(jié)點。（注：.contents()和.children()方法類似，只不過前者包括文本節(jié)點以及jQuery對象中產(chǎn)生的HTML元素。）

css

• css(property) ? value
• css([property1, property2, ...]) ? object
• css(property, value) ? self
• css({ property: value, property2: value2, ... }) ? self

讀取或設(shè)置DOM元素的css屬性。當(dāng)value參數(shù)不存在的時候，返回對象集合中第一個元素的css屬性。當(dāng)value參數(shù)存在時，設(shè)置對象集合中每一個元素的對應(yīng)css屬性。

多個屬性可以通過傳遞一個屬性名組成的數(shù)組一次性獲取。多個屬性可以利用對象鍵值對的方式進行設(shè)置。

當(dāng)value為空(空字符串，null 或 undefined)，那個css屬性將會被移出。當(dāng)value參數(shù)為一個無單位的數(shù)字，如果該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

讀取或?qū)懭雂om的 data-* 屬性。行為有點像 attr ，但是屬性名稱前面加上 data-。

當(dāng)讀取屬性值時，會有下列轉(zhuǎn)換:

• “true”, “false”, and “null” 被轉(zhuǎn)換為相應(yīng)的類型；
• 數(shù)字值轉(zhuǎn)換為實際的數(shù)字類型；
• JSON值將會被解析，如果它是有效的JSON；
• 其它的一切作為字符串返回。

each

• each(function(index, item){ ... }) ? self

遍歷一個對象集合每個元素。在迭代函數(shù)中，this關(guān)鍵字指向當(dāng)前項(作為函數(shù)的第二個參數(shù)傳遞)。如果迭代函數(shù)返回 false，遍歷結(jié)束。

$('form input').each(function(index){
  console.log('input %d is: %o', index, this)
})

empty

• empty() ? self

清空對象集合中每個元素的DOM內(nèi)容。

eq

• eq(index) ? collection

從當(dāng)前對象集合中獲取給定索引值（注：以0為基數(shù)）的元素。

$('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選擇器的項。如果參數(shù)為一個函數(shù)，函數(shù)返回有實際值得時候，元素才會被返回。在函數(shù)中， this 關(guān)鍵字指向當(dāng)前的元素。

find

• find(selector) ? collection
• find(collection) ? collection v1.0+
• find(element) ? collection v1.0+

在當(dāng)對象前集合內(nèi)查找符合CSS選擇器的每個元素的后代元素。

如果給定Zepto對象集合或者元素，過濾它們，只有當(dāng)它們在當(dāng)前Zepto集合對象中時，才回被返回。

var form = $('#myform')
form.find('input, select')

first

• first() ? collection

獲取當(dāng)前對象集合中的第一個元素。

$('form').first()

forEach

• forEach(function(item, index, array){ ... }, [context])

遍歷對象集合中每個元素，有點類似 each，但是遍歷函數(shù)的參數(shù)不一樣，當(dāng)函數(shù)返回 false 的時候，遍歷不會停止。

get

• get() ? array
• get(index) ? DOM node

從當(dāng)前對象集合中獲取所有元素或單個元素。當(dāng)index參數(shù)不存在的時，以普通數(shù)組的方式返回所有的元素。當(dāng)指定index時，只返回該置的元素。這點與eq不同，該方法返回的是DOM節(jié)點，不是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

判斷當(dāng)前對象集合的子元素是否有符合選擇器的元素，或者是否包含指定的DOM節(jié)點，如果有，則返回新的對象集合，該對象過濾掉不含有選擇器匹配元素或者不含有指定DOM節(jié)點的對象。

$('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

獲取對象集合中第一個元素的高度；或者設(shè)置對象集合中所有元素的高度。

const height = await $('#foo').height() // => 123

:::caution 請注意 height() 返回的 Promise 對象。 :::

hide

• hide() ? self

通過設(shè)置css的屬性 display 為 none 來將對象集合中的元素隱藏。

html

• html() ? string
• html(content) ? self
• html(function(index, oldHtml){ ... }) ? self

獲取或設(shè)置對象集合中元素的HTML內(nèi)容。當(dāng)沒有給定content參數(shù)時，返回對象集合中第一個元素的innerHtml。當(dāng)給定content參數(shù)時，用其替換對象集合中每個元素的內(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

• index([element]) ? number

獲取一個元素的索引值（注：從0開始計數(shù)）。當(dāng)elemen參數(shù)沒有給出時，返回當(dāng)前元素在兄弟節(jié)點中的位置。當(dāng)element參數(shù)給出時，返回它在當(dāng)前對象集合中的位置。如果沒有找到該元素，則返回-1。

$('li:nth-child(2)').index()  //=> 1

insertAfter

• insertAfter(target) ? self

將集合中的元素插入到指定的目標(biāo)元素后面（注：外部插入）。這個有點像 after，但是使用方式相反。

$('<p>Emphasis mine.</p>').insertAfter('blockquote')

insertBefore

• insertBefore(target) ? self

將集合中的元素插入到指定的目標(biāo)元素前面（注：外部插入）。這個有點像 before，但是使用方式相反。

$('<p>See the following table:</p>').insertBefore('table')

last

• last() ? collection

獲取對象集合中最后一個元素。

$('li').last()

map

• map(function(index, item){ ... }) ? collection

遍歷對象集合中的所有元素。通過遍歷函數(shù)返回值形成一個新的集合對象。在遍歷函數(shù)中this關(guān)鍵之指向當(dāng)前循環(huán)的項（遍歷函數(shù)中的第二個參數(shù)）。

遍歷中返回 null和undefined，遍歷將結(jié)束。

elements.map(function(){ return $(this).text() }).get().join(', ')

next

• next() ? collection
• next(selector) ? collection

獲取對象集合中每一個元素的下一個兄弟節(jié)點(可以選擇性的帶上過濾選擇器)。

not

• not(selector) ? collection
• not(collection) ? collection
• not(function(index){ ... }) ? collection

過濾當(dāng)前對象集合，獲取一個新的對象集合，它里面的元素不能匹配css選擇器。如果另一個參數(shù)為Zepto對象集合，那么返回的新Zepto對象中的元素都不包含在該參數(shù)對象中。如果參數(shù)是一個函數(shù)。僅僅包含函數(shù)執(zhí)行為false值得時候的元素，函數(shù)的 this 關(guān)鍵字指向當(dāng)前循環(huán)元素。

與它相反的功能，查看 filter。

offset

• offset() ? Promise<object>
• offset(coordinates) ? self
• offset(function(index, oldOffset){ ... }) ? self

獲得當(dāng)前元素相對于document的位置。返回一個對象含有： top, left, width和height。

offsetParent

• offsetParent() ? collection

找到第一個定位過的祖先元素，意味著它的css中的 position 屬性值為“relative”, “absolute” or “fixed”

parent

• parent([selector]) ? collection

獲取對象集合中每個元素的直接父元素。如果css選擇器參數(shù)給出。過濾出符合條件的元素。

parents

• parents([selector]) ? collection

獲取對象集合每個元素所有的祖先元素。如果css選擇器參數(shù)給出，過濾出符合條件的元素。

如果想獲取直接父級元素，使用 parent。如果只想獲取到第一個符合css選擇器的元素，使用closest。

$('h1').parents()   //=> [<div#container>, <body>, <html>]

position

• position() ? object

獲取對象集合中第一個元素的位置。相對于 offsetParent。當(dāng)絕對定位的一個元素靠近另一個元素的時候，這個方法是有用的。

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

將參數(shù)內(nèi)容插入到每個匹配元素的前面（注：元素內(nèi)部插入）。插入d的元素可以試html字符串片段，一個dom節(jié)點，或者一個節(jié)點的數(shù)組。

$('ul').prepend('<li>first list item</li>')

prependTo

• prependTo(target) ? self

將所有元素插入到目標(biāo)前面（注：元素內(nèi)部插入）。這有點像prepend，但是是相反的方式。

$('<li>first list item</li>').prependTo('ul')

prev

• prev() ? collection
• prev(selector) ? collection

獲取對象集合中每一個元素的前一個兄弟節(jié)點，通過選擇器來進行過濾。

prop

• prop(name) ? value
• prop(name, value) ? self
• prop(name, function(index, oldValue){ ... }) ? self

讀取或設(shè)置dom元素的屬性值。它在讀取屬性值的情況下優(yōu)先于 attr，因為這些屬性值會因為用戶的交互發(fā)生改變，如checked 和 selected。

簡寫或小寫名稱，比如for, class, readonly及類似的屬性，將被映射到實際的屬性上，比如htmlFor, className, readOnly, 等等。

remove

• remove() ? self

從其父節(jié)點中刪除當(dāng)前集合中的元素，有效的從dom中移除。

removeAttr

• removeAttr(name) ? self

移除當(dāng)前對象集合中所有元素的指定屬性。

removeClass

• removeClass([name]) ? self
• removeClass(function(index, oldClassName){ ... }) ? self

移除當(dāng)前對象集合中所有元素的指定class。如果沒有指定name參數(shù)，將移出所有的class。多個class參數(shù)名稱可以利用空格分隔。下例移除了兩個class。

$("#check1").removeClass("test")

removeProp

• removeProp(name) ? self

從集合的每個DOM節(jié)點中刪除一個屬性。這是用JavaScript的delete操作符完成。值得注意的是如果嘗試刪除DOM的一些內(nèi)置屬性，如className或maxLength，將不會有任何效果，因為瀏覽器禁止刪除這些屬性。

replaceWith

• replaceWith(content) ? self

用給定的內(nèi)容替換所有匹配的元素。(包含元素本身)。content參數(shù)可以為 before中描述的類型。

scrollLeft

• scrollLeft() => Promise<number>
• scrollLeft(value) ? self

獲取或設(shè)置頁面上的滾動元素或者整個窗口向右滾動的像素值。

const height = await $('#foo').scrollLeft() // => 123

scrollTop

• scrollTop() => Promise<number>
• scrollTop(value) ? self

獲取或設(shè)置頁面上的滾動元素或者整個窗口向下滾動的像素值。

const height = await $('#foo').scrollTop() // => 123

show

• show() ? self

siblings

• siblings([selector]) ? collection

獲取對象集合中所有元素的兄弟節(jié)點。如果給定CSS選擇器參數(shù)，過濾出符合選擇器的元素。

size

• size() ? number

獲取對象集合中元素的數(shù)量。

slice

• slice(start, [end]) ? array

提取這個數(shù)組array的子集，從start開始，如果給定end，提取從從start開始到end結(jié)束的元素，但是不包含end位置的元素。

text

• text() ? string
• text(content) ? self
• text(function(index, oldText){ ... }) ? self

獲取或者設(shè)置所有對象集合中元素的文本內(nèi)容。當(dāng)沒有給定content參數(shù)時，返回當(dāng)前對象集合中第一個元素的文本內(nèi)容（包含子節(jié)點中的文本內(nèi)容）。當(dāng)給定content參數(shù)時，使用它替換對象集合中所有元素的文本內(nèi)容。它有待點似 html，與它不同的是它不能用來獲取或設(shè)置 HTML。

toggle

• toggle([setting]) ? self

顯示或隱藏匹配元素。如果 setting 為 true，相當(dāng)于 show() 。如果setting為false。相當(dāng)于 hide()。

toggleClass

• toggleClass(names, [setting]) ? self
• toggleClass(function(index, oldClassNames){ ... }, [setting]) ? self

在匹配的元素集合中的每個元素上添加或刪除一個或多個樣式類。如果class的名稱存在則刪除它，如果不存在，就添加它。如果 setting的值為真，這個功能類似于 addClass，如果為假，這個功能類似與 removeClass。

unwrap

• unwrap() ? self

移除集合中每個元素的直接父節(jié)點，并把他們的子元素保留在原來的位置。 基本上，這種方法刪除上一的祖先元素，同時保持DOM中的當(dāng)前元素。

val

• val() ? string
• val(value) ? self
• val(function(index, oldValue){ ... }) ? self

獲取或設(shè)置匹配元素的值。當(dāng)沒有給定value參數(shù)，返回第一個元素的值。當(dāng)給定value參數(shù)，那么將設(shè)置所有元素的值。

width

• width() ? Promise<number>
• width(value) ? self
• width(function(index, oldWidth){ ... }) ? self

獲取對象集合中第一個元素的寬；或者設(shè)置對象集合中所有元素的寬。

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()添加的那個相同的函數(shù)。否則，只通過事件類型調(diào)用此方法將移除該類型的所有處理程序。如果沒有參數(shù)，將移出當(dāng)前元素上全部的注冊事件。

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

添加事件處理程序到對象集合中得元素上。多個事件可以通過空格的字符串方式添加，或者以事件類型為鍵、以函數(shù)為值的對象 方式。如果給定css選擇器，當(dāng)事件在匹配該選擇器的元素上發(fā)起時，事件才會被觸發(fā)（注：即事件委派，或者說事件代理）。

如果給定data參數(shù)，這個值將在事件處理程序執(zhí)行期間被作為有用的 event.data 屬性

事件處理程序在添加該處理程序的元素、或在給定選擇器情況下匹配該選擇器的元素的上下文中執(zhí)行(注：this指向觸發(fā)事件的元素)。 當(dāng)一個事件處理程序返回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

• 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() 一樣，添加一個處理事件到元素，當(dāng)?shù)谝淮螆?zhí)行事件以后，該事件將自動解除綁定，保證處理函數(shù)在每個元素上最多執(zhí)行一次。

trigger

• trigger(event, [args]) ? self

在對象集合的元素上觸發(fā)指定的事件。如果給定args參數(shù)，它會作為參數(shù)傳遞給事件函數(shù)。

$('#test').trigger('tap', ['one', 'two'])

triggerHandler

• triggerHandler(event, [args]) ? self

和 trigger 一樣，它只在當(dāng)前元素上觸發(fā)事件，但不冒泡。