React 的正确使用方法:ref 篇
阿里妹导读
说到 useRef,相信你一定不会陌生:你可以用它来获取 DOM 元素,也可以多次渲染之间保持引用不变……
然而,你真的用对了 useRef 吗?在与 TypeScript 一起使用、以及撰写组件库的情况下,你的写法能够避开以下所有场景的坑吗?
场景一:获取 DOM 元素
以下几种写法,哪种是正确的?
function MyComponent() {
// 写法 1
const ref = useRef();
// 写法 2
const ref = useRef(undefined);
// 写法 3
const ref = useRef(null);
// 通过 ref 计算 DOM 元素尺寸
// 🚨 这段代码故意留了坑,坑在哪里?请看下文。
useLayoutEffect(() => {
const rect = ref.current.getBoundingClientRect();
}, [ref.current]);
return <div ref={ref} />;
}
如果只看 JS,几种写法似乎并没有差别,但如果你开启了 TS 的类型提示,就能够发现其中端倪:
function MyComponent() {
// ❌ 写法 1
// 你会得到一个 MutableRefObject<HTMLDivElement | undefined>,
// 即 ref.current 类型是 HTMLDivElement | undefined,
// 这导致你每次获取 DOM 元素都需要判断是否为 undefined,很是麻烦。
const ref = useRef<HTMLDivElement>();
// ❌ 写法 2.1
// 你可能想得到一个 MutableRefObject<HTMLDivElement>,但初始值传入的
// undefined 并不是 HTMLDivElement,所以会 TS 报错。
const ref = useRef<HTMLDivElement>(undefined);
// ❌ 写法 2.2
// 等价于写法 1,但需要多打一些字。
const ref = useRef<HTMLDivElement | undefined>(undefined);
// ✅ 写法 3
// 你会得到一个 RefObject<HTMLDivElement>,其中
// ref.current 类型是 HTMLDivElement | null。
// 这个 ref 的 current 是不可从外部修改的,更符合使用场景下的语义,
// 也是 React 推荐的获取 DOM 元素方式。
// 注意:如果 tsconfig 没开 strictNullCheck,则不会匹配到这个定义,
// 因此请务必开启 strictNullCheck。
const ref = useRef<HTMLDivElement>(null);
// 通过 ref 计算 DOM 元素尺寸
// 🚨 这段代码故意留了坑,坑在哪里?请看下文。
useLayoutEffect(() => {
const rect = ref.current.getBoundingClientRect();
}, [ref.current]);
return <div ref={ref} />;
}
Ref 还可以传入一个函数,会把被 ref 的对象应用作为参数传入,因此我们也可以这样获取 DOM 元素:
function MyComponent() {
const [divEl, setDivEl] = useState<HTMLDivElement | null>(null);
// 计算 DOM 元素尺寸
useEffect(() => {
if (divEl) {
divEl.current.getBoundingClientRect();
}
}, [divEl]);
return <div ref={setDivEl} />;
}
场景二:DOM 元素与 useLayoutEffect
在场景一中,我们留了一个坑,你能看出以下代码有什么问题吗?
/* 🚨 错误案例,请勿照抄 */
function MyComponent({ visible }: { visible: boolean }) {
const ref = useRef<HTMLDivElement>(null);
useLayoutEffect(() => {
const rect = ref.current.getBoundingClientRect();
// ...
}, [ref.current]);
return <>{visible && <div ref={ref}/>}</>;
}
1. useLayoutEffect 中没有判空
useRef<HTMLDivElement>(null) 返回的类型是RefObject<HTMLDivELement>,其ref.current 类型为HTMLDivELement | null。因此单从 TS 类型出发,也应该判断ref.current 是否为空。
你也许会认为,我都在 useLayoutEffect 里了,此时组件 DOM 已经生成,因而理应存在 ref.current,是否可以不用判断呢?(或用 ! 强制设为非空)
上述使用场景中,确实可以这样做,但如果div 是条件渲染的,则无法保证useLayoutEffect 时组件已被渲染,自然也就不一定存在ref.current。
2. useLayoutEffect deps 配置错误
这个问题涉及到useLayoutEffect 更本质的使用目的。
useLayoutEffect 的执行时机是:
‒最终提交渲染之前(同步任务返回前)。
由于其执行时机在 repaint 之前,此时对已生成的 DOM 进行更改,用户不会看到「闪一下」。举个例子,你可以计算元素的尺寸,如果太大则修改 CSS 使其自动换行,从而实现溢出检测。
另一个常见场景是在useLayoutEffect 中获取原生组件,用来添加原生 listener、获取底层HTMLMediaElement 实例来控制播放,或添加ResizeObserver、IntersectionObserver 等。
这里,由于div 是条件渲染的,我们显然会希望useLayoutEffect 的操作在每次渲染出来之后都执行一遍,因此我们会想把ref.current 写进useLayoutEffect 的dependencies,但这是完全错误的。
让我们盘一下MyComponent 的渲染过程:
5.由于<div ref={ref}>,React 使用新的 DOM 元素更新ref.current。
显然,这里并没有再次触发useLayoutEffect,直到下一次渲染中才会发现ref.current 有变化,这背离了我们对于 useLayoutEffect 能让用户看不到「闪一下」的预期。
解决方案是,使用与条件渲染相同的条件作为useLayoutEffect 的 deps:
function MyComponent({ visible }: { visible: boolean }) {
const ref = useRef<HTMLDivElement>(null);
useLayoutEffect(() => {
// 这里不必额外判断 if (visible),因为只要这里有 ref.current 那就必然是 visible
if (ref.current) {
const rect = ref.current.getBoundingClientRect();
}
}, [/* ✅ */ visible]);
// 这样,在 visible 变化时,就必然会在同一次渲染内触发 useLayoutEffect
return <>{visible && <div ref={ref}/>}</>;
}
// 或者也可以将 <div> 抽取成一个独立的组件,从而避免上述问题
最后,如果并非是要在 repaint 之前对 DOM 元素进行操作,更推荐的写法是用函数写法:
function MyComponent({ visible }: { visible: boolean }) {
// ✅ 无需使用 ref
const [video, setVideo] = useState<Video | null>(null);
const play = useCallback(() => video?.play(), [video]);
// ✅ 使用普通 useEffect 即可
useEffect(() => {
console.log(video.currentTime);
}, [video]);
return <>{visible && <video ref={setVideo}/>}</>;
}
场景三:组件中同时传递 & 获取 Ref
——你实现了一个组件,想要将传入的 ref 传给组件中渲染的根元素,听起来很简单!
哦对了,出于某种原因,你的组件中也需要用到根组件的 ref,于是你写出了这样的代码:
/* 🚨 错误案例,请勿照抄 */
const MyComponent = forwardRef(
function (
props: MyComponentProps,
// type ForwardedRef<T> =
// | ((instance: T | null) => void)
// | MutableRefObject<T | null>
// | null
// ✅ 这个工具类型覆盖了传 useRef 和传 setState 的情况,是正确的写法
ref: ForwardedRef<HTMLDivElement>
) {
useLayoutEffect(() => {
const rect = ref.current.getBoundingClientRect();
// 使用 rect 进行计算
}, []);
return <div ref={ref}>{/* ... */}</div>;
}
});
/* 🚨 错误案例,请勿照抄 */
const MyComponent = forwardRef(
function (
props: MyComponentProps,
ref: ForwardedRef<HTMLDivElement>
) {
const localRef = useRef<HTMLDivElement>(null);
useLayoutEffect(() => {
const rect = localRef.current.getBoundingClientRect();
// 使用 rect 进行计算
}, []);
return <div ref={(el: HTMLDivElement) => {
localRef.current = el;
if (ref) {
ref.current = el;
}
}}>{/* ... */}</div>;
}
});
这样的代码显然是会 TS 报错的,因为ref 可能是个函数,本来你只需要把它直接传给<div> 就好了,因此你需要写一堆代码,处理多种可能的情况……
更好的解决方式是使用 react-merge-refs:
import { mergeRefs } from "react-merge-refs";
const MyComponent = forwardRef(
function (
props: MyComponentProps,
ref: ForwardedRef<HTMLDivElement>
) {
const localRef = React.useRef<HTMLDivElement>(null);
useLayoutEffect(() => {
const rect = localRef.current.getBoundingClientRect();
// 使用 rect 进行计算
}, []);
return <div ref={mergeRefs([localRef, ref])} />;
}
);
场景四:组件透出命令式操作
Form 和 Table 这种复杂的组件往往会在组件内维护较多状态,不适合受控操作,当调用者需要控制组件行为时,往往就会采取这样的模式:
function MyPage() {
const ref = useRef<FormRef>(null);
return (
<div>
<Button onClick={() => { ref.current.reset(); }}>重置表单</Button>
<Form actionRef={ref}>{/* ... */}</Form>
</div>
);
}
这种用法实际上脱胎于 class component 时代,人们使用 ref 来获取 class 实例,通过调用实例方法来控制组件。
现在,你的超级复杂绝绝子组件也希望通过这种方式与调用者交互,于是你写出了以下实现:
/* 🚨 错误案例,请勿照抄 */
interface MySuperDuperComponentAction {
reset(): void;
}
const MySuperDuperComponent = forwardRef(
function (
props: MySuperDuperComponentProps,
ref: ForwardedRef<MySuperDuperComponentAction>
) {
const action = useMemo((): MySuperDuperComponentAction => ({
reset() {
// ...
}
}), [/* ... */]);
if (ref) {
ref.current = action;
}
return <div/>;
}
);
然而 TS 不会容许这样的代码通过类型检查,因为调用者可以函数作为 ref 来接收 action,这与获取 DOM 元素时类似。
正确的做法是,你应该使用 React 提供的工具函数useImperativeHandle:
const MyComponent = forwardRef(
function (
props: MyComponentProps,
ref: ForwardedRef<MyComponentRefType>
) {
// useImperativeHandle 这个工具函数会自动处理函数 ref 和对象 ref 的情况,
// 后两个参数基本等于 useMemo
useImperativeHandle(ref, () => ({
refresh: () => {
// ...
},
// ...
}), [/* deps */]);
// 命令式 + 下传
// 如果你的组件内部也会用到这个命令式对象,推荐的写法是:
const actions = useMemo(() => ({
refresh: () => {
// ...
},
}), [/* deps */]);
useImperativeHandle(ref, () => actions, [actions]);
return <div/>;
}
);
场景五:组件 TS 导出如何声明 Ref 类型
如果内部的组件类型正确,forwardRef 会自动检测 ref 类型:
const MyComponent = forwardRef(
function (
props: MyComponentProps,
ref: ForwardedRef<MyComponentRefType>
) {
return <div/>;
}
});
// 其结果类型为:
// const MyComponent: ForwardRefExoticComponent<
// PropsWithoutRef<MyComponentProps> & RefAttributes<MyComponentRefType>
// >
// 这里最后导出的 PropsWithoutRef<P> & RefAttributes<T> 就是用户侧最终可传的类型,
// 其中 PropsWithoutRef 会无视你 component 中 props 的 ref。
这里有一个问题:你的组件导出的 Props 中需要包含 ref 吗?由于forwardRef 会强行改掉你的 ref,这里有两种方法:
2.用ComponentProps<typeof MyComponent> 取出最终的 Props。
然而,当组件内需要必须层层透传 ref 的时候,如果把 ref 写进 Props 里,就需要每层组件都使用 forwardRef,否则就会出现问题:
/* 🚨 错误案例,请勿照抄 */
interface OtherComponentProps {
ref?: Ref<OtherComponentActions>;
}
interface MyComponentProps extends OtherComponentProps {
myAdditionalProp: string;
}
// 这是错误的,props 里根本拿不到 ref!
function MyComponent({ myAdditionalProp, ...props }: MyComponentProps) {
console.log(myAdditionalProp);
return <OtherComponent {...props} />;
}
因此,更推荐的方案是不用 ref 这个名字,比如叫 actionRef 等等,这样也可以毫无痛苦地写进 props 并导出了。
Bonus: 与 Ref 相关的 TS 类型
PropsWithoutRef<Props>:从 Props 中删除 ref,可用于 HOC 等场景。 PropsWithRef<Props>:并不会添加 ref,而是保证 ref 里没有 string。这是因为在古代,可以给 ref 传 string 来代替传函数,现代我们一般不这么做。 如果想要添加 ref,可以仿照forwardRef 里的写法:PropsWithoutRef<Props> & RefAttribute<RefType>。 RefAttribute<RefType>:{ ref?: Ref<T> | undefined; }。 ForwardedRef<RefType>:组件内部拿外部 ref 唯一指定类型。 MutableRefObject<RefType>:useRef 和 createRef 的结果。 RefObject<RefType>:useRef(null) 的结果。 Ref<RefType>:传入的 ref 参数类型,RefType 即 ref.current 拿到的类型,会自动加上 null。
注意:这个类型包括 RefObject 与函数。 注注意:这个类型与 ForwardedRef 的区别是,它只需要 RefObject 而非 MutableRefObject,因此可以接受 useRef(null) 的结果并被用于 props。组件内部由于需要修改 ref.current,必须使用 MutableRefObject。
ForwardRefExoticComponent:forwardRef 的返回类型。
这些类型类似于 React 提供的类型接口,为了保证你的组件能够兼容尽可能多的 React 版本,请务必使用最合适的类型。
网站文本内容安全检测
通过内容安全API提供直播场景的文本检测能力,响应时间短、支持类型多,多维度判断风险行为。
点击阅读原文查看详情。
微信扫码关注该文公众号作者