createSelectorQuery
该 API 使用方法为 SelectorQuery wx.createSelectorQuery()
功能说明:返回一个 SelectorQuery 对象实例,在自定义组件或包含自定义组件的页面中,用
this.createSelectorQuery()
来代替。返回值:SelectorQuery。
示例代码:
const query = wx.createSelectorQuery()query.select('#the-id').boundingClientRect()query.selectViewport().scrollOffset()query.exec(function (res) {res[0].top // #the-id节点的上边界坐标res[1].scrollTop // 显示区域的竖直滚动位置})
createIntersectionObserver
该 API 使用方法为 IntersectionObserver wx.createIntersectionObserver(Object component, Object options)
功能说明:创建并返回一个 IntersectionObserver 对象实例。在自定义组件或包含自定义组件的页面中,应使用
this.createIntersectionObserver([options])
来代替。参数及说明:Object this
自定义组件实例:Object options。
选项
属性 | 类型 | 默认值 | 必填 | 说明 |
thresholds | Array.<number> | [0] | 否 | 一个数值数组,包含所有阈值。 |
initialRatio | number | 0 | 否 | 初始的相交比例,如果调用时检测到的相交比例与这个值不相等且达到阈值,则会触发一次监听器的回调函数。 |
observeAll | boolean | false | 否 | 是否同时观测多个目标节点(而非一个),如果设为 true ,observe 的 targetSelector 将选中多个节点(注意:同时选中过多节点将影响渲染性能)。 |
返回值:IntersectionObserver。
IntersectionObserver
.relativeTo
该 方法 使用方式为 IntersectionObserver.relativeTo(string selector, Object margins)
功能说明:使用选择器指定一个节点,作为参照区域之一。
参数及说明:string selector,用来扩展(或收缩)参照节点布局区域的边界。
选择器:Object margins。
属性 | 类型 | 默认值 | 必填 | 说明 |
left | number | - | 否 | 节点布局区域的左边界 |
right | number | - | 否 | 节点布局区域的右边界 |
top | number | - | 否 | 节点布局区域的上边界 |
bottom | number | - | 否 | 节点布局区域的下边界 |
.relativeToViewport
该 方法 使用方式为 IntersectionObserver.relativeToViewport(Object margins)
功能说明:指定页面显示区域作为参照区域之一。
参数及说明:Object margins ,用来扩展(或收缩)参照节点布局区域的边界。
属性 | 类型 | 默认值 | 必填 | 说明 |
left | number | - | 否 | 节点布局区域的左边界 |
right | number | - | 否 | 节点布局区域的右边界 |
top | number | - | 否 | 节点布局区域的上边界 |
bottom | number | - | 否 | 节点布局区域的下边界 |
示例代码
下面的示例代码中,如果目标节点(用选择器 .target-class 指定)进入显示区域以下100px时,就会触发回调函数。
Page({onLoad() {wx.createIntersectionObserver().rela
.disconnect
该 方法 使用方式为 IntersectionObserver.disconnect()
功能说明:停止监听,回调函数将不再触发。
.observe
该 方法 使用方式为 IntersectionObserver.observe(string targetSelector, function callback)
功能说明:指定目标节点并开始监听相交状态变化情况。
参数及说明:string targetSelector。
选择器:function callback。
监听相交状态变化的回调函数参数:Object res。
属性 | 类型 | 说明 |
intersectionRatio | number | 相交比例 |
intersectionRect | object | 相交区域的边界 |
boundingClientRect | object | 目标边界 |
relativeRect | object | 参照区域的边界 |
time | number | 相交检测时的时间戳 |
res.intersectionRect 的结构
属性 | 类型 | 说明 |
left | number | 左边界 |
right | number | 右边界 |
top | number | 上边界 |
bottom | number | 下边界 |
res.boundingClientRect 的结构
属性 | 类型 | 说明 |
left | number | 左边界 |
right | number | 右边界 |
top | number | 上边界 |
bottom | number | 下边界 |
res.relativeRect 的结构
属性 | 类型 | 说明 |
left | number | 左边界 |
right | number | 右边界 |
top | number | 上边界 |
bottom | number | 下边界 |
NodesRef
.fields
该 方法 使用方式为 NodesRef.fields(Object fields)
功能说明:获取节点的相关信息。需要获取的字段在fields中指定。
参数及说明:Object 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.\\ | - | 否 | 指定属性名列表,返回节点对应属性名的当前属性值(只能获得组件文档中标注的常规属性值,id class style 和事件绑定的属性值不可获取) |
computedStyle | Array.\\ | - | 否 | 指定样式名列表,返回节点对应样式名的当前值 |
context | boolean | false | 否 | 是否返回节点对应的 Context 对象 |
注意:
computedStyle 的优先级高于 size,当同时在 computedStyle 里指定了 width/height 和传入了 size: true,则优先返回 computedStyle 获取到的 width/height。
返回值:nodesRef 对应的 selectorQuery。
.boundingClientRect
该 方法 使用方式为 SelectorQuery NodesRef.boundingClientRect(NodesRef.boundingClientRectCallback callback)
功能说明:添加节点的布局位置的查询请求。相对于显示区域,以像素为单位。其功能类似于 DOM 的
getBoundingClientRect
。参数及说明:function callback。回调函数,在执行 SelectorQuery.exec 方法后,节点信息会在 callback 中返回。
Object res
属性 | 类型 | 说明 |
id | string | 节点的 ID |
dataset | Object | 节点的 dataset |
left | number | 节点的左边界坐标 |
right | number | 节点的右边界坐标 |
top | number | 节点的上边界坐标 |
bottom | number | 节点的下边界坐标 |
width | number | 节点的宽度 |
height | number | 节点的高度 |
返回值:SelectorQuery。
示例代码:
Page({getRect() {wx.createSelectorQuery().select('#the-id').boundingClientRect(function (rect) {rect.id // 节点的IDrect.dataset // 节点的datasetrect.left // 节点的左边界坐标rect.right // 节点的右边界坐标rect.top // 节点的上边界坐标rect.bottom // 节点的下边界坐标rect.width // 节点的宽度rect.height // 节点的高度}).exec()},getAllRects() {wx.createSelectorQuery().selectAll('.a-class').boundingClientRect(function (rects) {rects.forEach(function (rect) {rect.id // 节点的IDrect.dataset // 节点的datasetrect.left // 节点的左边界坐标rect.right // 节点的右边界坐标rect.top // 节点的上边界坐标rect.bottom // 节点的下边界坐标rect.width // 节点的宽度rect.height // 节点的高度})}).exec()}})
.scrollOffset
该 方法 使用方式为 SelectorQuery NodesRef.scrollOffset(NodesRef.scrollOffsetCallback callback)
功能说明:添加节点的滚动位置查询请求。以像素为单位。节点必须是
scroll-view
或者viewport
。参数及说明:function callback,回调函数,在执行 SelectorQuery.exec 方法后,节点信息会在 callback 中返回。
Object res
属性 | 类型 | 说明 |
id | string | 节点的 ID |
dataset | Object | 节点的 dataset |
scrollLeft | number | 节点的水平滚动位置 |
scrollTop | number | 节点的竖直滚动位置 |
返回值:SelectorQuery。
示例代码:
Page({getScrollOffset() {wx.createSelectorQuery().selectViewport().scrollOffset(function (res) {res.id // 节点的IDres.dataset // 节点的datasetres.scrollLeft // 节点的水平滚动位置res.scrollTop // 节点的竖直滚动位置}).exec()}})
.context
该 方法 使用方式为 SelectorQuery NodesRef.context(NodesRef.contextCallback callback)
功能说明:添加节点的 Context 对象查询请求。目前支持 MapContext 的获取。
参数及说明:function callback,回调函数,在执行 SelectorQuery.exec 方法后,返回节点信息。
Object res。
属性 | 类型 | 说明 |
context | Object | 节点对应的 Context 对象 |
返回值:SelectorQuery。
示例代码:
Page({getContext() {wx.createSelectorQuery().select('.the-video-class').context(function (res) {console.log(res.context) // 节点对应的 Context 对象。如:选中的节点是 <video> 组件,那么此处即返回 VideoContext 对象}).exec()}})
.node
该 方法 使用方式为 SelectorQuery NodesRef.node(NodesRef.nodeCallback callback)
功能说明:获取 Node 节点实例。目前支持 ScrollViewContext 界面-滚动的获取。 目前支持 Canvas 的获取。
参数及说明:function callback,回调函数,在执行 SelectorQuery.exec 方法后,返回节点信息。
Object res
属性 | 类型 | 说明 |
node | Object | 节点对应的 Node 实例 |
返回值:SelectorQuery。
示例代码:
Page({getNode() {wx.createSelectorQuery().select('.canvas').node(function(res){console.log(res.node) // 节点对应的 Canvas 实例。}).exec()}})
SelectorQuery
.exec
该 方法 使用方式为 NodesRef SelectorQuery.exec(function callback)
功能说明:执行所有的请求。请求结果按请求次序构成数组,在 callback 的第一个参数中返回。
参数及说明:function callback,回调函数。
返回值:NodesRef。
.in
该 方法 使用方式为 SelectorQuery SelectorQuery.in(Component component)
功能说明:将选择器的选取范围更改为自定义组件 component 内。(初始时,选择器仅选取页面范围的节点,不会选取任何自定义组件中的节点)。
参数及说明:Component component,自定义组件实例。
返回值:SelectorQuery。
示例代码:
Component({queryMultipleNodes() {const query = wx.createSelectorQuery().in(this)query.select('#the-id').boundingClientRect(function (res) {res.top // 这个组件内 #the-id 节点的上边界坐标}).exec()}})
.select
该 方法 使用方式为 NodesRef SelectorQuery.select(string selector)
功能说明:在当前页面下选择第一个匹配选择器 selector 的节点。返回一个 NodesRef 对象实例,可以用于获取节点信息。
参数及说明:string 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。
多选择器的并集:#a-node, .some-other-nodes。
.selectAll
该 方法 使用方式为 NodesRef SelectorQuery.selectAll(string selector)
功能说明:在当前页面下选择匹配选择器 selector 的所有节点。
参数及说明:string 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。
多选择器的并集:#a-node, .some-other-nodes。
.selectViewport
该 方法 使用方式为 NodesRef SelectorQuery.selectViewport()
功能说明:选择显示区域。可用于获取显示区域的尺寸、滚动位置等信息。
返回值:NodesRef
MediaQueryObserver
MediaQueryObserver 对象,用于监听页面 media query 状态的变化,如界面的长宽是不是在某个指定的范围内。
.disconnect
该 方法 使用方式为 MediaQueryObserver.disconnect()
功能说明:停止监听。回调函数将不再触发。
.observe
该 方法 使用方式为 MediaQueryObserver.observe(Object descriptor, function callback)
功能说明:开始监听页面 media query 变化情况。
参数及说明:
Object descriptor,media query 描述符。
属性 | 类型 | 默认值 | 必填 | 说明 |
minWidth | number | - | 是 | 页面最小宽度( px 为单位) |
maxWidth | number | - | 是 | 页面最大宽度( px 为单位) |
width | number | - | 是 | 页面宽度( px 为单位) |
minHeight | number | - | 是 | 页面最小高度( px 为单位) |
maxHeight | number | - | 是 | 页面最大高度( px 为单位) |
height | number | - | 是 | 页面高度( px 为单位) |
orientation | string | - | 是 | 屏幕方向( landscape 或 portrait ) |
function callback,监听 media query 状态变化的回调函数。
Object res
属性 | 类型 | 说明 |
matches | boolean | 页面的当前状态是否满足所指定的 media query |