useImperativeHandle与直接挂载属性到ref的差异分析

我正在开发一个UI库，其中包含一个TagPicker组件，用户可通过该组件选择标签进行搜索筛选。在考虑组件状态由父组件管理还是内部管理时，遇到了一个问题：当组件内部维护状态时，如何让外部（如父组件）访问内部的selectedTags和setSelectedTags？下面对比两种实现方式，并重点分析直接通过useEffect挂载属性到ref.current的方案。

基础场景：内部维护状态的TagPicker #

先看组件内部维护状态的基础实现：

import React, { useState, type HTMLAttributes } from 'react'

type SelectedTagsState = { id: string; title: string }[];
type Props = HTMLAttributes<HTMLDivElement> & { tags?: SelectedTagsState };

const TagPicker = React.forwardRef<HTMLDivElement, Props>(({ tags, ...rest }, ref) => {
    const [selectedTags, setSelectedTags] = useState<SelectedTagsState>([]);

    return (
      <div ref={ref} {...rest}>
        {tags?.map(tag => (
          <div
            key={tag.id}
            title={tag.title}
            className={selectedTags.includes(tag) ? 'active' : ''}
          >
            {tag.title}
          </div>
        ))}
      </div>
    )
})

方案一：使用useImperativeHandle暴露API #

这是React官方推荐的命令式暴露组件内部能力的方式：

import React, { useState, useImperativeHandle, type HTMLAttributes } from 'react'

type SelectedTagsState = { id: string; title: string }[];
type TagPickerRef = {
  getSelectedTags: () => SelectedTagsState;
  setSelectedTags: React.Dispatch<React.SetStateAction<SelectedTagsState>>;
};
type Props = HTMLAttributes<HTMLDivElement> & { tags?: SelectedTagsState };

const TagPicker = React.forwardRef<TagPickerRef, Props>(({ tags, ...rest }, ref) => {
    const [selectedTags, setSelectedTags] = useState<SelectedTagsState>([]);

    useImperativeHandle(ref, () => ({
      getSelectedTags: () => selectedTags,
      setSelectedTags   
    }), [selectedTags]);

    return (
      <div {...rest}>
        {tags?.map(tag => (
          <div
            key={tag.id}
            title={tag.title}
            className={selectedTags.includes(tag) ? 'active' : ''}
          >
            {tag.title}
          </div>
        ))}
      </div>
    )
})

核心优势 #

• 符合React设计规范：明确界定外部可访问的API，不会污染DOM原生属性。
• 类型友好：可通过TypeScript清晰定义ref的类型，让使用者明确组件暴露的能力。
• 时机可靠：ref的赋值与组件渲染流程绑定，不会出现初始阶段API未就绪的情况。
• 灵活可控：可以选择暴露的内容，比如用getSelectedTags方法避免直接暴露内部state，降低外部误修改的风险。

方案二：通过useEffect直接挂载属性到ref.current #

这种方式直接将组件内部状态和方法挂载到DOM元素的ref上：

import React, { useState, useEffect, type HTMLAttributes } from 'react'

type SelectedTagsState = { id: string; title: string }[];
type Props = HTMLAttributes<HTMLDivElement> & { tags?: SelectedTagsState };

const TagPicker = React.forwardRef<HTMLDivElement, Props>(({ tags, ...rest }, ref) => {
    const [selectedTags, setSelectedTags] = useState<SelectedTagsState>([]);

    useEffect(() => {
      if (ref.current) {
        ref.current.selectedTags = selectedTags;
        ref.current.setSelectedTags = setSelectedTags;
      }
    }, [ref, selectedTags, setSelectedTags]);

    return (
      <div ref={ref} {...rest}>
        {tags?.map(tag => (
          <div
            key={tag.id}
            title={tag.title}
            className={selectedTags.includes(tag) ? 'active' : ''}
          >
            {tag.title}
          </div>
        ))}
      </div>
    )
})

表面优点 #

• 保留了DOM节点的所有原生属性，外部可同时访问DOM原生方法（如focus、scroll）和组件内部状态。
• 写法直观，无需额外hook包裹。

缺点与风险（属于反模式） #

1. 污染DOM实例：DOM元素的ref设计初衷是暴露原生属性和方法，强行挂载自定义属性可能与未来的DOM标准属性冲突（比如浏览器后续新增selectedTags属性）。
2. 时机延迟：useEffect在组件渲染完成后执行，若父组件在组件刚挂载时就访问ref上的自定义属性，会得到undefined，而useImperativeHandle的赋值时机更可靠。
3. 类型不兼容：TypeScript中HTMLElement类型不包含这些自定义属性，需要频繁类型断言，容易引发类型错误，不利于UI库的易用性。
4. 状态同步延迟：虽然依赖了selectedTags，但useEffect的执行存在轻微延迟，外部访问selectedTags可能拿到过时的值；而useImperativeHandle中getSelectedTags每次调用都会获取最新state。
5. 潜在内存泄漏：若ref动态变化（比如父组件传递回调ref），旧DOM实例可能仍保留过时属性，引发意外问题。

折中方案：同时保留DOM能力与规范API #

如果需要让外部同时访问DOM原生属性和组件自定义API，可以通过useImperativeHandle合并DOM元素和自定义API：

import React, { useState, useImperativeHandle, type HTMLAttributes } from 'react'

type SelectedTagsState = { id: string; title: string }[];
type TagPickerRef = HTMLDivElement & {
  getSelectedTags: () => SelectedTagsState;
  setSelectedTags: React.Dispatch<React.SetStateAction<SelectedTagsState>>;
};
type Props = HTMLAttributes<HTMLDivElement> & { tags?: SelectedTagsState };

const TagPicker = React.forwardRef<TagPickerRef, Props>(({ tags, ...rest }, ref) => {
  const [selectedTags, setSelectedTags] = useState<SelectedTagsState>([]);
  const divRef = React.useRef<HTMLDivElement>(null);

  useImperativeHandle(ref, () => ({
    ...divRef.current,
    getSelectedTags: () => selectedTags,
    setSelectedTags
  }), [selectedTags]);

  return (
    <div ref={divRef} {...rest}>
      {tags?.map(tag => (
        <div
          key={tag.id}
          title={tag.title}
          className={selectedTags.includes(tag) ? 'active' : ''}
        >
          {tag.title}
        </div>
      ))}
    </div>
  )
})

这种方式既遵循React规范，又能满足外部访问DOM和组件API的需求，类型也能完美推导。

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