展示全部

# uni.createSelectorQuery()

返回一个 SelectorQuery 对象实例。可以在这个实例上使用 select 等方法选择节点，并使用 boundingClientRect 等方法选择需要查询的信息。

元服务
x

HarmonyOS Next 兼容性

HarmonyOS Next
HBuilderX 4.23

Tips:

使用 uni.createSelectorQuery() 需要在生命周期 mounted 后进行调用。
默认需要使用到 selectorQuery.in 方法。

# SelectorQuery

查询节点信息的对象

# selectorQuery.in(component)

将选择器的选取范围更改为自定义组件 component 内，返回一个 SelectorQuery 对象实例。（初始时，选择器仅选取页面范围的节点，不会选取任何自定义组件中的节点）。

代码示例

选项式 API

组合式 API

const query = uni.createSelectorQuery().in(this);
query
  .select("#id")
  .boundingClientRect((data) => {
    console.log("得到布局位置信息" + JSON.stringify(data));
    console.log("节点离页面顶部的距离为" + data.top);
  })
  .exec();

注意

支付宝小程序不支持 in(component)，使用无效果

# selectorQuery.select(selector)

在当前页面下选择第一个匹配选择器 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 (H5 暂不支持)
多选择器的并集：#a-node, .some-other-nodes

# selectorQuery.selectAll(selector)

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

# selectorQuery.selectViewport()

选择显示区域，可用于获取显示区域的尺寸、滚动位置等信息，返回一个 NodesRef 对象实例。

# selectorQuery.exec(callback)

执行所有的请求。请求结果按请求次序构成数组，在 callback 的第一个参数中返回。

# NodesRef

用于获取节点信息的对象

# nodesRef.fields(object,callback)

获取节点的相关信息。第一个参数是节点相关信息配置（必选）；第二参数是方法的回调函数，参数是指定的相关节点信息。

object 参数说明

字段名	类型	默认值	必填	说明	平台差异说明
id	Boolean	false	否	是否返回节点 `id`
dataset	Boolean	false	否	是否返回节点 `dataset`	App、微信小程序、H5
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 和事件绑定的属性值不可获取）	仅 App 和微信小程序支持
computedStyle	Array＜string＞	[]	否	指定样式名列表，返回节点对应样式名的当前值	仅 App 和微信小程序支持
context	Boolean	false	否	是否返回节点对应的 Context 对象	仅 App 和微信小程序支持

# nodesRef.boundingClientRect(callback)

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

callback 返回参数

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

# nodesRef.scrollOffset(callback)

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

callback 返回参数

属性	类型	说明
id	String	节点的 ID
dataset	Object	节点的 dataset
scrollLeft	Number	节点的水平滚动位置
scrollTop	Number	节点的竖直滚动位置

# nodesRef.context(callback)

添加节点的 Context 对象查询请求。支持 VideoContext、CanvasContext、和 MapContext 等的获取。

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
√	HBuilderX 2.4.7+	√	x	x	x	√	√	√

callback 返回参数

属性	类型	说明
context	Object	节点对应的 Context 对象

# nodesRef.node(callback)

获取 Node 节点实例。目前支持 Canvas 的获取。

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
x	x	√	x	x	x	x	√	√

callback 返回参数

属性	类型	说明
node	Object	节点对应的 Node 实例

注意

目前仅能用于canvas
canvas需设置type="webgl"才能正常使用

# 代码示例

uni
  .createSelectorQuery()
  .selectViewport()
  .scrollOffset((res) => {
    console.log("竖直滚动位置" + res.scrollTop);
  })
  .exec();

let view = uni.createSelectorQuery().in(this).select(".test");

view
  .fields(
    {
      size: true,
      scrollOffset: true,
    },
    (data) => {
      console.log("得到节点信息" + JSON.stringify(data));
      console.log("节点的宽为" + data.width);
    }
  )
  .exec();

view
  .boundingClientRect((data) => {
    console.log("得到布局位置信息" + JSON.stringify(data));
    console.log("节点离页面顶部的距离为" + data.top);
  })
  .exec();

注意

nvue 暂不支持 uni.createSelectorQuery，暂时使用下面的方案

<template>
  <view class="wrapper">
    <view ref="box" class="box">
      <text class="info">Width: {{size.width}}</text>
      <text class="info">Height: {{size.height}}</text>
      <text class="info">Top: {{size.top}}</text>
      <text class="info">Bottom: {{size.bottom}}</text>
      <text class="info">Left: {{size.left}}</text>
      <text class="info">Right: {{size.right}}</text>
    </view>
  </view>
</template>

<script>
  // 注意平台差异
  // #ifdef APP-NVUE
  const dom = weex.requireModule("dom");
  // #endif

  export default {
    data() {
      return {
        size: {
          width: 0,
          height: 0,
          top: 0,
          bottom: 0,
          left: 0,
          right: 0,
        },
      };
    },
    onReady() {
      setTimeout(() => {
        const result = dom.getComponentRect(this.$refs.box, (option) => {
          console.log("getComponentRect:", option);
          this.size = option.size;
        });
        console.log("return value:", result);
        console.log("viewport:", dom.getComponentRect("viewport"));
      }, 100);
    },
  };
</script>

# 返回值 HarmonyOS Next 兼容性

类型
SelectorQuery

# SelectorQuery 的方法

# in(component: any | null): SelectorQuery

将选择器的选取范围更改为自定义组件component内 HarmonyOS Next 兼容性

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称	HarmonyOS Next 兼容性
component	-

# 返回值 HarmonyOS Next 兼容性

类型
SelectorQuery

# select(selector: string): NodesRef

在当前页面下选择第一个匹配选择器selector的节点 HarmonyOS Next 兼容性

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称	HarmonyOS Next 兼容性
selector	-

# 返回值 HarmonyOS Next 兼容性

类型
NodesRef

# NodesRef 的方法

# boundingClientRect( callback: SelectorQueryNodeInfoCallback | null, ): SelectorQuery

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

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称	HarmonyOS Next 兼容性
callback	-

# 返回值 HarmonyOS Next 兼容性

类型
SelectorQuery

# scrollOffset(callback: SelectorQueryNodeInfoCallback): SelectorQuery

添加节点的滚动位置查询请求，以像素为单位 HarmonyOS Next 兼容性

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称	HarmonyOS Next 兼容性
callback	-

# 返回值 HarmonyOS Next 兼容性

类型
SelectorQuery

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

获取节点的相关信息，需要获取的字段在fields中指定 HarmonyOS Next 兼容性

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称

HarmonyOS Next 兼容性

fields

名称	HarmonyOS Next 兼容性
id	-
dataset	-
rect	-
size	-
scrollOffset	-
properties	-
computedStyle	-
context	-
node	-

callback

# 返回值 HarmonyOS Next 兼容性

类型
SelectorQuery

# context(callback: SelectorQueryNodeInfoCallback): SelectorQuery

添加节点的 Context 对象查询请求 HarmonyOS Next 兼容性

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称	HarmonyOS Next 兼容性
callback	-

# 返回值 HarmonyOS Next 兼容性

类型
SelectorQuery

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

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

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称	HarmonyOS Next 兼容性
callback	-

# 返回值 HarmonyOS Next 兼容性

类型
SelectorQuery

# selectAll(selector: string): NodesRef

在当前页面下选择匹配选择器selector的所有节点 HarmonyOS Next 兼容性

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称	HarmonyOS Next 兼容性
selector	-

# 返回值 HarmonyOS Next 兼容性

类型
NodesRef

# selectViewport(): NodesRef

选择显示区域 HarmonyOS Next 兼容性

HarmonyOS Next
-

# 返回值 HarmonyOS Next 兼容性

类型
NodesRef

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

执行所有的请求 HarmonyOS Next 兼容性

HarmonyOS Next
-

# 参数 HarmonyOS Next 兼容性

名称	HarmonyOS Next 兼容性
callback	-

# 返回值 HarmonyOS Next 兼容性

类型	必备
NodesRef	否

运营产品

uni-ad uni统计 uni发行 uni安全专题

开发者服务

问答社区开发者后台

技术文档

uni-app文档 uniCloud文档原生开发者支持文档 HBuilder文档

生态服务

插件市场 OAuth用户开放平台

关于我们： DCloud官网案例需求墙许可协议加入我们赞助我们

联系我们：商务合作：bd@dcloud.io 广告合作：uniad@dcloud.io

DCloud.io 数字天堂（北京）网络技术有限公司是

HTML5中国产业联盟发起单位

京公网安备：11010802035340号

国家信息安全等级保护三级，证书编号：11010813802-20001

# uni.createSelectorQuery()

# SelectorQuery

# selectorQuery.in(component)

# selectorQuery.select(selector)

# selectorQuery.selectAll(selector)

# selectorQuery.selectViewport()

# selectorQuery.exec(callback)

# NodesRef

# nodesRef.fields(object,callback)

# nodesRef.boundingClientRect(callback)

# nodesRef.scrollOffset(callback)

# nodesRef.context(callback)

# nodesRef.node(callback)

# 代码示例

# 返回值 HarmonyOS Next 兼容性

# SelectorQuery 的方法

# in(component: any | null): SelectorQuery

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

# select(selector: string): NodesRef

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

# NodesRef 的方法

# boundingClientRect( callback: SelectorQueryNodeInfoCallback | null, ): SelectorQuery

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

# scrollOffset(callback: SelectorQueryNodeInfoCallback): SelectorQuery

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

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

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

# context(callback: SelectorQueryNodeInfoCallback): SelectorQuery

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

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

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

# selectAll(selector: string): NodesRef

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

# selectViewport(): NodesRef

# 返回值 HarmonyOS Next 兼容性

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

# 参数 HarmonyOS Next 兼容性

# 返回值 HarmonyOS Next 兼容性

本页导读