wx.createSelectorQuery()

从 2.0.7 版本开始支持

返回一个 SelectorQuery 对象实例

参数

无

---

SelectorQuery

查询节点信息的对象，实例的方法用于添加要查询节点的请求

实例的方法

NodesRef SelectorQuery.select(string selector)

在当前页面下选择第一个匹配选择器 selector 的节点。返回一个 NodesRef 对象实例，可以用于获取节点信息

参数

属性	类型	默认值	必填	说明
selector	string		是	选择器

注意

selector类似于 CSS 的选择器，但仅支持下列语法：
1.ID选择器：#the-id
2.class选择器（可以连续指定多个）：.a-class.another-class
3.子元素选择器：.the-parent > .the-child
4.后代选择器：.the-ancestor .the-descendant

NodesRef SelectorQuery.selectAll(string selector)

在当前页面下选择匹配选择器 selector 的所有节点

参数

同SelectorQuery.select参数

NodesRef SelectorQuery.selectViewport()

选择显示区域。可用于获取显示区域的尺寸、滚动位置等信息

NodesRef SelectorQuery.exec(function callback)

执行所有的请求。请求结果按请求次序构成数组，在callback的第一个参数中返回，返回的数据由selector等多个参数决定，不同参数返回数据不同

参数

属性	类型	默认值	必填	说明
callback	function		否	回调函数，返回值res，表示查询结果数组

---

NodesRef

用于获取 WXML 节点信息的对象，实例的方法用于添加要查询节点具体属性的请求

实例的方法

SelectorQuery NodesRef.fields(Object fields, function callback)

添加自定义查询请求，获取节点的相关信息，需要获取的字段在fields中指定。返回值是 nodesRef 对应的 selectorQuery

参数

属性	类型	默认值	必填	说明
fields	Object		否	筛选的条件
callback	function		否	回调函数，返回值res，表示节点信息

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.<Object>	[]	否	指定属性名列表，返回节点对应属性名的当前属性值（只能获得组件文档中标注的常规属性值，id class style 和事件绑定的属性值不可获取）
computedStyle	Array.<Object>	[]	否	指定样式名列表，返回节点对应样式名的当前值
node	boolean	false	否	是否返回节点对应的 node 对象，只用于获取 canvas 节点

注意

computedStyle 的优先级高于 size，当同时在 computedStyle 里指定了 width/height 和传入了 size: true，则优先返回 computedStyle 获取到的 width/height

SelectorQuery NodesRef.boundingClientRect(function callback)

添加节点的布局位置的查询请求，以像素为单位。其功能类似于 DOM 的 getBoundingClientRect。返回 NodesRef 对应的 SelectorQuery

参数

属性	类型	默认值	必填	说明
callback	function		否	回调函数，在执行 SelectorQuery.exec 方法后，节点信息会在 callback 中返回

返回参数

属性	类型	说明
id	string	节点的 ID
dataset	Object	节点的 dataset
left	number	节点的左边界坐标
right	number	节点的右边界坐标
top	number	节点的上边界坐标
bottom	number	节点的下边界坐标
width	number	节点的宽度
height	number	节点的高度

SelectorQuery NodesRef.scrollOffset(function callback)

添加节点的滚动位置查询请求，以像素为单位。节点必须是 scroll-view 或者 viewport。返回 NodesRef 对应的 SelectorQuery

参数

属性	类型	默认值	必填	说明
callback	function		否	回调函数，在执行 SelectorQuery.exec 方法后，节点信息会在 callback 中返回

返回参数

属性	类型	说明
id	string	节点的 ID
dataset	Object	节点的 dataset
scrollLeft	number	节点的水平滚动位置
scrollTop	number	节点的竖直滚动位置
scrollWidth	number	节点的可滚动宽度
scrollHeight	number	节点的可滚动高度

SelectorQuery NodesRef.node(function callback)

添加获取 Node 节点（canvas）实例的请求，返回 NodesRef 对应的 SelectorQuery

参数

属性	类型	默认值	必填	说明
callback	function		否	回调函数，在执行 SelectorQuery.exec 方法后，节点信息会在 callback 中返回

返回参数

属性	类型	说明
node	Object	节点对应的 Node 实例
nodeCanvasType	String	canvas的上下文type

注意

该接口只可用于获取 canvas 实例，实例对应 canvas组件，且canvas组件必须配置type属性。通过 Canvas.getContext(‘2d’) 接口可以获取 CanvasRenderingContext2D 对象，具体内容详见 CanvasRenderingContext2D 对象。使用方式可参考H5的 canvas ，api基本一致。

示例代码

WXML

<view>
  <view wx:for="{{[1,2,3,4,5,6]}}" wx:key="index" id="{{'view' + index}}" class="{{'view' + index + index}}">
    <text class="{{'text' + index}}">{{item}}</text>
  </view>
  <canvas type="2d" id="canvas" class="canvas"></canvas>
</view>

JS

Page({
  onReady: function() {
    const query = wx.createSelectorQuery();
    query.select('#view1').fields({
      dataset: true,
      size: true,
      scrollOffset: true,
      properties: ['scrollX', 'scrollY'],
      computedStyle: ['margin', 'backgroundColor']
    });
    query.select('#view1').boundingClientRect();
    query.selectViewport().scrollOffset();
    query.select('#canvas').node();
    query.selectAll('.text1').boundingClientRect();
    query.exec(function(res){
      console.log(res[0]); // 返回id为view1的元素的在fields中指定的属性
      console.log(res[1]); // 返回id为view1的元素的宽高等信息
      console.log(res[2]); // 返回viewport的滚动信息
      console.log(res[3]); // 返回对应canvas节点实例
      if (res[3] && res[3].node) {
        const canvasNode = res[3].node;
        const ctx = canvasNode.getContext('2d');
        ctx.fillStyle = 'green';
        ctx.fillRect(20, 10, 150, 100);
      }
    });
  }
})

注释：

1.目前接口查询范围为当前page内所有dom节点，不支持自定义组件查询
2.SelectorQuery 和 NodesRef 的实例方法必须配套使用，见示例代码，且最后必须调用exec方法才会发起真实的查询请求并返回结果
3.请在onReady生命周期内或以后再调用该方法
4.因系统版本、webview内核不同，不同系统查询到的宽高属性会存在差异，部分组件的 computedStyle 的宽高属性会返回auto，可使用 size: true 获取实际的宽高信息
5.目前 data- 相关属性传入基础数据类型会自动转为字符串，可在获取到 dataset 数据后自行处理数据类型