浏览器 Observer API

August 13, 2022

观察器都是异步的，因此会性能更好

IntersectionObserver

https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API
https://developer.mozilla.org/docs/Web/API/IntersectionObserverEntry

交叉区域：被观察元素在根元素中的可见区域

const io = new IntersectionObserver(
    /* IntersectionObserverCallback */
    (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => {
        // entries : https://developer.mozilla.org/docs/Web/API/IntersectionObserverEntry
        // observer: 当前 IntersectionObserver 实例
        entries.forEach((entry) => {
            // 每一个 entry 都描述了一个被观察元素的 intersection 变化
            // 相当于 被观察元素.getBoundingClientRect()
            // entry.boundingClientRect
            // 等于 intersectionRect 与 boundingClientRect 的比例，[0, 1]
            // entry.intersectionRatio
            // 相当于 交叉区域的 DOMRectReadOnly
            // entry.intersectionRect
            // 是否交叉
            // entry.isIntersecting
            // 相当于 根元素的.getBoundingClientRect()
            // entry.rootBounds
            // 等于被观察元素
            // entry.target
            // intersection 变化发生的时间戳
            // entry.time
        });
    },
    /* IntersectionObserverInit */
    {
        root: document.querySelector("#scrollArea"),
        // 指定根 (root) 元素，用于检查目标的可见性。必须是目标元素的父级元素。
        // 如果未指定或者为 null，则默认为浏览器视窗。
        rootMargin: "0px",
        // 根 (root) 元素的外边距。类似于 CSS 中的 margin 属性，
        // 比如 "10px 20px 30px 40px" (top, right, bottom, left)。
        // 如果有指定 root 参数，则 rootMargin 也可以使用百分比来取值。
        // 该属性值是用作 root 元素和 target 发生交集时候的计算交集的区域范围，
        // 使用该属性可以控制 root 元素每一边的收缩或者扩张。默认值为 0。
        threshold: 1.0,
        // 可以是单一的 number 也可以是 number 数组，
        // target 元素和 root 元素相交程度达到该值的时候
        // IntersectionObserver 注册的回调函数将会被执行。
        // 如果你只是想要探测当 target 元素的在 root 元素中的可见性超过 50% 的时候，
        // 你可以指定该属性值为 0.5。
        // 如果你想要 target 元素在 root 元素的可见程度每多 25% 就执行一次回调，
        // 那么你可以指定一个数组 [0, 0.25, 0.5, 0.75, 1]。
        // 默认值是 0 (意味着只要有一个 target 像素出现在 root 元素中，回调函数将会被执行)。
        // 该值为 1.0 的含义是当 target 完全出现在 root 元素中时候 回调才会被执行。
    },
);

// 开始监听指定元素
io.observe(document.querySelector("#target"));

// 停止监听指定元素
io.unobserve(document.querySelector("#target"));

// 停止监听所有元素
io.disconnect();

// 即时获取 IntersectionObserverEntry 对象数组，同 IntersectionObserver 回调函数的第一个参数
const entries = intersectionObserver.takeRecords();

简单示例：

_______________
|-------------|
| #nav        |
|-------------|
|             |
|             |
|             |
|             |
|             |

const nav = document.getElementById("nav");

const io = new IntersectionObserver(
    (entries) => {
        entries.forEach((entry) => console.log(entry));
    },
    {
        threshold: [1],
    },
);
io.observe(nav);
// 在页面加载完成后立即触发一次
// 由于浏览器默认的body具有margin，此时nav的顶部与视窗顶部具有一小段距离
// 向下滚动页面，nav的顶部到达视窗顶时，触发一次
// 继续向下滚动
// 向上滚动页面，nav的顶部到达视窗顶时，触发一次
// ... ...

const io = new IntersectionObserver(
    (entries) => {
        entries.forEach((entry) => console.log(entry));
    },
    {
        threshold: [0],
    },
);
io.observe(nav);
// 在页面加载完成后立即触发一次
// 向下滚动直至nav的底部到达视窗顶时，触发一次
// ... ...

// 回调总是立即调用一次，无论 threshold 指定为任何值
document.addEventListener("DOMContentLoaded", () => {
    io.observe(nav);
});

MutationObserver

https://developer.mozilla.org/docs/Web/API/MutationObserver

const mo = new MutationObserver((mutations: MutationRecord[], observer: MutationObserver) => {
    // entries : https://developer.mozilla.org/docs/Web/API/MutationRecord
    // observer: 当前 MutationObserver 实例
});

interface MutationRecord {
    readonly addedNodes: NodeList;
    readonly attributeName: string | null;
    readonly attributeNamespace: string | null;
    readonly nextSibling: Node | null;
    readonly oldValue: string | null;
    readonly previousSibling: Node | null;
    readonly removedNodes: NodeList;
    readonly target: Node;
    readonly type: "attributes" | "characterData" | "childList";
}

mo.observe(targetNode, config as MutationObserverInit);

interface MutationObserverInit {
    /** 当为 true 时，将会监听以 target 为根节点的整个子树。包括子树中所有节点的属性，而不仅仅是针对 target。默认值为 false。 */
    subtree?: boolean;
    /** 当为 true 时，监听 target 节点中发生的节点的新增与删除（同时，如果 subtree 为 true，会针对整个子树生效）。默认值为 false。 */
    childList?: boolean;

    /** 当为 true 时观察所有监听的节点属性值的变化。默认值为 true，当声明了 attributeFilter 或 attributeOldValue，默认值则为 false。 */
    attributes?: boolean;
    /** 一个用于声明哪些属性名会被监听的数组。如果不声明该属性，所有属性的变化都将触发通知。 */
    attributeFilter?: string[];
    /** 当为 true 时，记录上一次被监听的节点的属性变化；可查阅监听属性值了解关于观察属性变化和属性值记录的详情。默认值为 false。 */
    attributeOldValue?: boolean;

    /** 当为 true 时，监听声明的 target 节点上所有字符的变化。默认值为 true，如果声明了 characterDataOldValue，默认值则为 false */
    characterData?: boolean;
    /** 当为 true 时，记录前一个被监听的节点中发生的文本变化。默认值为 false */
    characterDataOldValue?: boolean;
}

// 停止监听
// 注意没有 unobserve 方法
mo.disconnect();

// 立即获取 MutationRecord 数组
const entries = mo.takeRecords();

ResizeObserver

https://developer.mozilla.org/docs/Web/API/ResizeObserver

监听元素的内容区域（不包括 padding）或 SVG 元素的边界框改变。

const ro = new ResizeObserver((entries: ResizeObserverEntry[], observer: ResizeObserver) => {
    // entries:  https://developer.mozilla.org/docs/Web/API/ResizeObserverEntry
    for (let entry of entries) {
        // entry.target
        // entry.borderBoxSize
        // entry.contentBoxSize
        // entry.devicePixelContentBoxSize
        // entry.contentRect
        console.log(entry);
    }
});

ro.observe(document.querySelector("#example"), options as ResizeObserverOptions);

interface ResizeObserverOptions {
    box?: ResizeObserverBoxOptions;
}

ro.unobserve(document.querySelector("#example"));

ro.disconnect();