MutationObserver 怎样只监听指定属性的变化

结论先说：在 observe() 的配置里加入 attributeFilter，就能把属性监听从“所有属性变化”收窄到指定名称；再配合 attributeOldValue: true 读取修改前的值。如果目标节点下面还有动态生成的元素，再开启 subtree: true。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe

最小判断标准是：监听属性变化必须打开 attributes，过滤名单放进 attributeFilter，旧值放进 attributeOldValue；组件销毁时调用 disconnect() 收口。

先把监听范围收窄到指定属性

例如一个用户列表只需要关注状态和展开状态。直接监听属性会把无关的 class、title 等变化也送进回调，判断成本会随着页面复杂度上升。attributeFilter 接受属性名数组，名单之外的属性变化不会产生属性通知。

const userList = document.querySelector("#user-list");

const observer = new MutationObserver((mutationList) => {
  for (const mutation of mutationList) {
    // 只处理属性记录；过滤名单已经在 observe 配置中收窄。
    if (mutation.type !== "attributes") {
      continue;
    }

    // attributeName 是发生变化的属性名，可用于分派不同业务处理。
    if (mutation.attributeName === "data-status") {
      console.log("状态变化", mutation.target.dataset.status);
    } else if (mutation.attributeName === "aria-expanded") {
      console.log("展开状态变化", mutation.target.getAttribute("aria-expanded"));
    }
  }
});

observer.observe(userList, {
  // 明确声明要监听属性变化，避免配置语义不清。
  attributes: true,
  // 只关注这两个属性，其他属性不会进入属性通知。
  attributeFilter: ["data-status", "aria-expanded"]
});

这里的关键不是在回调里写更多 if，而是先把无关变化挡在观察配置之外。attributeFilter 出现时，属性监听语义会被启用，但显式写出 attributes: true 更容易阅读，也能避免后来有人把它改成 false 后触发配置错误。

需要前后对比时打开 attributeOldValue

回调收到的是一批 MutationRecord，属性名在 attributeName，修改前的值在 oldValue。当前值仍应从 mutation.target 读取，因为同一批通知中可能已经发生了多次修改。

const observer = new MutationObserver((mutationList) => {
  for (const mutation of mutationList) {
    if (mutation.type !== "attributes") {
      continue;
    }

    // oldValue 只有在 attributeOldValue 开启后才会提供旧值。
    const before = mutation.oldValue;
    const after = mutation.target.getAttribute(mutation.attributeName);
    console.log({
      // 保留属性名，便于统一记录不同元素的变化。
      name: mutation.attributeName,
      before,
      after
    });
  }
});

observer.observe(document.querySelector("#panel"), {
  // 属性旧值依赖属性监听，不能单独关闭 attributes。
  attributes: true,
  attributeFilter: ["data-status", "aria-expanded"],
  attributeOldValue: true
});

oldValue 可能是 null，这通常表示属性原本不存在；当前值也可能再次变成 null，表示属性已经被移除。不要把空字符串、属性不存在和字符串 "null" 混成同一种业务状态。

子树监听和生命周期怎么收口

如果用户列表中的行会动态增加，观察根节点时加上 subtree: true，属性规则就会覆盖它的后代节点。这个选项扩大的是观察范围，不是属性类型；仍然要保留 attributes 与 attributeFilter。

const root = document.querySelector("#user-list");

const observer = new MutationObserver((mutationList) => {
  for (const mutation of mutationList) {
    if (mutation.type === "attributes") {
      // target 可能是根节点的任意后代，按需更新对应行。
      console.log(mutation.target, mutation.attributeName, mutation.oldValue);
    }
  }
});

observer.observe(root, {
  // subtree 让动态生成的列表项也沿用同一组属性规则。
  subtree: true,
  attributes: true,
  attributeFilter: ["data-status", "aria-expanded"],
  attributeOldValue: true
});

function dispose() {
  // 页面或组件销毁时停止后续通知，避免保留不再需要的回调关系。
  observer.disconnect();
}

如果只想观察根节点本身，不要打开 subtree。另外，disconnect() 只停止这个观察器后续收到的通知；已经进入回调的业务副作用仍要由业务代码自己管理。

配置错误和批量记录怎么排查

observe() 至少需要把 childList、attributes 或 characterData 之一设为 true，否则会抛出 TypeError。如果写了 attributeFilter 或 attributeOldValue，却显式把 attributes 设为 false，同样属于冲突配置。

实战中建议按下面的顺序定位：先确认目标节点不是 null，再确认属性名与 DOM 中实际使用的名称一致，最后检查回调是否遍历了整批 mutationList。不要假设“一次属性修改只对应一次回调”，观察器会把记录以批次交给回调。

function watchAttributes(target, names, onChange) {
  if (!(target instanceof Element)) {
    throw new TypeError("target 必须是 Element");
  }
  if (!Array.isArray(names) || names.length === 0) {
    throw new TypeError("至少提供一个属性名");
  }

  const observer = new MutationObserver((records) => {
    // 一次回调可能包含多条记录，不能只读取 records[0]。
    records.forEach((record) => onChange({
      target: record.target,
      name: record.attributeName,
      before: record.oldValue,
      after: record.target.getAttribute(record.attributeName)
    }));
  });

  observer.observe(target, {
    attributes: true,
    attributeFilter: names,
    attributeOldValue: true
  });

  // 返回释放函数，让调用方把观察器纳入组件生命周期。
  return () => observer.disconnect();
}

常见问题

attributeFilter 能监听属性值中的某一部分吗？

不能。它匹配的是属性名，例如 data-status，不会按属性值、正则或 CSS 选择器过滤。值的判断要在回调中读取当前值后完成。

为什么写了 attributeOldValue 却没有旧值？

先确认监听的是 attributes，并且没有把它设为 false。同时注意，新增属性的旧值通常是 null，这不是配置失败。