# SelectorQuery

## has.createSelectorQuery

has.createSelectorQuery(): SelectorQuery

创建SelectorQuery对象实例。

在自定义组件或包含自定义组件的页面中，应使用this.createSelectorQuery()来代替。

**起始版本：** 1.0.0

**返回值：**

返回[SelectorQuery](#selectorquery)对象。

**示例：**

```js
const query = has.createSelectorQuery();
query.select('#id').boundingClientRect();
query.exec(function(res) {
  console.info('res = ', res);
});
```

## SelectorQuery

### SelectorQuery.exec

SelectorQuery.exec(function callback): NodesRef

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

**起始版本：** 1.0.0

**参数：**

|参数|类型|必填|描述|
|:-------|:-------|:-|:----|
|callback|function|否|回调函数。|

**返回值：**

返回[NodesRef](#nodesref)对象。

**示例：**

```js
const query = has.createSelectorQuery();
const selecttarget = query.select('#movabletarget1').boundingClientRect(function(rect) {
  console.info('rect = ', rect);
}).exec();
```

### SelectorQuery.in

SelectorQuery.in(Component component): SelectorQuery

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

初始时，选择器仅选取页面范围的节点，不会选取任何自定义组件中的节点。

**起始版本：** 1.0.0

**参数：**

|参数|类型|必填|描述|
|:--------|:--------|:-|:-------|
|component|Component|是|自定义组件实例。|

**返回值：**

返回[SelectorQuery](#selectorquery)对象。

**示例：**

```js
const query = has.createSelectorQuery().in(this);
```

### SelectorQuery.select

SelectorQuery.select(string selector): NodesRef

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

**起始版本：** 1.0.0

**参数：**

|参数|类型|必填|描述|
|:-------|:-----|:-|:---|
|selector|string|是|选择器。|

**返回值：**

返回[NodesRef](#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

**示例：**

```js
const query = has.createSelectorQuery();
const nodesRef = query.select('#movabletarget1');
```

### SelectorQuery.selectAll

SelectorQuery.selectAll(string selector): NodesRef

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

**起始版本：** 1.0.0

**参数：**

|参数|类型|必填|描述|
|:-------|:-----|:-|:---|
|selector|string|是|选择器。|

**返回值：**

返回[NodesRef](#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

**示例：**

```js
const query = has.createSelectorQuery();
const nodesRef = query.selectAll('#movabletarget1');
```

### SelectorQuery.selectViewport

SelectorQuery.selectViewport(): NodesRef

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

**起始版本：** 1.0.0

**返回值：**

返回[NodesRef](#nodesref)对象。

**示例：**

```js
const query = has.createSelectorQuery();
const nodesRef = query.selectViewport();
```

## NodesRef

### NodesRef.boundingClientRect

NodesRef.boundingClientRect(function callback): SelectorQuery

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

**起始版本：** 1.0.0

**参数：**

|参数|类型|必填|描述|
|:-------|:-------|:-|:-----------------------------------------------|
|callback|function|否|回调函数，在执行SelectorQuery.exec方法后，节点信息将在callback中返回。|

**callback返回值：**

|参数|类型|描述|
|:------|:-----|:----------|
|id|string|节点的ID。|
|dataset|object|节点的dataset。|
|left|number|节点的左边界坐标。|
|right|number|节点的右边界坐标。|
|top|number|节点的上边界坐标。|
|bottom|number|节点的下边界坐标。|
|width|number|节点的宽度。|
|height|number|节点的高度。|

**返回值：**

返回[SelectorQuery](#selectorquery)对象。

**示例：**

```js
has.createSelectorQuery().select('#id').boundingClientRect(function(rect) {
  console.info('rect = ', rect);
}).exec();
```

### NodesRef.context

NodesRef.context(function callback): SelectorQuery

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

**起始版本：** 1.0.17

**参数：**

|参数|类型|必填|描述|
|:-------|:-------|:-|:------------------------------------|
|callback|function|否|回调函数，在执行SelectorQuery.exec方法后，返回节点信息。|

**callback返回值：**

|参数|类型|描述|
|:------|:-----|:--------------|
|context|object|节点对应的Context对象。|

**返回值：**

返回[SelectorQuery](#selectorquery)对象。

**示例：**

```js
has.createSelectorQuery().select('#id').context(function(res) {
  console.info('context = ', res.context);
}).exec();
```

### NodesRef.fields

NodesRef.fields(Object fields, function callback): SelectorQuery

获取节点的相关信息。需要获取的字段在fields中指定。返回值是NodesRef对应的SelectorQuery。

**起始版本：** 1.0.17

**参数：**

|参数|类型|必填|描述|
|:-------|:-------|:-|:-----------------------------------------------|
|fields|object|是|选项。包含需要获取的字段。|
|callback|function|否|回调函数，在执行SelectorQuery.exec方法后，返回在fields中指定的节点信息。|

**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对象。|
|node|boolean|false|否|是否返回节点对应的Node实例。|

**返回值：**

返回[SelectorQuery](#selectorquery)对象。

**示例：**

```js
has.createSelectorQuery().select('#id').fields({
  id: true,
  rect: true,
  size: true
}, function(res) {
  console.info('res = ', res);
}).exec();
```

### NodesRef.node

NodesRef.node(function callback): SelectorQuery

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

**起始版本：** 1.0.17

**参数：**

|参数|类型|必填|描述|
|:-------|:-------|:-|:------------------------------------|
|callback|function|否|回调函数，在执行SelectorQuery.exec方法后，返回节点信息。|

**callback返回值：**

|参数|类型|描述|
|:---|:-----|:-----------|
|node|object|节点对应的Node实例。|

**返回值：**

返回[SelectorQuery](#selectorquery)对象。

**示例：**

```js
has.createSelectorQuery().select('#id').node(function(res) {
  console.info('node = ', res.node);
}).exec();
```

### NodesRef.scrollOffset

NodesRef.scrollOffset(function callback): SelectorQuery

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

**起始版本：** 1.0.17

**参数：**

|参数|类型|必填|描述|
|:-------|:-------|:-|:------------------------------------|
|callback|function|否|回调函数，在执行SelectorQuery.exec方法后，返回节点信息。|

**callback返回值：**

|参数|类型|描述|
|:-----------|:-----|:----------|
|id|string|节点的ID。|
|dataset|object|节点的dataset。|
|scrollLeft|number|节点的水平滚动位置。|
|scrollTop|number|节点的竖直滚动位置。|
|scrollWidth|number|节点的滚动宽度。|
|scrollHeight|number|节点的滚动高度。|

**返回值：**

返回[SelectorQuery](#selectorquery)对象。

**示例：**

```js
has.createSelectorQuery().selectViewport().scrollOffset(function(res) {
  console.info('res = ', res);
}).exec();
```