React useId 教程：为 label 和 ARIA 生成唯一 ID

useId 为组件的每个实例返回一个唯一的 id，并且每次渲染都返回同一个 id。当组件可能在页面上出现不止一次时，用它把 <label> 和对应的 <input> 关联起来，或者通过 aria-describedby 把 input 和它的提示关联起来。

import { useId } from 'react';

function PasswordField({ label }) {
    const id = useId();
    const hintId = `${id}-hint`;
    return (
        <div style={{ marginBottom: 16 }}>
            <label htmlFor={id}>{label}</label>
            <br />
            <input id={id} type="password" aria-describedby={hintId} />
            <p id={hintId} style={{ margin: '4px 0', fontSize: 13, color: '#666' }}>
                At least 12 characters.
            </p>
            <code style={{ fontSize: 12 }}>
                id = {id}, hint id = {hintId}
            </code>
        </div>
    );
}

export default function App() {
    return (
        <form>
            <PasswordField label="Password" />
            <PasswordField label="Confirm password" />
        </form>
    );
}

同一个组件渲染了两次，得到两个不同的 id，分别显示在每个字段下方。点击文字“Confirm password”，焦点会跳到第二个输入框，因为它的 htmlFor 只与那个输入框的 id 匹配。如果把 useId() 换成写死的 id="password"，两个 label 都会指向第一个输入框。

语法

const id = useId();

useId 不接收参数，返回一个字符串。和所有 Hook 一样，在组件的顶层调用它。它的具体格式属于内部实现，在不同版本之间变过：React 18 生成 :r1:；React 19.2 中，首次在浏览器中渲染的组件得到 _r_1_，在服务器上渲染的组件得到一个以 _R_ 开头、根据树中位置生成的 id。永远不要解析它，也不要依赖它的格式。

为什么不用 Math.random 或计数器

用于无障碍访问的 id，必须在服务器发送的 HTML 和 React 在浏览器中构建的树之间保持一致。最容易想到的两种生成 id 的方法都过不了这一关。

// Changes on every render, and differs between server and browser
const id = 'field-' + Math.random().toString(36).slice(2);

// The server's counter keeps growing across requests, the browser starts at 0
let nextId = 0;
const id = 'field-' + nextId++;

在服务端渲染时（Next.js、React Router 的框架模式，或任何使用 hydrateRoot 的项目），服务器在 HTML 中输出 id="field-4817"，浏览器第一次渲染算出的是 field-0，React 就会报告 hydration 不匹配。useId 根据组件在树中的位置生成 id，而这个位置在两边完全相同。

即使没有服务器，在渲染期间生成的 id 也可能每次渲染都变。下面这个例子不涉及任何服务器，就能看出区别：

import { useId, useState } from 'react';

let nextId = 0;

function Field({ label }) {
    const stable = useId();
    const unstable = `field-${nextId++}`;
    console.log(label, 'useId:', stable, '| counter:', unstable);
    return (
        <p>
            <label htmlFor={stable}>{label}</label> <input id={stable} />
            <br />
            <small>useId: {stable}, counter: {unstable}</small>
        </p>
    );
}

export default function App() {
    const [renders, setRenders] = useState(0);
    return (
        <div>
            <button onClick={() => setRenders(renders + 1)}>Render again ({renders})</button>
            <Field label="Name" />
            <Field label="Email" />
        </div>
    );
}

多点几次按钮。useId 的值保持不变，而计数器生成的 id 每渲染一次就增加一次，于是原本指向旧 id 的东西（aria-describedby、label）现在什么都指不到了。把计数器包进 useState(() => nextId++) 能解决重新渲染的问题，但解决不了服务端不匹配的问题。

一次调用得到多个 id

一个有多个字段的组件不需要调用多次 useId。生成一个基础 id，再给每个元素加上后缀即可。

import { useId, useState } from 'react';

function SignupForm() {
    const id = useId();
    const [email, setEmail] = useState('');
    const invalid = email !== '' && !email.includes('@');

    return (
        <form onSubmit={(e) => e.preventDefault()}>
            <p>
                <label htmlFor={`${id}-name`}>Name</label>{' '}
                <input id={`${id}-name`} />
            </p>
            <p>
                <label htmlFor={`${id}-email`}>Email</label>{' '}
                <input
                    id={`${id}-email`}
                    value={email}
                    onChange={(e) => setEmail(e.target.value)}
                    aria-invalid={invalid}
                    aria-describedby={invalid ? `${id}-error` : undefined}
                />
            </p>
            {invalid && (
                <p id={`${id}-error`} style={{ color: '#c0392b' }}>
                    An email needs an @.
                </p>
            )}
            <small>Base id: {id}</small>
        </form>
    );
}

export default function App() {
    return <SignupForm />;
}

在邮箱字段里输入一个不含 @ 的词：错误提示会出现，并且输入框的 aria-describedby 指向它，这样当输入框获得焦点时，屏幕阅读器会读出这条错误。在 App 中渲染两次 <SignupForm />，每一份都会得到自己的基础 id。

不能用作列表的 key

key 和 id 解决的是不同的问题。key 告诉 React 在多次渲染之间哪一项对应哪一项，所以它必须来自数据。useId 为每个组件实例提供一个 id，而且你不能在 map 里调用它。

// Wrong: breaks the rules of hooks, and the key is unrelated to the item
{todos.map((todo) => <Todo key={useId()} todo={todo} />)}

// Right: the key comes from the data
{todos.map((todo) => <Todo key={todo.id} todo={todo} />)}

如果你的数据没有 id，就在创建这一项的时候生成一个（在添加它的事件处理函数中调用 crypto.randomUUID()），而不是在渲染期间生成。列表与 key 一页解释了为什么 key 必须始终跟随它对应的那一项。

同一页面上有多个 React 根

如果同一个页面上渲染了两个独立的 React 应用，它们的 id 可能会冲突。给每个根加一个前缀：

createRoot(document.getElementById('cart'), { identifierPrefix: 'cart-' });
createRoot(document.getElementById('chat'), { identifierPrefix: 'chat-' });

在服务端渲染时，把同一个 identifierPrefix 同时传给服务端渲染器和 hydrateRoot，这样两边生成的 id 才会一致。

常见错误

在服务器和浏览器中渲染不同的树。 useId 依赖组件的位置，所以如果在某个字段上方有 typeof window === 'undefined' ? <A /> : <B /> 这样的分支，两次渲染中的 id 就可能错位。hydration 期间保持树结构一致，等它完成后再在 Effect 中切换。

通过 id 查找元素。 document.getElementById(id) 能用，但 ref 才是 React 访问 DOM 节点的方式，而且根本不需要 id。

把它当作随机值使用。 这个 id 在应用内是唯一的，但不是随机的，可以根据树结构推算出来。不要把它用作安全令牌、缓存键，或任何跨会话保存的东西。

什么时候使用

只要可复用的组件需要 id 属性，就使用 useId：由一个会多次使用的组件构成的表单字段，通过 aria-describedby 关联的提示框，带 aria-labelledby 的对话框，带 aria-controls 的选项卡。如果 id 只是用来把 label 和输入框关联起来，也可以不用 id，直接把输入框嵌套在 label 里面（<label>Name <input /></label>）；当元素无法嵌套时再用 useId。