React18+TypeScript5.x中无法通过Context访问Ref属性的问题求助

问题场景 #

在React 18和TypeScript 5.x环境中，通过Context传递useRef创建的Ref对象时，子组件访问ref.current会触发TypeScript类型错误，但实际运行时能正常输出预期值。

父组件（含Context）代码 #

interface MyContextValues {
  ref: LegacyRef<ExternalApi>
} 

export const MyComponentContext = createContext<MyContextValues>({ref:null})

export const MyComponent = () => {
  const ref = useRef<ExternalThing | null>(null);

  useEffect(() => {
    console.log(ref.current); // 此处无类型错误
  }, [ref]);

  return (
    <MyComponentContext.Provider value={{ref}}>
      <SomeComponent ref={ref}/>
    </MyComponentContext.Provider>);
}

export const useMyComponentContext = () => useContext(MyComponentContext);

子组件代码 #

export const MyChildComponent = () => {
  const { ref } = useMyComponentContext();
  useEffect(() => {
    // 类型错误：Property 'current' does not exist on type 'string | ((instance: ExternalThing | null) => void) | RefObject<ExternalThing >'.
    console.log(ref.current);

    // 运行时实际能正常输出预期值
  }, [ref]);
  return <div></div>
}

错误原因 #

Context中定义的ref类型为LegacyRef<ExternalApi>，这个类型是联合类型，包含了字符串Ref、回调Ref和RefObject三种可能。TypeScript无法确定当前ref是哪一种类型，因此会提示current属性不存在于字符串或回调函数类型上。但实际传递的是useRef创建的RefObject，所以运行时能正常访问current。

解决方案 #

方案1：明确Context的Ref类型为RefObject（推荐） #

既然父组件中传递的是useRef生成的RefObject，直接将Context的ref类型限定为RefObject即可，无需兼容其他Ref类型：

import { RefObject } from 'react';

interface MyContextValues {
  ref: RefObject<ExternalThing | null>
} 

export const MyComponentContext = createContext<MyContextValues>({ ref: null })

修改后，子组件中ref的类型会被正确推断为RefObject，访问ref.current不再触发类型错误。

方案2：类型断言（仅在必须保留LegacyRef类型时使用） #

如果因某种原因必须保留LegacyRef类型，可以通过类型断言告诉TypeScript当前ref是RefObject：

useEffect(() => {
  console.log((ref as RefObject<ExternalThing | null>).current);
}, [ref]);

注意：这种方式跳过了TypeScript的类型检查，若后续ref类型发生变更，可能引发运行时错误，需谨慎使用。

方案3：类型守卫（安全兼容LegacyRef的方式） #

通过类型守卫判断ref是否为RefObject，让TypeScript自动缩小类型范围：

useEffect(() => {
  if ('current' in ref) {
    console.log(ref.current);
  }
}, [ref]);

这种方式既保留了类型安全，又能兼容LegacyRef的所有可能类型。

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