如何在Web应用的script标签中添加Mutation Observer？React组件显隐监听排查

核心问题 #

HTML中通过script标签在id='header'的DOM节点创建的UI组件，会在包含该节点的div因参数变化重新渲染时丢失。尝试用Mutation Observer监听DOM变化以触发重建逻辑，但未按预期生效；简化示例中，期望NewApp组件显隐时触发Observer回调，也未实现。

尝试的代码（原业务场景） #

useEffect(() => {
  const onElementMutate = () => setElementReady(true)
  const observer = new MutationObserver(onElementMutate)
  const observerConfig = { childList: true, subtree: true }

  const target = document.getElementById(elementId)

  if (target) {
    observer.observe(target, observerConfig)
    setElementReady(true)
  }

  return () => {
    observer.disconnect()
  }
},[])

通过状态控制Portal渲染：

return elementReady ? ReactDOM.createPortal(<Component />, document.getElementById(elementId) as any) : null

简化示例代码 #

App.jsx #

import "./App.css";
import NewApp from "./NewApp";
import { useEffect, useState } from "react";

function App() {
  const [show, setShow] = useState(false);
  useEffect(() => {
    const element = document.getElementById("observer");
    const observer = new MutationObserver((data) => {
      console.log("Data = ", data);
    });
    if (element) {
      observer.observe(element, { childList: true });
    }
    return () => observer.disconnect();
  }, [show]);
  return (
    <div className="App">
      <NewApp show={show} setShow={setShow} />
      {!show && <button onClick={() => setShow(true)}>Show</button>}
    </div>
  );
}

export default App;

NewApp.jsx #

const NewApp = ({show,setShow}) => {
  return show ? (
    <div id='observer'>
    <div>Showing...</div>
    <button onClick={() => setShow(false)}>Dont Show</button>
    </div>
  ) : null
};
export default NewApp;

问题根源 #

1. Observer绑定时机错误：简化示例中，show状态变化触发useEffect时，React尚未完成NewApp组件的DOM挂载，document.getElementById("observer")返回null，导致Observer未绑定到目标元素。
2. 监听范围不匹配：Observer仅监听目标元素内部的childList变化，但组件显隐是目标元素自身被添加/移除，不在当前监听范围内；且元素被移除时，Observer随元素销毁无法触发回调。
3. 依赖项缺失：原业务代码的useEffect依赖数组为空，仅在组件挂载时执行一次，若目标元素是动态挂载或elementId变化，Observer无法重新绑定。

解决方案 #

1. 修复简化示例：监听父元素捕获组件显隐 #

要监听NewApp的显隐，需将Observer绑定到目标元素的父节点，监听父节点的childList变化，从而捕获目标元素的添加/移除：

import "./App.css";
import NewApp from "./NewApp";
import { useEffect, useState } from "react";

function App() {
  const [show, setShow] = useState(false);
  
  useEffect(() => {
    // 绑定到App组件的根父元素
    const parentElement = document.querySelector(".App");
    const observer = new MutationObserver((mutations) => {
      mutations.forEach(mutation => {
        // 检查目标元素的添加/移除
        const addedObserver = Array.from(mutation.addedNodes).find(node => node.id === 'observer');
        const removedObserver = Array.from(mutation.removedNodes).find(node => node.id === 'observer');
        
        if (addedObserver) {
          console.log("observer元素已挂载");
          // 执行你的UI重建逻辑
        }
        if (removedObserver) {
          console.log("observer元素已卸载");
        }
      });
    });
    
    if (parentElement) {
      observer.observe(parentElement, { childList: true });
    }
    
    return () => observer.disconnect();
  }, []); // 仅在App挂载时绑定一次

  return (
    <div className="App">
      <NewApp show={show} setShow={setShow} />
      {!show && <button onClick={() => setShow(true)}>Show</button>}
    </div>
  );
}

export default App;

2. 原业务场景优化方案 #

方案A：用React生命周期替代原生script

优先将原生script的UI逻辑封装为React组件，利用useEffect管理初始化与销毁，参数变化时自动重新渲染，无需手动操作DOM：

const HeaderComponent = ({/* 所需参数 */}) => {
  useEffect(() => {
    // 执行原script的UI创建逻辑
    const initHeader = () => {
      // 创建并挂载UI到当前组件根节点
    };
    
    initHeader();
    
    return () => {
      // 清理逻辑：移除创建的UI元素
    };
  }, [/* 参数依赖，变化时重新执行 */]);
  
  return <div id='header'></div>;
};

方案B：正确配置Mutation Observer

若必须保留原生script，需调整Observer的监听目标与逻辑：

useEffect(() => {
  // 监听header节点的父元素
  const parentNode = document.getElementById('header')?.parentNode;
  if (!parentNode) return;

  const observer = new MutationObserver((mutations) => {
    mutations.forEach(mutation => {
      // 检测header节点是否被添加
      const headerNode = Array.from(mutation.addedNodes).find(node => node.id === 'header');
      if (headerNode) {
        // 重新执行script的UI初始化逻辑
        initHeaderUI();
      }
    });
  });

  observer.observe(parentNode, { childList: true });
  
  // 首次挂载时执行一次初始化
  const initialHeader = document.getElementById('header');
  if (initialHeader) initHeaderUI();

  return () => observer.disconnect();
}, [/* 触发重新渲染的参数依赖 */]);

方案C：状态驱动Portal渲染

无需依赖Mutation Observer，直接通过状态监听目标元素的存在状态，控制Portal渲染：

import { useState, useEffect } from 'react';
import ReactDOM from 'react-dom';

const PortalComponent = ({ elementId, children }) => {
  const [targetElement, setTargetElement] = useState(null);

  useEffect(() => {
    const updateTarget = () => {
      setTargetElement(document.getElementById(elementId));
    };

    // 初始检查
    updateTarget();
    
    // 监听父节点变化，更新目标元素状态
    const parent = document.getElementById(elementId)?.parentNode;
    if (parent) {
      const observer = new MutationObserver(updateTarget);
      observer.observe(parent, { childList: true });
      return () => observer.disconnect();
    }
  }, [elementId]);

  return targetElement ? ReactDOM.createPortal(children, targetElement) : null;
};

// 使用方式
<PortalComponent elementId='header'>
  <YourUIComponent />
</PortalComponent>

内容的提问来源于stack exchange，提问作者Shivam Sahil