Get Node Information on Interface

WXML Node Information

The API for querying node information is used to get information of a node such as its properties, style, and position in the interface.

This API is mostly used to query the current position and scroll position of a node in the interface.

Sample code:

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

In the above example, #the-id is a node selector, which is slightly different from the CSS selector. For more information, see SelectorQuery.select.

In custom components or pages that contain custom components, it is recommended to use this.createSelectorQuery, instead of wx.createSelectorQuery, to ensure nodes are selected within the correct area.

WXML Node Layout Intersection

The APIs for node layout intersection is used to listen to the layout intersection between two or more component nodes. This set of APIs are often used to determine whether certain nodes are visible to users and the percentage of the visible area.

The set of APIs involve the following concepts:

  • Reference node: The reference node for listening, whose layout area is taken as the reference area. If there are multiple reference nodes, the intersection of their layout areas is taken as the reference area. The page display area can also be used as a reference area.
  • Target node: The target to be listened to. Only one target node is allowed by default (you can listen to multiple nodes at the same time using the selectAll option).
  • Intersection area: The intersection area between the layout area of the target node and the reference area.
  • Intersection percentage: The percentage of the intersection area in the reference area.
  • Threshold: If the intersection percentage reaches the threshold, the callback function of the listener is triggered. Multiple thresholds can be set.

In the following sample code, a callback function is triggered each time the target node (specified using the selector .target-class) enters or exits the page display area.

Sample code:

Page({
  onLoad: function(){
    wx.createIntersectionObserver().relativeToViewport().observe('.target-class', (res) => {
      res.id // Target node ID
      res.dataset // Target node dataset
      res.intersectionRatio // The percentage of the intersection area in the layout area of the target node
      res.intersectionRect // Intersection area
      res.intersectionRect.left // Left boundary coordinates of the intersection area
      res.intersectionRect.top // Upper boundary coordinates of the intersection area
      res.intersectionRect.width // Width of the intersection area
      res.intersectionRect.height // Height of the intersection area
    })
  }
})

In the sample code below, a callback function is triggered when the interaction area or the separation space between the target node (specified using the selector .target-class) and the reference node (specified using the selector .relative-class) reaches 20% or 50% of the target node's layout area, respectively.

Sample code:

Page({
  onLoad: function(){
    wx.createIntersectionObserver(this, {
      thresholds: [0.2, 0.5]
    }).relativeTo('.relative-class').relativeToViewport().observe('.target-class', (res) => {
      res.intersectionRatio // The percentage of the intersection area in the layout area of the target node
      res.intersectionRect // Intersection area
      res.intersectionRect.left // Left boundary coordinates of the intersection area
      res.intersectionRect.top // Upper boundary coordinates of the intersection area
      res.intersectionRect.width // Width of the intersection area
      res.intersectionRect.height // Height of the intersection area
    })
  }
})

Note: The intersection area with the page display area does not accurately represent the area visible to users, because the area involved in the calculation is the "layout area", which may be cropped or hidden by, for example, a node whose ancestor node has the overflow style "hidden", or obscured by, for example, a node with fixed position during drawing.

In custom components or pages that contain custom components, it is recommended to use this.createIntersectionObserver, instead of wx.createIntersectionObserver, to ensure nodes are selected within the correct area.