React如何同步移除DOM子组件？解决Tanstack Query缓存冲突

问题背景 #

我需要实现点击移除按钮后立即从DOM中移除子组件，但当前基于useState的常规方案存在渲染延迟：点击移除按钮时，先打印FIRST，调用移除函数触发父组件状态更新，接着打印THIRD，最后父组件重新渲染打印SECOND才完成子组件移除。

实际业务场景中，子组件通过Tanstack Query请求数据，调用删除接口后我会移除组件并使缓存失效，但缓存失效早于组件卸载，导致仍处于DOM中的子组件触发已删除数据的接口请求，引发报错。尝试直接操作DOM（如document.getElementById(${index})?.remove()）会抛出Uncaught DOMException: Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node异常。

原实现代码：

type ChildProps = {
  index: number;
  id: string;
  remove: (index: number) => void;
};

function Child(props: ChildProps) {
  const handleClick = () => {
    console.log('FIRST');
    props.remove(props.index);
    console.log('THIRD');
  };
  return (
    <button id={props.id} onClick={handleClick}>
      Child {props.index}
    </button>
  );
}

export default function Home() {
  const [childrens, setChildrens] = React.useState<{ el: React.ReactNode; index: number }[]>([]);

  const removeChildren = (index: number) => {
    setChildrens((old) => old.filter((e) => e.index !== index));
  };

  const addChildren = () => {
    const index = new Date().getTime();
    setChildrens((old) => [
      ...old,
      { index, el: <Child id={`${index}`} index={index} remove={removeChildren} /> },
    ]);
  };

  console.log('SECOND');
  return (
    <div>
      <button onClick={addChildren}>Add</button>
      <div>{childrens.map((e) => e.el)}</div>
    </div>
  );
}

可行解决方案 #

方案1：子组件内部维护卸载状态（推荐） #

在子组件中添加isUnmounted状态，点击移除按钮时立即标记为卸载状态，阻止后续Query请求，同时通知父组件更新状态，视觉上瞬间移除组件。

修改后代码：

import { useQuery } from '@tanstack/react-query';

type ChildProps = {
  index: number;
  id: string;
  remove: (index: number) => void;
};

// 模拟删除接口请求
const deleteItem = (index: number) => new Promise(resolve => setTimeout(resolve, 100));
// 模拟数据获取请求
const fetchData = (index: number) => fetch(`/api/item/${index}`).then(res => res.json());

function Child(props: ChildProps) {
  const [isUnmounted, setIsUnmounted] = React.useState(false);
  
  // 通过enabled控制Query是否执行，卸载状态下禁用请求
  const { data } = useQuery({
    queryKey: ['childData', props.index],
    queryFn: () => fetchData(props.index),
    enabled: !isUnmounted
  });

  const handleClick = async () => {
    console.log('FIRST');
    // 立即标记为卸载状态，视觉上移除组件
    setIsUnmounted(true);
    // 执行删除接口请求
    await deleteItem(props.index);
    // 通知父组件更新状态
    props.remove(props.index);
    console.log('THIRD');
  };

  // 卸载状态下直接返回null，组件从DOM中移除
  if (isUnmounted) return null;

  return (
    <button id={props.id} onClick={handleClick}>
      Child {props.index}
    </button>
  );
}

export default function Home() {
  // 父组件不再存储已渲染的ReactNode，改为存储组件元数据，确保每次渲染都是最新实例
  const [childrenMeta, setChildrenMeta] = React.useState<{ index: number; id: string }[]>([]);

  const removeChildren = (index: number) => {
    setChildrenMeta(old => old.filter(e => e.index !== index));
  };

  const addChildren = () => {
    const index = new Date().getTime();
    setChildrenMeta(old => [...old, { index, id: `${index}` }]);
  };

  console.log('SECOND');
  return (
    <div>
      <button onClick={addChildren}>Add</button>
      <div>
        {childrenMeta.map(meta => (
          <Child key={meta.index} id={meta.id} index={meta.index} remove={removeChildren} />
        ))}
      </div>
    </div>
  );
}

核心改进：

• 父组件存储组件元数据而非已渲染节点，避免缓存旧组件实例
• 子组件通过isUnmounted状态立即控制渲染，实现视觉上的即时移除
• Tanstack Query的enabled选项绑定卸载状态，阻止无效请求

方案2：通过Ref安全操作DOM（应急方案） #

若必须直接操作DOM，需通过React的forwardRef获取子组件真实DOM节点，先移除DOM再通知父组件更新状态，避免React虚拟DOM与真实DOM不一致。

type ChildProps = {
  index: number;
  id: string;
  remove: (index: number) => void;
};

function Child(props: ChildProps, ref: React.Ref<HTMLButtonElement>) {
  const handleClick = async () => {
    console.log('FIRST');
    // 通过ref直接移除DOM节点
    if (ref.current) {
      ref.current.remove();
    }
    await deleteItem(props.index);
    // 通知父组件更新状态，保持虚拟DOM与真实DOM同步
    props.remove(props.index);
    console.log('THIRD');
  };

  return (
    <button ref={ref} id={props.id} onClick={handleClick}>
      Child {props.index}
    </button>
  );
}

// 转发ref到子组件
const ForwardedChild = React.forwardRef(Child);

export default function Home() {
  const [childrenMeta, setChildrenMeta] = React.useState<{ index: number; id: string }[]>([]);
  // 存储所有子组件的ref
  const childRefs = React.useRef<Record<number, HTMLButtonElement | null>>({});

  const removeChildren = (index: number) => {
    setChildrenMeta(old => old.filter(e => e.index !== index));
    // 清理不再需要的ref
    delete childRefs.current[index];
  };

  const addChildren = () => {
    const index = new Date().getTime();
    setChildrenMeta(old => [...old, { index, id: `${index}` }]);
  };

  console.log('SECOND');
  return (
    <div>
      <button onClick={addChildren}>Add</button>
      <div>
        {childrenMeta.map(meta => (
          <ForwardedChild
            key={meta.index}
            ref={el => childRefs.current[meta.index] = el}
            id={meta.id}
            index={meta.index}
            remove={removeChildren}
          />
        ))}
      </div>
    </div>
  );
}

注意事项：

• 直接操作DOM违背React设计理念，仅作为应急方案使用
• 移除DOM后必须通知父组件更新状态，否则会导致后续渲染冲突

方案3：调整Tanstack Query缓存失效时机 #

若问题核心是缓存失效早于组件卸载，可利用React的useEffect清理函数，在子组件卸载后再执行缓存失效操作。

import { useQuery, useQueryClient } from '@tanstack/react-query';

function Child(props: ChildProps) {
  const queryClient = useQueryClient();
  
  const { data } = useQuery({
    queryKey: ['childData', props.index],
    queryFn: () => fetchData(props.index),
  });

  const handleClick = async () => {
    console.log('FIRST');
    await deleteItem(props.index);
    props.remove(props.index);
    console.log('THIRD');
  };

  // 组件卸载时才执行缓存失效
  React.useEffect(() => {
    return () => {
      queryClient.invalidateQueries({ queryKey: ['childData', props.index] });
    };
  }, [props.index, queryClient]);

  return (
    <button id={props.id} onClick={handleClick}>
      Child {props.index}
    </button>
  );
}

优势：

• 无需额外状态控制，利用React生命周期自动处理
• 确保缓存失效发生在组件卸载后，避免子组件触发无效请求

内容的提问来源于stack exchange，提问作者Marco Morozzi