React里怎么获取DOM节点？useRef和querySelector怎么选？

图 1：React 官方 useRef 实例绑定与原生全局 document.querySelector 的底层架构差异

一、React 为什么不推荐直接使用 querySelector？

很多刚从原生 JavaScript 或 jQuery 转向 React 的开发者，在遇到“让输入框自动聚焦”或“获取容器滚动高度”等需求时，第一反应往往是直接调用 document.querySelector('.my-input')。这种写法虽然在单一静态组件下能跑通，但在真实工程架构中，它隐藏着三个致命缺陷：

1. 组件复用与“多实例选择冲突”

React 的核心基石是可复用组件。假设封装了一个通用的搜索框组件 <SearchBar />，在内部使用了 document.querySelector('.search-input')。当页面中同时存在两个搜索框实例（例如顶部导航栏与侧边栏抽屉）时，无论用户点击哪一个实例的清空或聚焦按钮，document.querySelector 都会从根节点向下扫描，并且永远只返回页面结构中第一个出现的节点。这意味着第二个组件实例对自身 DOM 的控制将完全失效，甚至误篡改其他实例的状态。

2. 渲染时序与虚拟 DOM 生命周期错位

React 的渲染是声明式且具备异步批处理特性的。在组件的渲染函数执行期间，JSX 仅仅是描述 UI 的虚拟 DOM 对象，真实的 DOM 尚未创建或尚未更新。如果此时调用 document.querySelector，获取到的结果要么是 null，要么是上一轮渲染残留的旧节点。即便将查询放在 useEffect 中，如果组件内部存在条件渲染（例如 {isOpen && <input />}），全局选择器也无法感知组件的局部挂载节奏，容易产生难以排查的空指针异常。

3. 破坏单向数据流与 Fiber 树协调

React 依靠内部的 Fiber 树来维护组件状态与真实 DOM 的映射关系。如果使用 querySelector 获得节点后，直接通过原生命令式 API（如 element.remove()、element.appendChild() 或直接修改 innerHTML）改动了 DOM 结构，React 在下一次协调（Reconciliation）比对时会因为找不到预期的 DOM 引用而抛出运行时错误（例如常见的 NotFoundError: Failed to execute 'removeChild' on 'Node'）。

图 2：组件多次复用时，useRef 实例隔离与 querySelector 全局冲突的具象对比

二、useRef 获取 DOM 节点的标准规范与步骤

在 React 中，使用 useRef 获取真实 DOM 节点遵循严格的三步走流程：声明引用、挂载绑定、在正确的生命周期阶段中安全访问。

步骤 1：声明 Ref 容器

在函数组件顶层调用 useRef，并传入初始值 null。对于 TypeScript 开发者，建议显式声明对应的 HTML 元素类型：

import React, { useRef, useEffect } from 'react';

function SearchInput() {
  // 1. 声明 Ref 容器，初始值赋为 null
  const inputRef = useRef<HTMLInputElement>(null);
  // ...
}

步骤 2：将 Ref 绑定到 JSX 元素的 ref 属性

React 原生 HTML 标签均原生支持 ref 属性。将声明好的 Ref 传递给目标标签：

  return (
    <div className="search-wrapper">
      {/* 2. 将 inputRef 绑定到真实 DOM 载体 */}
      <input ref={inputRef} type="text" placeholder="请输入搜索内容..." />
      <button onClick={handleFocus}>聚焦</button>
    </div>
  );

步骤 3：在 Commit 完成后的阶段中安全读取

这是最容易出错的环节：严禁在组件渲染函数的主体中直接访问 inputRef.current。在渲染阶段，DOM 节点尚未挂载。正确的访问时机仅限于两种场景：

• 副作用钩子中（useEffect 或 useLayoutEffect）：React 保证在这些钩子执行时，真实的 DOM 节点已经创建并挂载到文档中，inputRef.current 已被赋予对应的 DOM 实例。
• 用户交互事件回调中（如 onClick、onSubmit、onScroll）：事件触发发生在组件挂载之后，DOM 必然处于可用状态。

  // 场景 A：组件挂载完成后自动执行（如自动获取焦点）
  useEffect(() => {
    // 务必使用可选链判空，防止条件渲染导致节点不存在
    inputRef.current?.focus();
  }, []);

  // 场景 B：在按钮点击事件中操作 DOM
  const handleFocus = () => {
    if (inputRef.current) {
      inputRef.current.focus();
      inputRef.current.select(); // 全选输入框文字
    }
  };

图 3：React 生命周期中 useRef 建立与释放的时序流线

三、什么时候必须操作 DOM？React 中合法操作的边界

React 提倡通过状态（State）驱动界面变更，绝大多数的 UI 展示、显隐切换和文字变动都不应该通过直接操作 DOM 来实现。但在以下几种典型的“底层能力”场景下，操作真实 DOM 是必要且合法的：

• 焦点控制与选区管理：输入框聚焦（focus()）、失焦（blur()）以及选中一段文本（setSelectionRange()），这些功能在浏览器中属于原生命令式 API，无法通过声明式状态优雅达成。
• 几何尺寸与物理位置测量：获取容器宽度、精确计算弹窗位置、调用 getBoundingClientRect() 或读取 scrollTop、scrollHeight 等运行时计算值。
• 滚动位置同步：页面跳转或消息流更新时，通过 element.scrollIntoView({ behavior: 'smooth' }) 自动滚入视野。
• 集成第三方非 React 原生类库：在 React 容器中嵌入 D3.js 图表、ECharts、Leaflet 地图、Three.js 画布或特定富文本编辑器时，需要提供一个真实的 DOM 容器给第三方库进行初始化。
• 原生多媒体控制：调用 <video> 或 <audio> 节点的 play()、pause()、修改播放速率或监听原生底层事件。

四、在什么极少数场景下可能会接触 querySelector？如何安全降级？

虽然我们强调 useRef 是绝对首选，但在极个别特殊的架构边界下，开发者确实会遇到单纯依靠 ref 难以直接获取节点的边缘情况。此时如果必须使用 querySelector，必须遵循两套严格的安全降级原则：

1. 容器受限查询（Scoped querySelector）

当你引入了一个黑盒第三方组件（或富文本组件），其内部会动态生成许多深层 HTML 节点，而该库未向外暴露子节点的 ref 时，绝对不能使用 document.querySelector。正确的做法是：使用 useRef 拿到外层包裹容器的 DOM，然后调用该容器的 querySelector：

function RichContentPreview() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;
    // 安全降级：仅在当前组件的容器树内查找，坚决不查询全局 document
    const firstImg = containerRef.current.querySelector('img.render-target');
    if (firstImg) {
      // 执行只读测量或监听
      console.log('图片实际高度:', firstImg.clientHeight);
    }
  }, []);

  return <div ref={containerRef} className="editor-output" />;
}

通过限定在 containerRef.current.querySelector，查找范围被严格锁死在当前组件实例的物理子树内，即便页面复用了多个相同组件，也绝不会发生跨实例污染。

2. 访问 React 根节点之外的外部宿主

另一种场景是需要操作挂载在 React 根节点外部的 DOM，例如在打开模态框时锁定整个页面的滚动条（document.body.style.overflow = 'hidden'），或是操作某个全局 Portal 容器。在这些场景中，如果确实需要使用全局 document，必须在 useEffect 的清理函数（Cleanup function）中完整还原现场，防止产生持久副作用：

useEffect(() => {
  const originalOverflow = document.body.style.overflow;
  document.body.style.overflow = 'hidden';

  // 卸载时必须恢复原状
  return () => {
    document.body.style.overflow = originalOverflow;
  };
}, []);

图 4：React 获取与操作 DOM 选型逻辑推导流程

五、常见认知误区与辨析

在日常代码审查中，常能见到一些看似有理、实则暗藏隐患的说法。针对这些容易混淆的观点，我们进行具体辨析：

说法辨析 1：“只要写在 useEffect 里，querySelector 和 useRef 效果是一样的？”

说法辨析 2：“useRef 只能用来绑定 DOM 节点？”

说法辨析 3：“直接用原生 DOM API 操作节点比调用 setState 渲染性能更好？”

图 5：useRef 与 querySelector 核心指标对比及合规红线速查矩阵

六、全文选型总结清单

简而言之：能用声明式状态解决的，不碰 DOM；必须操作 DOM 的，坚决使用 useRef；在无法预知内部结构的第三方子树中，使用 containerRef.current.querySelector 做局部限定；全局 document.querySelector 仅作为极少数根节点外部交互的最后保底手段，且务必在卸载时彻底清理。遵循这一准则，即可确保 React 应用兼具底层硬件/原生能力与高水准的代码健壮性。