WXML

createSelectorQuery

TIP

該API使用方法為： SelectorQuery wx.createSelectorQuery()

功能說明： 返回一個SelectorQuery對象實例，在自定義組件或包含自定義組件的頁面中，用this.createSelectorQuery（）來代替。
返回值： SelectorQuery
示例代碼：

const query = wx.createSelectorQuery()
query.select('#the-id').boundingClientRect()
query.selectViewport().scrollOffset()
query.exec(function (res) {
  res[0].top // The upper boundary coordinate of the #the-id node.
  res[1].scrollTop // The vertical scroll position of the display area.
})

createIntersectionObserver

TIP

該API使用方法為： IntersectionObserver wx.createIntersectionObserver(Object component, Object options)

功能說明： 創建並返回一個IntersectionObserver對象實例。在自定義組件或包含自定義組件的頁面中，應使用this.createIntersectionObserver（[options]）來代替。

參數及說明：

Object component, 自定義組件實例。

Object options，合法值如下：

内容	類型	預設值	必填	說明
thresholds	Array.<`number`>	[0]	否	一個數值數組，包含所有閾值
initialRatio	number	0	否	初始的相交比例，如果調用時檢測到的相交比例與這個值不相等且達到閾值，則會觸發一次監聽器的回呼函數
observeAll	boolean	false	否	是否同時觀測多個目標節點（而非一個），如果設為true，observe的targetSelector將選中多個節點（注意：同時選中過多節點將影響渲染效能）

返回值： IntersectionObserver

IntersectionObserver

ntersectionObserver對象，用於推斷某些節點是否可以被用戶看見、有多大比例可以被用戶看見。

.relativeTo

TIP

該API使用方法為： IntersectionObserver.relativeTo(string selector, Object margins)

功能說明： 使用選擇器指定一個節點，作為參照區域之一。

參數及說明：

string selector, 選擇器。

Object margins, 用來擴展（或收縮）參照節點佈局區域的邊界。

内容	類型	預設值	必填	說明
left	number	-	否	節點佈局區域的左邊界
right	number	-	否	節點佈局區域的右邊界
top	number	-	否	節點佈局區域的上邊界
bottom	number	-	否	節點佈局區域的下邊界

.relativeToViewport

TIP

該API使用方法為： IntersectionObserver.relativeToViewport(Object margins)

功能說明： 指定頁面顯示區域作為參照區域之一。

參數及說明： Object margins, 用來擴展（或收縮）參照節點佈局區域的邊界。

内容	類型	預設值	必填	說明
left	number	-	否	節點佈局區域的左邊界
right	number	-	否	節點佈局區域的右邊界
top	number	-	否	節點佈局區域的上邊界
bottom	number	-	否	節點佈局區域的下邊界

示例代碼：
下麵的示例代碼中，如果目標節點（用選擇器.target-class指定）進入顯示區域以下100px時，就會觸發回呼函數。

Page({
  onLoad() {
    wx.createIntersectionObserver().rela
  onLoad: function(){
    wx.createIntersectionObserver().relativeToViewport({bottom: 100}).observe('.target-class', (res) => {
      res.intersectionRatio // the ratio of the intersection region to the layout region of the target node
      res.intersectionRect // intersection region
      res.intersectionRect.left // coordinates of the left boundary of the intersection region
      res.intersectionRect.top // the upper boundary of the intersection region
      res.intersectionRect.width // width of the intersection region
      res.intersectionRect.height // height of the intersection region
    })
  }
})

.disconnect

TIP

該API使用方法為： IntersectionObserver.disconnect()

功能說明： 停止監聽。回呼函數將不再觸發。

.observe

TIP

該API使用方法為： IntersectionObserver.observe(string targetSelector, function callback)

功能說明： 指定目標節點並開始監聽相交狀態變化情况。

參數及說明：

string targetSelector, 選擇器。

function callback, 監聽相交狀態變化的回呼函數，參數Object res如下：

内容	類型	說明
intersectionRatio	number	相交比例
intersectionRect	number	相交區域的邊界
boundingClientRect	number	目標邊界
relativeRect	number	參照區域的邊界
time	number	相交檢測時的時間戳記

res.intersectionRect的結構
結構内容類型說明
left number 左邊界
right number 右邊界
top number 上邊界
bottom number 下邊界
width number 寬度
height number 高度
res.boundingClientRect的結構
結構内容類型說明
left number 左邊界
right number 右邊界
top number 上邊界
bottom number 下邊界
width number 寬度
height number 高度
res.relativeRect的結構
結構内容類型說明
left number 左邊界
right number 右邊界
top number 上邊界
bottom number 下邊界

結構内容	類型	說明
left	number	左邊界
right	number	右邊界
top	number	上邊界
bottom	number	下邊界
width	number	寬度
height	number	高度

結構内容	類型	說明
left	number	左邊界
right	number	右邊界
top	number	上邊界
bottom	number	下邊界
width	number	寬度
height	number	高度

結構内容	類型	說明
left	number	左邊界
right	number	右邊界
top	number	上邊界
bottom	number	下邊界

NodesRef

用於獲取WXML節點資訊的對象。

.fields

TIP

該API使用方法為： NodesRef.fields(Object fields, function callback)

功能說明： 獲取節點的相關資訊。需要獲取的欄位在fields中指定。返回值是nodesRef對應的selectorQuery

參數及說明：

Object fields, 合法參數如下：

内容	類型	預設值	必填	說明
id	boolean	false	否	是否返回節點id
dataset	boolean	false	否	是否返回節點dataset
rect	boolean	false	否	是否返回節點佈局位置（left、right、top、bottom）
size	boolean	false	否	是否返回節點尺寸（width、height）
scrollOffset	boolean	false	否	是否返回節點的scrollLeft scrollTop，節點必須是scroll-view或者viewport
properties	Array.<`string`>	[]	否	指定内容名清單，返回節點對應内容名的當前屬性值（只能獲得組件文件中標注的常規屬性值，id class style和事件綁定的屬性值不可獲取）
computedStyle	Array.<`string`>	[]	否	指定樣式名清單，返回節點對應樣式名的當前值
context	boolean	false	否	是否返回節點對應的Context對象

function callback, 回呼函數，參數Object res為節點相關資訊。
返回值： nodesRef對應的selectorQuery。

TIP

computedStyle的優先順序高於size，當同時在computedStyle裏指定了width/height和傳入了size: true，則優先返回computedStyle獲取到的width/height。

示例代碼：

  Page({
  getFields () {
    wx.createSelectorQuery().select('#the-id').fields({
      dataset: true,
      size: true,
      scrollOffset: true,
      properties: ['scrollX', 'scrollY'],
      computedStyle: ['margin', 'backgroundColor'],
      context: true, }, function (res) { {
    }, function (res) {
      res.dataset // the node's dataset
      res.width // width of the node
      res.height // the height of the node
      res.scrollLeft // The horizontal scroll position of the node.
      res.scrollTop // The vertical scroll position of the node.
      res.scrollX // The current value of the node's scroll-x property.
      res.scrollY // The current value of the node's scroll-y property.
      // This returns the name of the style to be returned.
      res.margin
      res.backgroundColor
      res.context // The node's corresponding Context object.
      res.ref // The Ref object for the node.
    res.ref // Ref object for the node }).exec()
  }
})

.boundingClientRect

TIP

該API使用方法為： SelectorQuery NodesRef.boundingClientRect(function callback)

功能說明： 添加節點的佈局位置的査詢請求。相對於顯示區域，以點數為單位。其功能類似於DOM的getBoundingClientRect。

參數及說明： function callback。回呼函數，在執行 SelectorQuery.exec 方法後，節點資訊會在callback中返回。

Object res

内容	類型	說明
id	string	節點的ID
dataset	Object	節點的dataset
left	number	節點的左邊界座標
right	number	節點的右邊界座標
top	number	節點的上邊界座標
bottom	number	節點的下邊界座標
width	number	節點的寬度
height	number	節點的高度

返回值： SelectorQuery
示例代碼：

Page({
  getRect() {
    wx.createSelectorQuery().select('#the-id').boundingClientRect(function (rect) {
      rect.id // Node's ID
      rect.dataset // Node's dataset
      rect.left // Node's left boundary coordinate
      rect.right // Node's right boundary coordinate
      rect.top // Node's upper boundary coordinate
      rect.bottom // Node's lower boundary coordinate
      rect.width // Node's width
      rect.height // Node's height
    }).exec()
  },
  getAllRects() {
    wx.createSelectorQuery().selectAll('.a-class').boundingClientRect(function (rects) {
      rects.forEach(function (rect) {
        rect.id // Node's ID
        rect.dataset // Node's dataset
        rect.left // Node's left boundary coordinate
        rect.right // Node's right boundary coordinate
        rect.top // Node's upper boundary coordinate
        rect.bottom // Node's lower boundary coordinate
        rect.width // Node's width
        rect.height // Node's height
      })
    }).exec()
  }
})

.scrollOffset

TIP

該API使用方法為： SelectorQuery NodesRef.scrollOffset(function callback)

功能說明： 添加節點的滾動位置査詢請求。以點數為單位。節點必須是scroll-view或者viewport。
參數及說明： function callback。回呼函數，在執行 SelectorQuery.exec 方法後，節點資訊會在callback中返回。
- Object res
  内容類型說明
  id string 節點的ID
  dataset string 節點的dataset
  scrollLeft number 節點的水准滾動位置
  scrollTop number 節點的豎直滾動位置
返回值： SelectorQuery
示例代碼：

Page({
  getScrollOffset() {
    wx.createSelectorQuery().selectViewport().scrollOffset(function (res) {
      res.id // Node's ID
      res.dataset // Node's dataset
      res.scrollLeft // Node's horizontal scroll position
      res.scrollTop // Node's vertical scroll position
    }).exec()
  }
})

.context

TIP

該API使用方法為： SelectorQuery NodesRef.context(function callback)

功能說明： 添加節點的Context對象査詢請求。現時支持 MapContext 的獲取。
參數及說明： function callback。回呼函數，在執行 SelectorQuery.exec 方法後，節點資訊會在callback中返回。
- Object res
  内容類型說明
  context Object 節點對應的Context對象
返回值： SelectorQuery
示例代碼：

内容	類型	說明
context	Object	節點對應的Context對象

Page({
  getContext() {
    wx.createSelectorQuery().select('.the-video-class').context(function (res) {
      console.log(res.context) // Context object corresponding to the node. For instance, if the selected node is a <map> component, then a MapContext object is returned here.
    }).exec()
  }
})

.node

TIP

該API使用方法為： SelectorQuery NodesRef.node(function callback)

功能說明： 獲取Node節點實例。現時支持 ScrollViewContext 和 Canvas 的獲取。
參數及說明： function callback。回呼函數，在執行 SelectorQuery.exec 方法後，節點資訊會在callback中返回。
- Object res
  内容類型說明
  node Object 節點對應的Node實例
返回值： SelectorQuery
示例代碼：

内容	類型	說明
node	Object	節點對應的Node實例

Page({
  getNode() {
    wx.createSelectorQuery().select('.canvas').node(function(res){
      console.log(res.node) // Canvas instance corresponding to the node.
    }).exec()
  }
})

SelectorQuery

査詢節點資訊的對象

.exec

TIP

該API使用方法為： NodesRef SelectorQuery.exec(function callback)

功能說明： 執行所有的請求。請求結果按請求次序構成數組，在callback的第一個參數中返回。
參數及說明： function callback。回呼函數
返回值： NodesRef

.in

TIP

該API使用方法為： SelectorQuery SelectorQuery.in(Component component)

功能說明： 將選擇器的選取範圍更改為自定義組件component內。（初始時，選擇器僅選取頁面範圍的節點，不會選取任何自定義組件中的節點）。
參數及說明： Component component，自定義組件實例。
返回值： SelectorQuery
示例代碼：

Component({
  queryMultipleNodes() {
    const query = wx.createSelectorQuery().in(this)
    query.select('#the-id').boundingClientRect(function (res) {
      res.top // The upper boundary coordinate of the #the-id node within this component.
    }).exec()
  }
})

.select

TIP

該API使用方法為： NodesRef SelectorQuery.select(string selector)

功能說明： 在當前頁面下選擇第一個匹配選擇器selector的節點。返回一個NodesRef對象實例，可以用於獲取節點資訊。
參數及說明： string selector，選擇器。
返回值： NodesRef
selector語法： selector類似於CSS的選擇器，但僅支持下列語法：
- ID選擇器： #the-id。
- class選擇器（可以連續指定多個）： .a-class.another-class。
- 子元素選擇器： .the-parent > .the-child。
- 後代選擇器： .the-ancestor .the-descendant。
- 跨自定義組件的後代選擇器： .the-ancestor >>> .the-descendant。
- 多選擇器的並集： #a-node, .some-other-nodes。

.selectAll

TIP

該API使用方法為： NodesRef SelectorQuery.selectAll(string selector)

功能說明： 在當前頁面下選擇匹配選擇器selector的所有節點。
參數及說明： string selector，選擇器。
返回值： NodesRef
selector語法： selector類似於CSS的選擇器，但僅支持下列語法：
- ID選擇器： #the-id。
- class選擇器（可以連續指定多個）： .a-class.another-class。
- 子元素選擇器： .the-parent > .the-child。
- 後代選擇器： .the-ancestor .the-descendant。
- 跨自定義組件的後代選擇器： .the-ancestor >>> .the-descendant。
- 多選擇器的並集： #a-node, .some-other-nodes。

.selectViewport

TIP

該API使用方法為： NodesRef SelectorQuery.selectViewport()

功能說明： 選擇顯示區域。可用於獲取顯示區域的尺寸、滾動位置等資訊
返回值： NodesRef

MediaQueryObserver

MediaQueryObserver對象，用於監聽頁面media query狀態的變化，如介面的長寬是不是在某個指定的範圍內。

.disconnect

TIP

該API使用方法為： MediaQueryObserver.disconnect()

功能說明： 停止監聽。回呼函數將不再觸發。

.observe

TIP

該API使用方法為： MediaQueryObserver.observe(Object descriptor, function callback)

功能說明： 開始監聽頁面media query變化情况。

參數及說明：

Object descriptor，media query描述符。

内容	類型	預設值	必填	說明
minWidth	number	-	是	頁面最小寬度（px為單位）
maxWidth	number	-	是	頁面最大寬度（px為單位）
width	number	-	是	頁面寬度（px為單位）
minHeight	number	-	是	頁面最小高度（px為單位）
maxHeight	number	-	是	頁面最大高度（px為單位）
height	number	-	是	頁面高度（px為單位）
orientation	string	-	是	荧幕方向（landscape或portrait）

function callback，監聽media query狀態變化的回呼函數。參數Object res如下：
内容類型說明
matches boolean 頁面的當前狀態是否滿足所指定的media query

WXML ​

createSelectorQuery ​

createIntersectionObserver ​

IntersectionObserver ​

.relativeTo ​

.relativeToViewport ​

.disconnect ​

.observe ​

NodesRef ​

.fields ​

.boundingClientRect ​

.scrollOffset ​

.context ​

.node ​

SelectorQuery ​

.exec ​

.in ​

.select ​

.selectAll ​

.selectViewport ​

MediaQueryObserver ​

.disconnect ​

.observe ​

WXML

createSelectorQuery

createIntersectionObserver

IntersectionObserver

.relativeTo

.relativeToViewport

.disconnect

.observe

NodesRef

.fields

.boundingClientRect

.scrollOffset

.context

.node

SelectorQuery

.exec

.in

.select

.selectAll

.selectViewport

MediaQueryObserver

.disconnect

.observe