uni.createSelectorQuery()

返回一个SelectorQuery对象实例

createSelectorQuery是小程序的API，因小程序未开放DOM，且视图层和逻辑层分离，于是提供了一个异步的API，可以在逻辑层有限的获取一些DOM能力。

该API返回的类型为NodeRef。它和DOM的Element有区别。

大多数组件的属性和样式操作，是通过绑定vue的响应式变量data来实现的。一般不使用本API。

本API的主要用途是小程序下获取元素计算后的样式。如果您的应用不适配小程序，那么在Web和App上有更强大的UniElement。

小程序下有时用本API获取部分组件的上下文context，但这个写法不跨平台。跨平台的获取组件context，应该使用uni.createXXContext()。

createSelectorQuery 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	3.91	4.11	4.61

selector 说明：

selector 类似于 CSS 的选择器，但仅支持下列语法。

• ID选择器：#the-id
• class选择器：.a-class

返回值

类型
SelectorQuery

SelectorQuery 的方法

in(component: any | null): SelectorQuery

将选择器的选取范围更改为自定义组件component内

in 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
-	4.41	-	-	-

参数

名称	类型	必填	默认值	兼容性	描述
component	any	否	-	-

返回值

类型
SelectorQuery

select(selector: string): NodesRef

在当前页面下选择第一个匹配选择器selector的节点

select 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
-	4.41	-	-	-

参数

名称	类型	必填	默认值	兼容性	描述
selector	string	是	-	-	-

返回值

类型
NodesRef

NodesRef 的方法

boundingClientRect( callback: SelectorQueryNodeInfoCallback | null, ): SelectorQuery

添加节点的布局位置的查询请求，相对于显示区域，以像素为单位

boundingClientRect 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
-	-	-	-	-

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	否	-	-

返回值

类型
SelectorQuery

scrollOffset(callback: SelectorQueryNodeInfoCallback): SelectorQuery

添加节点的滚动位置查询请求，以像素为单位

scrollOffset 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
-	-	-	-	-

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-

返回值

类型
SelectorQuery

fields( fields: NodeField, callback: SelectorQueryNodeInfoCallback | null, ): SelectorQuery

获取节点的相关信息，需要获取的字段在fields中指定

fields 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	4.25	4.25	-

参数

名称	类型	必填	默认值	兼容性	描述
fields	NodeField	是	-	-	-
名称 类型 必备 默认值 兼容性 描述 id boolean 否 - - 是否返回节点 id dataset boolean 否 - - 是否返回节点 dataset rect boolean 否 - - 是否返回节点布局位置（left right top bottom） size boolean 否 - - 是否返回节点尺寸（width height） scrollOffset boolean 否 - - 是否返回节点的 scrollLeft scrollTop，节点必须是 scroll-view 或者 viewport properties Array<string> 否 - - 指定属性名列表，返回节点对应属性名的当前属性值（只能获得组件文档中标注的常规属性值，id class style 和事件绑定的属性值不可获取） computedStyle Array<string> 否 - - 指定样式名列表，返回节点对应样式名的当前值 context boolean 否 - Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 x x - 是否返回节点对应的 Context 对象 node boolean 否 - - 是否返回节点对应的 Node 实例
callback	(result: any) => void	否	-	-

返回值

类型
SelectorQuery

context(callback: SelectorQueryNodeInfoCallback): SelectorQuery

添加节点的 Context 对象查询请求

context 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	x	x	-

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-

返回值

类型
SelectorQuery

node(callback: (result: any) => void): SelectorQuery

获取 Node 节点实例。目前支持 Canvas 的获取。 获取节点的相关信息，需要获取的字段在fields中指定

node 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	4.25	4.25	-

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

返回值

类型
SelectorQuery

selectAll(selector: string): NodesRef

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

selectAll 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
-	4.41	-	-	-

参数

名称	类型	必填	默认值	兼容性	描述
selector	string	是	-	-	-

返回值

类型
NodesRef

selectViewport(): NodesRef

选择显示区域

selectViewport 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
-	4.41	-	-	-

返回值

类型
NodesRef

exec(callback: (result: Array<any>) => void | null): NodesRef | null

执行所有的请求

exec 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
-	4.41	-	-	-

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: Array<any>) => void	是	-	-	-

返回值

类型	必备
NodesRef	否

NodeInfo 属性值

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

参见

• 相关 Bug
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

组件内使用

<template>
  <view>
    <button @click="getNodeInfo">getNodeInfo</button>
    <view class="rect-1-2">
      <view class="rect rect1"></view>
      <view class="rect rect2"></view>
    </view>
  </view>
</template>

<script>
  export default {
    data() {
      return {
        nodeInfoList: [] as NodeInfo[]
      }
    },
    props: {
    },
    methods: {
      getNodeInfo() {
        uni.createSelectorQuery().in(this).select('.rect1').boundingClientRect().exec((ret) => {
          this.nodeInfoList.length = 0
          this.nodeInfoList.push(ret[0] as NodeInfo)
        })
      }
    }
  }
</script>

示例

hello uni-app x

扫码体验（手机浏览器跳转到App直达页）

扫码体验

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view class="page-scroll-view">
  <!-- #endif -->
    <view class="page" id="page">
      <page-head :title="title"></page-head>
      <button class="btn btn-get-node-info" @click="getNodeInfo">getNodeInfo</button>
      <button class="btn btn-get-all-node-info" @click="getAllNodeInfo">getAllNodeInfo</button>
      <view id="rect-1-2" class="rect-1-2">
        <view class="rect rect1"></view>
        <view class="rect rect2"></view>
      </view>
      <view class="rect-info-1-2">
        <view class="rect-info" v-for="(nodeInfo, index) in nodeInfoList" :key="index">
          <view class="node-info-item">
            <text class="node-info-item-k">left: </text>
            <text class="node-info-item-v">{{nodeInfo.left}}</text>
          </view>
          <view class="node-info-item">
            <text class="node-info-item-k">top: </text>
            <text class="node-info-item-v">{{nodeInfo.top}}</text>
          </view>
          <view class="node-info-item">
            <text class="node-info-item-k">right: </text>
            <text class="node-info-item-v">{{nodeInfo.right}}</text>
          </view>
          <view class="node-info-item">
            <text class="node-info-item-k">bottom: </text>
            <text class="node-info-item-v">{{nodeInfo.bottom}}</text>
          </view>
          <view class="node-info-item">
            <text class="node-info-item-k">width: </text>
            <text class="node-info-item-v">{{nodeInfo.width}}</text>
          </view>
          <view class="node-info-item">
            <text class="node-info-item-k">height: </text>
            <text class="node-info-item-v">{{nodeInfo.height}}</text>
          </view>
        </view>
      </view>
      <node-child class="node-child"></node-child>
      <text>子组件多根节点</text>
      <multi-child ref="multi-child" id="multi-child"></multi-child>
      <text>子组件多根节点(仅测试，用于验证查询是否超出范围)</text>
      <multi-child id="multi-child-2"></multi-child>
      <view>
        <text>测试.fields</text>
        <text>{{fieldsResultContainNode}}</text>
      </view>
      <view>
        <text>测试.node</text>
        <text>{{nodeResultContainNode}}</text>
      </view>
      <canvas id="canvas1"></canvas>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>



<style>
  .page {
    padding: 15px;
  }

  .btn {
    margin-top: 15px;
  }

  .rect-1-2 {
    flex-direction: row;
    margin-top: 15px;
  }

  .rect {
    width: 150px;
    height: 100px;
  }

  .rect1 {
    background-color: dodgerblue;
  }

  .rect2 {
    margin-left: auto;
    background-color: seagreen;
  }

  .rect-info-1-2 {
    flex-direction: row;
    margin-top: 15px;
  }

  .rect-info {
    flex: 1;
    flex-direction: column;
  }

  .node-info-item {
    flex-direction: row;
  }

  .node-info-item-k {
    width: 72px;
    line-height: 2;
  }

  .node-info-item-v {
    font-weight: bold;
    line-height: 2;
  }
</style>

exec 示例说明：

exec() 返回所有动作的集合，每一项的数据类型取决于查询动作，结果排序按照调用动作顺序

示例：

uni.createSelectorQuery().select('.rect1').boundingClientRect().exec()
// 共返回 1 条结果，第一项数据类型为 NodeInfo
result = [ {} ]

uni.createSelectorQuery().selectAll('.rect1').boundingClientRect().exec()
// 共返回 1 条结果，第一项数据类型为 NodeInfo[]
result = [ [{},{}] ]

uni.createSelectorQuery().select('.rect1').selectAll('.rect2').boundingClientRect().exec()
// 共返回 2 条结果，第一项数据类型为 NodeInfo，第二项数据类型类型为 NodeInfo[]
result = [ {}, [{},{}] ]

通过id查询组件内多节点

和单根节点组件有所不同，有着多个根节点的组件需要透传 attribute

页面

<template>
  <view>
    <custom-component1 id="custom-component1"></custom-component1>

    <button @click="query">query</button>
  </view>
</template>
<script>
  export default {
    data() {
      return {
      }
    },
    methods: {
      query() {
        uni.createSelectorQuery().in(this).select('#scustom-component1').boundingClientRect().exec((ret) => {
          console.log(ret)
        })
      }
    }
  }
</script>

组件 custom-component1

<template>
  <text>1</text>
  <text v-bind="$attrs">2</text>
  <text>3</text>
</template>

注意事项：

1. App 平台 <template> 下如果存在多个节点，会导致非第一个节点查询不到的问题
2. Web 平台 <template> 下如果存在多个节点，如果是在组件内部查询，可能会导致查询到其他组件或页面的元素

通用类型

GeneralCallbackResult

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS - 4.41 - - -	错误信息