小程序 API 能力汇总——TYML IntersectionObserver API

ty.createIntersectionObserver

创建并返回一个 IntersectionObserver 对象实例。在自定义组件或包含自定义组件的页面中，应使用 this.createIntersectionObserver([options]) 来代替。

使用方式

ty.createIntersectionObserver(instance, [options]);

this.createIntersectionObserver([options]);

instance

页面实例或自定义组件实例。

options

选项

属性	类型	默认值	必填	说明	最低版本
thresholds	Array<number>	[0]	否	一个数值数组，包含所有阈值。
initialRatio	number	0	否	初始的相交比例，如果调用时检测到的相交比例与这个值不相等且达到阈值，则会触发一次监听器的回调函数。
observeAll	boolean	false	否	是否同时观测多个目标节点（而非一个），如果设为 true ，observe 的 targetSelector 将选中多个节点（注意：同时选中过多节点将影响渲染性能）

返回值

IntersectionObserver

示例代码

Page({
  onLoad() {
    this._observer = ty.createIntersectionObserver(this);
    this._observer.relativeTo('.scroll-view').observe('.ball', (res) => {
      this.setData({
        appear: res.intersectionRatio > 0,
      });
    });
  },
 
  onUnload() {
    if (this._observer) this._observer.disconnect();
  },
});

IntersectionObserver

IntersectionObserver 对象，用于推断某些节点是否可以被用户看见、有多大比例可以被用户看见。

方法

IntersectionObserver.observe

指定目标节点并开始监听相交状态变化情况

IntersectionObserver.disconnect

停止监听。回调函数将不再触发

IntersectionObserver IntersectionObserver.relativeTo

使用选择器指定一个节点，作为参照区域之一。

IntersectionObserver IntersectionObserver.relativeToViewport

指定页面显示区域作为参照区域之一

observe

IntersectionObserver.observe(string targetSelector, function callback)

指定目标节点并开始监听相交状态变化情况

参数

string targetSelector

选择器

function callback

监听相交状态变化的回调函数

参数

Object res

属性	类型	说明
id	string	节点 ID
dataset	Record.<string, any>	节点自定义数据属性
intersectionRatio	number	相交比例
intersectionRect	Object	相交区域的边界
boundingClientRect	Object	目标边界
relativeRect	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	下边界

disconnect

IntersectionObserver.disconnect()

停止监听。回调函数将不再触发

relativeTo

IntersectionObserver.relativeTo(string selector, Object margins)

使用选择器指定一个节点，作为参照区域之一。

参数

string selector

选择器

Object margins

用来扩展（或收缩）参照节点布局区域的边界

属性	类型	默认值	必填	说明
left	number		否	节点布局区域的左边界
right	number		否	节点布局区域的右边界
top	number		否	节点布局区域的上边界
bottom	number		否	节点布局区域的下边界

返回值

IntersectionObserver

relativeToViewport

IntersectionObserver.relativeToViewport(Object margins)

指定页面显示区域作为参照区域之一

Object margins

用来扩展（或收缩）参照节点布局区域的边界

属性	类型	默认值	必填	说明
left	number		否	节点布局区域的左边界
right	number		否	节点布局区域的右边界
top	number		否	节点布局区域的上边界
bottom	number		否	节点布局区域的下边界

返回值 IntersectionObserver

示例代码

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

👉 立即开发。