tencent cloud

文档反馈

最后更新时间:2024-07-12 19:11:45

    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 component, 自定义组件实例;
    Object options,合法值如下:
    属性
    类型
    默认值
    必填
    说明
    thresholds
    Array.<number>
    [0]
    一个数值数组,包含所有阈值。
    initialRatio
    number
    0
    初始的相交比例,如果调用时检测到的相交比例与这个值不相等且达到阈值,则会触发一次监听器的回调函数。
    observeAll
    boolean
    false
    是否同时观测多个目标节点(而非一个),如果设为 true ,observe 的 targetSelector 将选中多个节点(注意:同时选中过多节点将影响渲染性能)。
    返回值:IntersectionObserver

    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: function(){
    wx.createIntersectionObserver().relativeToViewport({bottom: 100}).observe('.target-class', (res) => {
    res.intersectionRatio // 相交区域占目标节点的布局区域的比例
    res.intersectionRect // 相交区域
    res.intersectionRect.left // 相交区域的左边界坐标
    res.intersectionRect.top // 相交区域的上边界坐标
    res.intersectionRect.width // 相交区域的宽度
    res.intersectionRect.height // 相交区域的高度
    })
    }
    })

    .disconnect

    该 方法 使用方式为 IntersectionObserver.disconnect()
    功能说明:停止监听,回调函数将不再触发。

    .observe

    该 方法 使用方式为 IntersectionObserver.observe(string targetSelector, function callback)
    功能说明:指定目标节点并开始监听相交状态变化情况。
    参数及说明:
    string targetSelector,选择器;
    function callback,监听相交状态变化的回调函数,参数Object res如下:
    属性
    类型
    说明
    intersectionRatio
    number
    相交比例
    object
    相交区域的边界
    object
    目标边界
    object
    参照区域的边界
    time
    number
    相交检测时的时间戳
    
    res.intersectionRect 的结构
    
    结构属性
    类型
    说明
    left
    number
    左边界
    right
    number
    右边界
    top
    number
    上边界
    bottom
    number
    下边界
    width
    number
    宽度
    height
    number
    高度
    
    res.boundingClientRect 的结构
    
    结构属性
    类型
    说明
    left
    number
    左边界
    right
    number
    右边界
    top
    number
    上边界
    bottom
    number
    下边界
    width
    number
    宽度
    height
    number
    高度
    
    res.relativeRect 的结构
    
    结构属性
    类型
    说明
    left
    number
    左边界
    right
    number
    右边界
    top
    number
    上边界
    bottom
    number
    下边界

    NodesRef

    用于获取 WXML 节点信息的对象。

    .fields

    该 方法 使用方式为 NodesRef.fields(Object fields, function callback)
    功能说明:获取节点的相关信息。需要获取的字段在fields中指定。返回值是 nodesRef 对应的 selectorQuery
    参数及说明:
    Object fields, 合法参数如下:
    属性
    类型
    默认值
    必填
    说明
    id
    boolean
    false
    是否返回节点 id
    dataset
    boolean
    false
    是否返回节点 dataset
    rect
    boolean
    false
    是否返回节点布局位置(leftrighttopbottom
    size
    boolean
    false
    是否返回节点尺寸(widthheight
    scrollOffset
    boolean
    false
    是否返回节点的 scrollLeft scrollTop,节点必须是 scroll-view 或者 viewport
    properties
    Array.<string>
    []
    指定属性名列表,返回节点对应属性名的当前属性值(只能获得组件文档中标注的常规属性值,id class style 和事件绑定的属性值不可获取)
    computedStyle
    Array.<string>
    []
    指定样式名列表,返回节点对应样式名的当前值
    context
    boolean
    false
    是否返回节点对应的 Context 对象
    function callback, 回调函数,参数Object res为节点相关信息。
    返回值:nodesRef 对应的 selectorQuery。
    注意:
    computedStyle 的优先级高于 size,当同时在 computedStyle 里指定了 width/height 和传入了 size: true,则优先返回 computedStyle 获取到的 width/height。
    示例代码:
    Page({
    getFields () {
    wx.createSelectorQuery().select('#the-id').fields({
    dataset: true,
    size: true,
    scrollOffset: true,
    properties: ['scrollX', 'scrollY'],
    computedStyle: ['margin', 'backgroundColor'],
    context: true,
    }, function (res) {
    res.dataset // 节点的dataset
    res.width // 节点的宽度
    res.height // 节点的高度
    res.scrollLeft // 节点的水平滚动位置
    res.scrollTop // 节点的竖直滚动位置
    res.scrollX // 节点 scroll-x 属性的当前值
    res.scrollY // 节点 scroll-y 属性的当前值
    // 此处返回指定要返回的样式名
    res.margin
    res.backgroundColor
    res.context // 节点对应的 Context 对象
    res.ref // 节点对应的 Ref 对象
    }).exec()
    }
    })

    .boundingClientRect

    该 方法 使用方式为 SelectorQuery NodesRef.boundingClientRect(function 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 // 节点的ID
    rect.dataset // 节点的dataset
    rect.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 // 节点的ID
    rect.dataset // 节点的dataset
    rect.left // 节点的左边界坐标
    rect.right // 节点的右边界坐标
    rect.top // 节点的上边界坐标
    rect.bottom // 节点的下边界坐标
    rect.width // 节点的宽度
    rect.height // 节点的高度
    })
    }).exec()
    }
    })

    .scrollOffset

    该 方法 使用方式为 SelectorQuery NodesRef.scrollOffset(function 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 // 节点的ID
    res.dataset // 节点的dataset
    res.scrollLeft // 节点的水平滚动位置
    res.scrollTop // 节点的竖直滚动位置
    }).exec()
    }
    })

    .context

    该 方法 使用方式为 SelectorQuery NodesRef.context(function callback)
    功能说明:添加节点的 Context 对象查询请求。目前支持 MapContext 的获取。
    参数及说明:function callback,回调函数,在执行 SelectorQuery.exec 方法后,返回节点信息。
    Object res。
    属性
    类型
    说明
    context
    Object
    节点对应的 Context 对象
    返回值:SelectorQuery
    示例代码:
    Page({
    getContext() {
    wx.createSelectorQuery().select('.the-map-class').context(function (res) {
    console.log(res.context) // 节点对应的 Context 对象。如:选中的节点是 <map> 组件,那么此处即返回 MapContext 对象
    }).exec()
    }
    })

    .node

    该 方法 使用方式为 SelectorQuery NodesRef.node(function 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
    -
    屏幕方向( landscapeportrait
    function callback,监听 media query 状态变化的回调函数。参数 Object res 如下:
    属性
    类型
    说明
    matches
    boolean
    页面的当前状态是否满足所指定的 media query
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持