WXML

createSelectorQuery

TIP

The API usage is as follows: SelectorQuery wx.createSelectorQuery()

• Functional description: Returns a SelectorQuery object instance. In custom components or pages containing custom components, use this.createSelectorQuery() instead.

• Return value: SelectorQuery

• Sample code:

const query = wx.createSelectorQuery()
query.select('#the-id').boundingClientRect()
query.selectViewport().scrollOffset()
query.exec(function (res) {
  res[0].top // The upper boundary coordinate of the #the-id node.
  res[1].scrollTop // The vertical scroll position of the display area.
})

createIntersectionObserver

TIP

The API usage is as follows: IntersectionObserver wx.createIntersectionObserver(Object component, Object options)

• Functional description: Create and return an IntersectionObserver object instance. In custom components or pages containing custom components, this.createIntersectionObserver([options]) should be used instead.
• Parameters and descriptions:

  • Object component, Custom component instance.

  • Object options, legal values

    Properties	Type	Default value	Required	Description
    thresholds	Array.<number>	[0]	No	A numeric array containing all thresholds
    initialRatio	number	0	No	The initial intersection ratio. If the intersection ratio detected during the call is not equal to this value and reaches the threshold, the listener callback function will be triggered once
    observeAll	boolean	false	No	Whether to observe multiple target nodes at the same time (instead of one). If set to true, observe's targetSelector will select multiple nodes (note: selecting too many nodes at the same time will affect rendering performance)

• Return value: IntersectionObserver

IntersectionObserver

IntersectionObserver object, used to infer whether certain nodes can be seen by users and what proportion of them can be seen by users.

.relativeTo

TIP

The API usage is as follows: IntersectionObserver.relativeTo(string selector, Object margins)

• Functional description: Use the selector to specify a node as one of the reference areas.
• Parameters and descriptions:

  • string selector, Selectors.

  • Object margins, Used to expand (or shrink) the border of the reference node layout area.

    Properties	Type	Default value	Required	Description
    left	number	-	No	Left border of the node layout area
    right	number	-	No	Right border of the node layout area
    top	number	-	No	Upper border of the node layout area
    bottom	number	-	No	Lower border of the node layout area

.relativeToViewport

TIP

The API usage is as follows: IntersectionObserver.relativeToViewport(Object margins)

• Functional description: Specifies the page display area as one of the reference areas.

• Parameters and descriptions: Object margins, Used to expand (or shrink) the border of the reference node layout area.

  Properties	Type	Default value	Required	Description
  left	number	-	No	Left border of the node layout area
  right	number	-	No	Right border of the node layout area
  top	number	-	No	Upper border of the node layout area
  bottom	number	-	No	Lower border of the node layout area

• Sample code:

  In the following sample code, if the target node (specified by the selector .target-class) enters 100px below the display area, the callback function will be triggered.

Page({
  onLoad() {
    wx.createIntersectionObserver().rela
  onLoad: function(){
    wx.createIntersectionObserver().relativeToViewport({bottom: 100}).observe('.target-class', (res) => {
      res.intersectionRatio // the ratio of the intersection region to the layout region of the target node
      res.intersectionRect // intersection region
      res.intersectionRect.left // coordinates of the left boundary of the intersection region
      res.intersectionRect.top // the upper boundary of the intersection region
      res.intersectionRect.width // width of the intersection region
      res.intersectionRect.height // height of the intersection region
    })
  }
})

.disconnect

TIP

The API usage is as follows: IntersectionObserver.disconnect()

• Functional description: Stop monitoring. The callback function will no longer be triggered.

.observe

TIP

The API usage is as follows: IntersectionObserver.observe(string targetSelector, function callback)

• Functional description: Specifies the target node and starts monitoring the intersection state changes.
• Parameters and descriptions:
  • string targetSelector, Selectors.
  • function callback, The callback function that monitors the intersection state change, the parameter Object res is as follows:

    Properties	Type	Description
    intersectionRatio	number	Intersection ratio
    intersectionRect	number	Boundary of the intersection area
    boundingClientRect	number	Target boundary
    relativeRect	number	Boundary of the reference area
    time	number	Timestamp when the intersection is detected

    • The structure of res.intersectionRect

      Structure properties	Type	Description
      left	number	Left boundary
      right	number	Right boundary
      top	number	Upper boundary
      bottom	number	Lower boundary
      width	number	Width
      height	number	Height

    • The structure of res.boundingClientRect

      Structure properties	Type	Description
      left	number	Left boundary
      right	number	Right boundary
      top	number	Upper boundary
      bottom	number	Lower boundary
      width	number	Width
      height	number	Height

    • The structure of res.relativeRect

      Structure properties	Type	Description
      left	number	Left boundary
      right	number	Right boundary
      top	number	Upper boundary
      bottom	number	Lower boundary

NodesRef

Object used to obtain WXML node information.

.fields

TIP

The API usage is as follows: NodesRef.fields(Object fields, function callback)

• Functional description: Get the relevant information of the node. The fields to be obtained are specified in fields. The return value is the selectorQuery corresponding to nodesRef
• Parameters and descriptions:
  • Object fields, legal parameters are as follows:

    Properties	Type	Default value	Required	Description
    id	boolean	false	No	Whether to return the node id
    dataset	boolean	false	No	Whether to return the node dataset
    rect	boolean	false	No	Whether to return the node layout position (left, right, top, bottom)
    size	boolean	false	No	Whether to return the node size (width, height)
    scrollOffset	boolean	false	No	Whether to return the scrollLeft scrollTop of the node, the node must be scroll-view or viewport
    properties	Array.<string>	[]	No	Specify the attribute name list and return the current attribute value of the corresponding attribute name of the node (only the general attribute values
    computedStyle	Array.<string>	[]	No	Specify the style name list and return the current value of the corresponding style name of the node
    context	boolean	false	No	Whether to return the Context object corresponding to the node

    • function callback, Callback function, the parameter Object res is the node related information.
    • Return value: The selectorQuery corresponding to nodesRef.

TIP

computedStyle has a higher priority than size. When width/height is specified in computedStyle and size: true is passed in at the same time, the width/height obtained by computedStyle will be returned first.

• Sample code:

  Page({
  getFields () {
    wx.createSelectorQuery().select('#the-id').fields({
      dataset: true,
      size: true,
      scrollOffset: true,
      properties: ['scrollX', 'scrollY'],
      computedStyle: ['margin', 'backgroundColor'],
      context: true, }, function (res) { {
    }, function (res) {
      res.dataset // the node's dataset
      res.width // width of the node
      res.height // the height of the node
      res.scrollLeft // The horizontal scroll position of the node.
      res.scrollTop // The vertical scroll position of the node.
      res.scrollX // The current value of the node's scroll-x property.
      res.scrollY // The current value of the node's scroll-y property.
      // This returns the name of the style to be returned.
      res.margin
      res.backgroundColor
      res.context // The node's corresponding Context object.
      res.ref // The Ref object for the node.
    res.ref // Ref object for the node }).exec()
  }
})

.boundingClientRect

TIP

The API usage is as follows: SelectorQuery NodesRef.boundingClientRect(function callback)

• Functional description: A query request for adding the layout position of the node. Relative to the display area, in pixels. Its function is similar to DOM's getBoundingClientRect.

• Parameters and descriptions: function callback。Callback function, after executing the SelectorQuery.exec method, the node information will be returned in the callback.

  • Object res

    Properties	Type	Description
    id	string	Node ID
    dataset	Object	Node dataset
    left	number	The left boundary coordinates of the node
    right	number	The right boundary coordinates of the node
    top	number	The upper boundary coordinates of the node
    bottom	number	The lower boundary coordinates of the node
    width	number	Node width
    height	number	Node height

• Return value: SelectorQuery

• Sample code:

Page({
  getRect() {
    wx.createSelectorQuery().select('#the-id').boundingClientRect(function (rect) {
      rect.id // Node's ID
      rect.dataset // Node's dataset
      rect.left // Node's left boundary coordinate
      rect.right // Node's right boundary coordinate
      rect.top // Node's upper boundary coordinate
      rect.bottom // Node's lower boundary coordinate
      rect.width // Node's width
      rect.height // Node's height
    }).exec()
  },
  getAllRects() {
    wx.createSelectorQuery().selectAll('.a-class').boundingClientRect(function (rects) {
      rects.forEach(function (rect) {
        rect.id // Node's ID
        rect.dataset // Node's dataset
        rect.left // Node's left boundary coordinate
        rect.right // Node's right boundary coordinate
        rect.top // Node's upper boundary coordinate
        rect.bottom // Node's lower boundary coordinate
        rect.width // Node's width
        rect.height // Node's height
      })
    }).exec()
  }
})

.scrollOffset

TIP

The API usage is as follows: SelectorQuery NodesRef.scrollOffset(function callback)

• Functional description: A query request for adding the scroll position of the node. In pixels. The node must be a scroll-view or viewport.

• Parameters and descriptions: function callback。Callback function, after executing the SelectorQuery.exec method, the node information will be returned in the callback.

  • Object res

    Properties	Type	Description
    id	string	Node ID
    dataset	string	Node dataset
    scrollLeft	number	Node horizontal scroll position
    scrollTop	number	Node vertical scroll position

• Return value: SelectorQuery

• Sample code:

Page({
  getScrollOffset() {
    wx.createSelectorQuery().selectViewport().scrollOffset(function (res) {
      res.id // Node's ID
      res.dataset // Node's dataset
      res.scrollLeft // Node's horizontal scroll position
      res.scrollTop // Node's vertical scroll position
    }).exec()
  }
})

.context

TIP

The API usage is as follows: SelectorQuery NodesRef.context(function callback)

• Functional description: A query request for adding the Context object of the node. Currently supported MapContext Getting.

• Parameters and descriptions: function callback。Callback function, after executing the SelectorQuery.exec method, the node information will be returned in the callback.

  • Object res

    Properties	Type	Description
    context	Object	The Context object corresponding to the node

• Return value: SelectorQuery

• Sample code:

Page({
  getContext() {
    wx.createSelectorQuery().select('.the-video-class').context(function (res) {
      console.log(res.context) // Context object corresponding to the node. For instance, if the selected node is a <map> component, then a MapContext object is returned here.
    }).exec()
  }
})

.node

TIP

The API usage is as follows: SelectorQuery NodesRef.node(function callback)

• Functional description: Get the Node node instance. Currently supported ScrollViewContext and Canvas Getting.

• Parameters and descriptions: function callback。Callback function, after executing the SelectorQuery.exec method, the node information will be returned in the callback.

  • Object res

    Properties	Type	Description
    node	Object	Node instance corresponding to the node

• Return value: SelectorQuery

• Sample code:

Page({
  getNode() {
    wx.createSelectorQuery().select('.canvas').node(function(res){
      console.log(res.node) // Canvas instance corresponding to the node.
    }).exec()
  }
})

SelectorQuery

Object for querying node information

.exec

TIP

The API usage is as follows: NodesRef SelectorQuery.exec(function callback)

• Functional description: Execute all requests. The request results are arrayed in the order of requests and returned in the first parameter of callback.
• Parameters and descriptions: function callback。Callback function
• Return value: NodesRef

.in

TIP

The API usage is as follows: SelectorQuery SelectorQuery.in(Component component)

• Functional description: Change the scope of the selector to the custom component component. (Initially, the selector only selects nodes in the page scope and will not select nodes in any custom component).

• Parameters and descriptions: Component component，Custom component instance.

• Return value: SelectorQuery

• Sample code:

Component({
  queryMultipleNodes() {
    const query = wx.createSelectorQuery().in(this)
    query.select('#the-id').boundingClientRect(function (res) {
      res.top // The upper boundary coordinate of the #the-id node within this component.
    }).exec()
  }
})

.select

TIP

The API usage is as follows: NodesRef SelectorQuery.select(string selector)

• Functional description: Select the first node that matches the selector selector in the current page. Returns a NodesRef object instance that can be used to obtain node information.
• Parameters and descriptions: string selector，Selectors.
• Return value: NodesRef
• selectorSyntax： selector is similar to the CSS selector, but only supports the following syntax:
  • ID selector: #the-id。
  • class selector (multiple can be specified consecutively): .a-class.another-class。
  • child element selector: .the-parent > .the-child。
  • descendant selector: .the-ancestor .the-descendant。
  • descendant selector across custom components: .the-ancestor >>> .the-descendant。
  • union of multiple selectors: #a-node, .some-other-nodes。

.selectAll

TIP

The API usage is as follows: NodesRef SelectorQuery.selectAll(string selector)

• Functional description: Selects all nodes that match the selector selector in the current page.
• Parameters and descriptions: string selector，Selectors.
• Return value: NodesRef
• selectorSyntax： selector is similar to the CSS selector, but only supports the following syntax:
  • ID selector: #the-id。
  • class selector (multiple can be specified consecutively): .a-class.another-class。
  • child element selector: .the-parent > .the-child。
  • descendant selector: .the-ancestor .the-descendant。
  • descendant selector across custom components: .the-ancestor >>> .the-descendant。
  • union of multiple selectors: #a-node, .some-other-nodes。

.selectViewport

TIP

The API usage is as follows: NodesRef SelectorQuery.selectViewport()

• Functional description: Select the display area. It can be used to obtain the size of the display area, scroll position and other information
• Return value: NodesRef

MediaQueryObserver

MediaQueryObserver object, used to monitor the changes in the page media query state, such as whether the length and width of the interface are within a specified range.

.disconnect

TIP

The API usage is as follows: MediaQueryObserver.disconnect()

• Functional description: Stop monitoring. The callback function will no longer be triggered.

.observe

TIP

The API usage is as follows: MediaQueryObserver.observe(Object descriptor, function callback)

• Functional description: Starts monitoring the page media query changes.
• Parameters and descriptions:

  • Object descriptor，media query descriptor.

    Properties	Type	Default value	Required	Description
    minWidth	number	-	Yes	Minimum page width (px)
    maxWidth	number	-	Yes	Maximum page width (px)
    width	number	-	Yes	Page width (px)
    minHeight	number	-	Yes	Minimum page height (px)
    maxHeight	number	-	Yes	Maximum page height (px)
    height	number	-	Yes	Page height (px)
    orientation	string	-	Yes	Screen orientation (landscape or portrait)

  • function callback，A callback function that listens to changes in the media query state. The parameters Object res are as follows:

    Properties	Type	Description
    matches	boolean	Whether the current state of the page meets the specified media query