获取界面上的节点信息

Mr.Hope ... 2021-1-19 小程序 大约 3 分钟

提示

此部分在初步学习小程序的时候直接略过即可。

# WXML 节点信息

节点信息查询 API (opens new window) 可以用于获取节点属性、样式、在界面上的位置等信息。

最常见的用法是使用这个接口来查询某个节点的当前位置,以及界面的滚动位置。

代码示例
const query = wx.createSelectorQuery();
query.select("#the-id").boundingClientRect(function (res) {
  res.top; // #the-id 节点的上边界坐标(相对于显示区域)
});
query.selectViewport().scrollOffset(function (res) {
  res.scrollTop; // 显示区域的竖直滚动位置
});

query.exec();
1
2
3
4
5
6
7
8
9

上述示例中, #the-id 是一个节点选择器,与 CSS 的选择器相近但略有区别,请参见 SelectorQuery.select (opens new window) 的相关说明。

提示

在自定义组件或包含自定义组件的页面中,推荐使用 this.createSelectorQuery 来代替 wx.createSelectorQuery ,这样可以确保在正确的范围内选择节点。

# WXML 节点布局相交状态

节点布局相交状态 API (opens new window) 可用于监听两个或多个组件节点在布局位置上的相交状态。这一组 API 常常可以用于推断某些节点是否可以被用户看见、有多大比例可以被用户看见。

这一组 API 涉及的主要概念如下。

  • 参照节点: 监听的参照节点,取它的布局区域作为参照区域。如果有多个参照节点,则会取它们布局区域的 交集 作为参照区域。页面显示区域也可作为参照区域之一。
  • 目标节点: 监听的目标,默认只能是一个节点(使用 selectAll 选项时,可以同时监听多个节点)。
  • 相交区域: 目标节点的布局区域与参照区域的相交区域。
  • 相交比例: 相交区域占参照区域的比例。
  • 阈值: 相交比例如果达到阈值,则会触发监听器的回调函数。阈值可以有多个。
代码示例

以下示例代码可以在目标节点(用选择器 .target-class 指定)每次进入或离开页面显示区域时,触发回调函数。

Page({
  onLoad() {
    wx.createIntersectionObserver()
      .relativeToViewport()
      .observe(".target-class", (res) => {
        res.id; // 目标节点 id
        res.dataset; // 目标节点 dataset
        res.intersectionRatio; // 相交区域占目标节点的布局区域的比例
        res.intersectionRect; // 相交区域
        res.intersectionRect.left; // 相交区域的左边界坐标
        res.intersectionRect.top; // 相交区域的上边界坐标
        res.intersectionRect.width; // 相交区域的宽度
        res.intersectionRect.height; // 相交区域的高度
      });
  },
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

以下示例代码可以在目标节点(用选择器 .target-class 指定)与参照节点(用选择器 .relative-class 指定)在页面显示区域内相交或相离,且相交或相离程度达到目标节点布局区域的 20%和 50%时,触发回调函数。

Page({
  onLoad() {
    wx.createIntersectionObserver(this, {
      thresholds: [0.2, 0.5],
    })
      .relativeTo(".relative-class")
      .relativeToViewport()
      .observe(".target-class", (res) => {
        res.intersectionRatio; // 相交区域占目标节点的布局区域的比例
        res.intersectionRect; // 相交区域
        res.intersectionRect.left; // 相交区域的左边界坐标
        res.intersectionRect.top; // 相交区域的上边界坐标
        res.intersectionRect.width; // 相交区域的宽度
        res.intersectionRect.height; // 相交区域的高度
      });
  },
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

注意

与页面显示区域的相交区域并不准确代表用户可见的区域,因为参与计算的区域是“布局区域”,布局区域可能会在绘制时被其他节点裁剪隐藏(如遇祖先节点中 overflow 样式为 hidden 的节点)或遮盖(如遇 fixed 定位的节点)。

提示

在自定义组件或包含自定义组件的页面中,推荐使用 this.createIntersectionObserver 来代替 wx.createIntersectionObserver ,这样可以确保在正确的范围内选择节点。