React useEffect依赖数组：ref.current与ref.current.property的疑问及解法

问题背景 #

我用React组件结合Google Maps街景功能，通过useImperativeHandle向父组件暴露街景全景实例。需求是街景Ref可用后，将其关联到Google Maps的Ref，但组件挂载后，空依赖数组的useEffect首次调用时，streetViewRef.current.panorama是undefined。后来把streetViewRef.current?.panorama加入依赖数组解决了问题，但对原理有疑问。

相关代码：

StreetView.tsx #

const StreetView = forwardRef((props, ref) => {
  useImperativeHandle(ref, () => ({
    updateView,
    panorama: streetViewPanoramaRef.current,
  }));
  // ... 组件其余代码
});

Parent.tsx #

const ParentComponent = () => {
  const streetViewRef = useRef<StreetViewHandle>(null);
  const mapRef = useRef<GoogleMap>(null);

  useEffect(() => {
    if (streetViewRef.current && mapRef.current?.map) {
      streetViewRef.current.updateView(/* ... */);
      mapRef.current.map.setStreetView(streetViewRef.current.panorama);
    }
  }, [streetViewRef.current?.panorama]); // 为何这样可行？

  return (
    <>
      <GoogleMap ref={mapRef} />
      <StreetView ref={streetViewRef} />
    </>
  );
};

疑问解答 #

1. 为什么将streetViewRef.current加入依赖数组是错误的，而streetViewRef.current?.panorama能解决问题？ #

• useRef创建的streetViewRef本身是不可变的引用对象，它的current属性可以修改，但streetViewRef这个对象的引用从组件挂载到卸载都不会变。如果把streetViewRef.current放进依赖数组，React依赖对比时会认为这个值的引用没变化（哪怕对象内部的panorama属性更新了），所以useEffect不会重新执行，自然拿不到有效的全景实例。
• 而streetViewRef.current?.panorama是具体的属性值：当StreetView组件内的streetViewPanoramaRef.current完成初始化（拿到Google Maps街景实例），useImperativeHandle会更新暴露给父组件的对象，此时streetViewRef.current?.panorama的值从undefined变成有效实例，依赖数组检测到这个值变化，就会重新执行useEffect，这时就能顺利关联街景和地图了。

2. 为什么省略panorama时，代码检查工具（linter）不会提示缺少依赖？ #

• React的ESLint规则（比如react-hooks/exhaustive-deps）对useRef的current属性处理特殊：它知道ref.current是可变的，但默认不会把ref.current当成必须依赖——因为ref本身的引用不变，规则无法静态分析到你在useEffect里访问了ref.current内部的嵌套属性（比如panorama）。
• 简单说，linter只会检查useEffect里直接用到的顶层变量，不会遍历对象的嵌套属性。你在useEffect里用的是streetViewRef.current.panorama，但linter只会检测streetViewRef，而streetViewRef是useRef创建的，规则认为它不需要加入依赖，所以不会触发提示。

3. 解决该问题的正确方式是什么？ #

目前你用的依赖数组方式是可行的，但有更符合React数据流理念的方案：

方案1：保持现有方式（依赖panorama）

如果场景简单，这种方式没问题，但要注意：useImperativeHandle每次重新执行时，会返回新的对象（或更新属性值），所以streetViewRef.current?.panorama会变化触发useEffect。只要确认panorama只会从undefined变成有效值、不会频繁变化，这个方式可以保留。

方案2：通过回调通知父组件（推荐）

在StreetView组件内部，当全景实例初始化完成后，通过props回调通知父组件，父组件在回调里执行关联操作，更符合React单向数据流原则：

// StreetView.tsx
const StreetView = ({ onPanoramaReady }, ref) => {
  useEffect(() => {
    if (streetViewPanoramaRef.current) {
      onPanoramaReady(streetViewPanoramaRef.current);
    }
  }, [onPanoramaReady]);

  useImperativeHandle(ref, () => ({
    updateView,
    panorama: streetViewPanoramaRef.current,
  }));
  // ... 其余代码
};

// Parent.tsx
const ParentComponent = () => {
  const streetViewRef = useRef<StreetViewHandle>(null);
  const mapRef = useRef<GoogleMap>(null);

  const handlePanoramaReady = useCallback((panorama) => {
    if (mapRef.current?.map) {
      streetViewRef.current?.updateView(/* ... */);
      mapRef.current.map.setStreetView(panorama);
    }
  }, []);

  return (
    <>
      <GoogleMap ref={mapRef} />
      <StreetView ref={streetViewRef} onPanoramaReady={handlePanoramaReady} />
    </>
  );
};

这种方式不需要依赖ref的嵌套属性，逻辑更清晰，也避免了依赖数组的潜在问题。

方案3：用状态跟踪panorama

在父组件中用useState跟踪panorama的状态，当StreetView的ref更新时同步状态，再依赖这个状态执行操作：

// Parent.tsx
const ParentComponent = () => {
  const streetViewRef = useRef<StreetViewHandle>(null);
  const mapRef = useRef<GoogleMap>(null);
  const [panorama, setPanorama] = useState<StreetViewPanorama | null>(null);

  // 监听ref变化，更新panorama状态
  useEffect(() => {
    setPanorama(streetViewRef.current?.panorama || null);
  }, [streetViewRef.current?.panorama]);

  useEffect(() => {
    if (panorama && mapRef.current?.map) {
      streetViewRef.current?.updateView(/* ... */);
      mapRef.current.map.setStreetView(panorama);
    }
  }, [panorama]);

  return (
    <>
      <GoogleMap ref={mapRef} />
      <StreetView ref={streetViewRef} />
    </>
  );
};

这种方式把可变的ref属性转化为响应式状态，更符合React的状态管理逻辑，但比回调方式多一层状态跟踪。

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