React 的 useId Hook：深入了解稳定且唯一的标识符生成

在瞬息万变的 Web 开发领域，确保服务器渲染内容与客户端应用程序之间的一致性至关重要。开发者面临的最持久、最微妙的挑战之一就是生成唯一且稳定的标识符。这些 ID 对于将标签与输入框连接、管理用于可访问性的 ARIA 属性以及许多其他与 DOM 相关的任务都至关重要。多年来，开发者们采用了一些不太理想的解决方案，常常导致 hydration 不匹配和令人沮丧的 bug。React 18 的 `useId` hook 应运而生——这是一个简单而强大的解决方案，旨在优雅而彻底地解决这个问题。

这篇综合指南面向全球的 React 开发者。无论您是在构建一个简单的客户端渲染应用，还是使用 Next.js 等框架开发复杂的服务器端渲染 (SSR) 体验，或是为全世界编写组件库，理解 `useId` 都已不再是可选项。它是构建现代化、健壮且可访问的 React 应用程序的基础工具。

在 `useId` 出现之前的问题：一个充满 Hydration 不匹配的世界

要真正领会 `useId` 的价值，我们必须首先了解没有它时的世界。核心问题始终是需要一个在渲染页面内唯一，同时在服务器和客户端之间保持一致的 ID。

考虑一个简单的表单输入组件：

function LabeledInput({ label, ...props }) {
  // 我们如何在这里生成一个唯一的 ID？
  const inputId = 'some-unique-id';

  return (
    

      {label}
      
    
  );
}

`` 上的 `htmlFor` 属性需要与 `` 的 `id` 匹配，以实现语义化的 HTML 和可访问性。如果我们在页面上多次使用这个 `LabeledInput` 组件，我们需要为每个实例提供一个不同的 ID。

尝试 1：使用 `Math.random()`

生成唯一 ID 时，一个常见的初步想法是使用随机性。

// 反面模式：不要这样做！
const inputId = `input-${Math.random()}`;

为何这种方法会失败：

• SSR 不匹配：服务器会生成一个随机数（例如，`input-0.12345`）。当客户端对应用程序进行 hydration 时，它会重新运行 JavaScript 并生成一个不同的随机数（例如，`input-0.67890`）。React 会发现服务器 HTML 和客户端渲染的 HTML 之间的差异，并抛出一个 hydration 错误。
• 重新渲染：该 ID 会在组件的每一次重新渲染时发生变化，这可能导致意外行为和性能问题。

尝试 2：使用全局计数器

一种稍微复杂点的方法是使用一个简单的递增计数器。

// 反面模式：同样有问题
let globalCounter = 0;
function generateId() {
  globalCounter++;
  return `component-${globalCounter}`;
}

为何这种方法会失败：

• SSR 顺序依赖：起初这似乎可行。服务器按一定顺序渲染组件，客户端再对它们进行 hydration。但是，如果服务器和客户端之间组件渲染的顺序略有不同呢？这可能由于代码分割或乱序流式传输而发生。如果一个组件在服务器上渲染了，但在客户端上延迟了，那么生成的 ID 序列就可能变得不同步，再次导致 hydration 不匹配。
• 组件库的噩梦：如果您是库的作者，您无法控制页面上其他组件是否也在使用它们自己的全局计数器。这可能导致您的库和宿主应用程序之间的 ID 冲突。

这些挑战凸显了对一种能够理解组件树结构、React 原生的、确定性解决方案的需求。这正是 `useId` 所提供的。

`useId` 简介：官方解决方案

The `useId` hook 生成一个唯一的字符串 ID，该 ID 在服务器和客户端渲染中都保持稳定。它被设计用于在组件的顶层调用，以生成传递给可访问性属性的 ID。

核心语法和用法

语法极其简单。它不接受任何参数，并返回一个字符串 ID。

import { useId } from 'react';

function LabeledInput({ label, ...props }) {
  // useId() 生成一个唯一、稳定的 ID，例如 ":r0:"
  const id = useId();

  return (
    

      {label}
      
    
  );
}

// 示例用法
function App() {
  return (
    

      
Sign Up Form
      
      
    
  );
}

在这个例子中，第一个 `LabeledInput` 可能会得到一个像 `":r0:"` 这样的 ID，而第二个可能会得到 `":r1:"`。ID 的确切格式是 React 的实现细节，不应该依赖它。唯一的保证是它将是唯一且稳定的。

关键在于，React 确保在服务器和客户端上生成相同的 ID 序列，从而完全消除了与生成 ID 相关的 hydration 错误。

它的概念性工作原理是什么？

`useId` 的魔力在于其确定性。它不使用随机性。相反，它根据组件在 React 组件树中的路径生成 ID。由于组件树结构在服务器和客户端上是相同的，因此生成的 ID 保证匹配。这种方法能够抵抗组件渲染顺序的影响，而这正是全局计数器方法的致命弱点。

通过一次 Hook 调用生成多个相关 ID

一个常见的需求是在单个组件内生成几个相关的 ID。例如，一个输入框可能需要一个自身的 ID，以及另一个通过 `aria-describedby` 链接的描述元素的 ID。

您可能想多次调用 `useId`：

// 不推荐的模式
const inputId = useId();
const descriptionId = useId();

虽然这样做可行，但推荐的模式是每个组件调用 `useId` 一次，并使用返回的基础 ID 作为您需要的任何其他 ID 的前缀。

import { useId } from 'react';

function FormFieldWithDescription({ label, description }) {
  const baseId = useId();
  const inputId = `${baseId}-input`;
  const descriptionId = `${baseId}-description`;

  return (
    

      {label}
      
      

        {description}
      
    
  );
}

为什么这种模式更好？

• 效率：它确保 React 只需要为该组件实例生成和跟踪一个唯一的 ID。
• 清晰度和语义：它使元素之间的关系变得清晰。任何阅读代码的人都可以看出 `form-field-:r2:-input` 和 `form-field-:r2:-description` 属于一起。
• 保证唯一性：由于 `baseId` 保证在整个应用程序中是唯一的，任何带有后缀的字符串也将是唯一的。

杀手级特性：无缝的服务器端渲染 (SSR)

让我们重新审视 `useId` 旨在解决的核心问题：在像 Next.js、Remix 或 Gatsby 这样的 SSR 环境中的 hydration 不匹配。

场景：Hydration 不匹配错误

想象一个在 Next.js 应用程序中使用我们旧的 `Math.random()` 方法的组件。

1. 服务器渲染：服务器运行组件代码。`Math.random()` 产生 `0.5`。服务器向浏览器发送带有 `` 的 HTML。
2. 客户端渲染 (Hydration)：浏览器接收到 HTML 和 JavaScript 包。React 在客户端启动并重新渲染组件以附加事件监听器（此过程称为 hydration）。在此次渲染期间，`Math.random()` 产生 `0.9`。React 生成一个带有 `` 的虚拟 DOM。
3. 不匹配：React 比较服务器生成的 HTML (`id="input-0.5"`) 和客户端生成的虚拟 DOM (`id="input-0.9"`)。它发现差异并抛出警告："Warning: Prop `id` did not match. Server: "input-0.5" Client: "input-0.9""。

这不仅仅是一个表面上的警告。它可能导致 UI 损坏、事件处理不正确和糟糕的用户体验。React 可能不得不丢弃服务器渲染的 HTML 并执行完整的客户端渲染，从而抵消了 SSR 带来的性能优势。

场景：`useId` 解决方案

现在，让我们看看 `useId` 是如何解决这个问题的。

1. 服务器渲染：服务器渲染组件。调用 `useId`。根据组件在树中的位置，它生成一个稳定的 ID，比如说 `":r5:"`。服务器发送带有 `` 的 HTML。
2. 客户端渲染 (Hydration)：浏览器接收到 HTML 和 JavaScript。React 开始 hydration。它在树中的相同位置渲染相同的组件。`useId` hook 再次运行。因为其结果是基于树结构确定的，所以它会生成完全相同的 ID：`":r5:"`。
3. 完美匹配：React 比较服务器生成的 HTML (`id=":r5:"`) 和客户端生成的虚拟 DOM (`id=":r5:"`)。它们完全匹配。Hydration 成功完成，没有任何错误。

这种稳定性是 `useId` 价值主张的基石。它为一个以前脆弱的过程带来了可靠性和可预测性。

使用 `useId` 增强可访问性 (a11y) 的超能力

虽然 `useId` 对 SSR 至关重要，但其主要的日常用途是提高可访问性。正确地关联元素对于使用屏幕阅读器等辅助技术的用户来说是至关重要的。

`useId` 是连接各种 ARIA (Accessible Rich Internet Applications) 属性的完美工具。

示例：可访问的模态对话框

一个模态对话框需要将其主容器与其标题和描述关联起来，以便屏幕阅读器能够正确地播报它们。

import { useId, useState } from 'react';

function AccessibleModal({ title, children }) {
  const id = useId();
  const titleId = `${id}-title`;
  const contentId = `${id}-content`;

  return (
    

      
{title}
      

        {children}
      
    
  );
}

function App() {
  return (
    
      
By using this service, you agree to our terms and conditions...
    
  );
}

在这里，`useId` 确保无论这个 `AccessibleModal` 在哪里使用，`aria-labelledby` 和 `aria-describedby` 属性都将指向标题和内容元素的正确、唯一的 ID。这为屏幕阅读器用户提供了无缝的体验。

示例：连接组内的单选按钮

复杂的表单控件通常需要仔细的 ID 管理。一组单选按钮应该与一个共同的标签相关联。

import { useId } from 'react';

function RadioGroup() {
  const id = useId();
  const headingId = `${id}-heading`;

  return (
    

      
Select your global shipping preference:
      

        
        Standard (5-10 business days)
      
      

        
        Express (2-3 business days)
      
    
  );
}

通过使用单个 `useId` 调用作为前缀，我们创建了一套内聚、可访问且唯一的控件，这些控件在任何地方都能可靠地工作。

重要区别：`useId` 不应用于什么

能力越大，责任越大。了解在哪些地方不应该使用 `useId` 同样重要。

不要将 `useId` 用于列表的 Keys

这是开发者最常犯的错误。React 的 key 需要是特定数据片段的稳定且唯一的标识符，而不是组件实例的。

错误用法：

function TodoList({ todos }) {
  // 反面模式：绝不要将 useId 用于 keys！
  return (
    

      {todos.map(todo => {
        const key = useId(); // 这是错误的！
        return 
{todo.text}
;
      })}
    
  );
}

这段代码违反了 Hooks 规则（你不能在循环中调用 hook）。但即使你用不同的方式组织代码，逻辑上也是有缺陷的。`key` 应该与 `todo` 项本身绑定，比如 `todo.id`。这使得 React 在添加、删除或重新排序项目时能够正确地跟踪它们。

将 `useId` 用于 key 会生成一个与渲染位置（例如，第一个 `

function TodoList({ todos }) {
  return (
    

      {todos.map(todo => (
        // 正确：使用来自数据的 ID。
        
{todo.text}
      ))}
    
  );
}