::: sourceCode
## uni.createSelectorQuery() @createselectorquery
> issues: https://issues.dcloud.net.cn/?mid=api.dom.createSelectorQuery
> 源码: https://github.com/dcloudio/uni-app/tree/uni-app-x-alpha/src/uni_modules/uni-createSelectorQuery
:::
返回一个SelectorQuery对象实例
createSelectorQuery是小程序的API,因小程序未开放DOM,且视图层和逻辑层分离,于是提供了一个异步的API,可以在逻辑层有限的获取一些DOM能力。
该API返回的类型为NodeRef。它和DOM的Element有区别。
大多数组件的属性和样式操作,是通过绑定vue的响应式变量data来实现的。一般不使用本API。
本API的主要用途是小程序下获取元素计算后的样式。如果您的应用不适配小程序,那么在Web和App上有更强大的[UniElement](../dom/README.md)。
小程序下有时用本API获取部分组件的上下文context,但这个写法不跨平台。跨平台的获取组件context,应该使用uni.createXXContext()。
### createSelectorQuery 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61
**selector 说明:**
``selector`` 类似于 CSS 的选择器,但仅支持下列语法。
- ID选择器:``#the-id``
- class选择器:``.a-class``
### 返回值
| 类型 |
| :- |
| [SelectorQuery](#selectorquery-values) |
#### SelectorQuery 的方法 @selectorquery-values
#### in(component: any): SelectorQuery @in
in
将选择器的选取范围更改为自定义组件component内
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| component | any | 否 |
##### 返回值
| 类型 |
| :- |
| SelectorQuery |
#### select(selector: string): NodesRef @select
select
在当前页面下选择第一个匹配选择器selector的节点
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| selector | string | 是 |
##### 返回值
| 类型 |
| :- |
| [NodesRef](#nodesref-values) |
###### NodesRef 的方法 @nodesref-values
###### boundingClientRect( callback: SelectorQueryNodeInfoCallback, ): SelectorQuery @boundingclientrect
boundingClientRect
添加节点的布局位置的查询请求,相对于显示区域,以像素为单位
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| callback | (result: any) => void | 否 |
###### 返回值
| 类型 |
| :- |
| SelectorQuery |
###### scrollOffset(callback: SelectorQueryNodeInfoCallback): SelectorQuery @scrolloffset
scrollOffset
添加节点的滚动位置查询请求,以像素为单位
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| callback | (result: any) => void | 是 |
###### 返回值
| 类型 |
| :- |
| SelectorQuery |
###### fields( fields: NodeField, callback: SelectorQueryNodeInfoCallback, ): SelectorQuery @fields
fields
获取节点的相关信息,需要获取的字段在fields中指定
###### fields 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 4.25; iOS: 4.25
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| fields | **NodeField** | 是 |
| callback | (result: any) => void | 否 |
#### fields 的属性描述
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
| :- | :- | :- | :-: | :- |
| 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: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: x; iOS: x | 是否返回节点对应的 Context 对象 |
| node | boolean | 否 | | 是否返回节点对应的 Node 实例 |
###### 返回值
| 类型 |
| :- |
| SelectorQuery |
###### context(callback: SelectorQueryNodeInfoCallback): SelectorQuery @context
context
添加节点的 Context 对象查询请求(uni-app x 暂仅支持获取 EditorContext)
###### context 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 5.04; iOS: 5.04; HarmonyOS: 5.04
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| callback | (result: any) => void | 是 |
###### 返回值
| 类型 |
| :- |
| SelectorQuery |
###### node(callback: (result: any) => void): SelectorQuery @node
node
获取 Node 节点实例。目前支持 Canvas 的获取。
获取节点的相关信息,需要获取的字段在fields中指定
###### node 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 4.25; iOS: 4.25
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| callback | (result: any) => void | 是 |
###### 返回值
| 类型 |
| :- |
| SelectorQuery |
#### selectAll(selector: string): NodesRef @selectall
selectAll
在当前页面下选择匹配选择器selector的所有节点
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| selector | string | 是 |
##### 返回值
| 类型 |
| :- |
| [NodesRef](#nodesref-values) |
#### selectViewport(): NodesRef @selectviewport
selectViewport
选择显示区域
##### 返回值
| 类型 |
| :- |
| [NodesRef](#nodesref-values) |
#### exec(callback: (result: Array\) => void): NodesRef \| null @exec
exec
执行所有的请求
##### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| callback | (result: Array<any>) => void | 是 |
##### 返回值
| 类型 | 必备 |
| :- | :- |
| [NodesRef](#nodesref-values) | 否 |
##### NodeInfo 属性值
|属性 |类型 |说明 |
|--- |--- |--- |
|id |String |节点的 ID |
|dataset|Object |节点的 dataset |
|left |Number |节点的左边界坐标 |
|right |Number |节点的右边界坐标 |
|top |Number |节点的上边界坐标 |
|bottom |Number |节点的下边界坐标 |
|width |Number |节点的宽度 |
|height |Number |节点的高度 |
组件内使用
```html
```
### 示例
示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/API/create-selector-query/create-selector-query.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/API/create-selector-query/create-selector-query.uvue)
::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/create-selector-query/create-selector-query
> appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/create-selector-query/create-selector-query
>示例
```vue
left:
{{nodeInfo.left}}
top:
{{nodeInfo.top}}
right:
{{nodeInfo.right}}
bottom:
{{nodeInfo.bottom}}
width:
{{nodeInfo.width}}
height:
{{nodeInfo.height}}
子组件多根节点
子组件多根节点(仅测试,用于验证查询是否超出范围)
测试.fields
{{data.fieldsResultContainNode}}
测试.node
{{data.nodeResultContainNode}}
Text 组件查询示例
这是一个测试文本元素
left:
{{data.textNodeInfo!.left}}
right:
{{data.textNodeInfo!.right}}
top:
{{data.textNodeInfo!.top}}
bottom:
{{data.textNodeInfo!.bottom}}
width:
{{data.textNodeInfo!.width}}
height:
{{data.textNodeInfo!.height}}
Image 组件查询示例
left:
{{data.imageNodeInfo!.left}}
right:
{{data.imageNodeInfo!.right}}
top:
{{data.imageNodeInfo!.top}}
bottom:
{{data.imageNodeInfo!.bottom}}
width:
{{data.imageNodeInfo!.width}}
height:
{{data.imageNodeInfo!.height}}
Scroll-view 组件查询示例
Scroll-view 第 {{i}} 行
left:
{{data.scrollViewNodeInfo!.left}}
right:
{{data.scrollViewNodeInfo!.right}}
top:
{{data.scrollViewNodeInfo!.top}}
bottom:
{{data.scrollViewNodeInfo!.bottom}}
width:
{{data.scrollViewNodeInfo!.width}}
height:
{{data.scrollViewNodeInfo!.height}}
```
:::
**exec 示例说明:**
`exec()` 返回所有动作的集合,每一项的数据类型取决于查询动作,结果排序按照调用动作顺序
示例:
```js
uni.createSelectorQuery().select('.rect1').boundingClientRect((res) => {
// 共返回 1 条结果,第一项数据类型为 NodeInfo
// res = [ {} ]
const nodeInfoArray = res as NodeInfo[]
const nodeInfoArrayItem = nodeInfoArray[0]
console.log('info', nodeInfoArrayItem.width, nodeInfoArrayItem.height)
}).exec()
```
```js
uni.createSelectorQuery().selectAll('.rect1').boundingClientRect((res) => {
// 共返回 1 条结果,第一项数据类型为 NodeInfo[]
// res = [ [{},{}] ]
const nodeInfoArray = res as NodeInfo[]
const nodeInfoArrayItem = nodeInfoArray[0]
nodeInfoArrayItem.foreach((item: NodeInfo) => {
console.log('item', item.width, item.height)
})
}).exec()
```
```js
uni.createSelectorQuery().select('.rect1').selectAll('.rect2').boundingClientRect((res) => {
// 共返回 2 条结果,第一项数据类型为 NodeInfo,第二项数据类型为 NodeInfo[]
// res = [ {}, [{},{}] ]
const nodeInfoArray = res as NodeInfo[]
const nodeInfoItem0 = nodeInfoArray[0]
console.log('nodeInfoItem0', nodeInfoItem0.width, nodeInfoItem0.height)
const nodeInfoItem1 = nodeInfoArray[1]
nodeInfoItem1.foreach((item: NodeInfo) => {
console.log('item', item.width, item.height)
})
}).exec()
```
通过id查询组件内多节点
和单根节点组件有所不同,有着多个根节点的组件需要透传 attribute
页面
```html
```
组件 custom-component1
```html
1
2
3
```
**注意事项:**
1. Web 平台 `` 下如果存在多个节点,如果是在组件内部查询,可能会导致查询到其他组件或页面的元素
2. 支付宝小程序中,`createSelectorQuery().in()` 只能将查询范围设置为自定义组件,不能用于页面;页面查询需要在页面渲染完成后调用,否则可能查询不到结果。
## 通用类型
### GeneralCallbackResult @generalcallbackresult-values
| 名称 | 类型 | 必备 | 描述 |
| :- | :- | :- | :- |
| errMsg | string | 是 | 错误信息 |