2025年8月20日中文

探索 React 的 experimental_useOpaqueIdentifier 在组件中生成唯一 ID 的强大功能。了解它的工作原理、何时使用以及它的优势。

React experimental_useOpaqueIdentifier：在 React 组件中生成唯一 ID

React 不断发展的生态系统不断推出旨在改善开发者体验和提高应用程序性能的新功能。其中一项实验性新增功能是 experimental_useOpaqueIdentifier。此 Hook 提供了一种简单而高效的方式，可在 React 组件中生成唯一的、不透明的标识符。这篇博文深入探讨了对这个 Hook 的理解、它的用途、用例，以及它如何为构建健壮且可访问的 React 应用程序做出贡献。

什么是 `experimental_useOpaqueIdentifier`？

experimental_useOpaqueIdentifier 是一个 React Hook，旨在生成一个唯一的字符串，保证在同一组件中多次调用该 Hook 时都是唯一的。它对于需要将元素与唯一 ID 关联的场景特别有用，尤其是在辅助功能或测试等上下文中。标识符的“不透明”性质意味着，虽然保证它是唯一的，但不应依赖于其特定格式或结构。其主要目的是提供一种可靠的生成唯一键的方法，而无需开发者管理自己的 ID 生成逻辑。

重要提示： 此 Hook 当前被标记为实验性，这意味着其 API 和行为可能会在未来的 React 版本中发生更改。在生产环境中谨慎使用它，并准备好在必要时调整你的代码。

为什么在 React 中使用唯一标识符？

在 React 开发中，唯一标识符至关重要，原因如下：

可访问性 (ARIA)： 许多 ARIA 属性，例如 aria-labelledby 或 aria-describedby，都需要使用元素的 ID 将其与另一个元素相关联。使用唯一 ID 可确保辅助技术可以正确解释元素之间的关系，从而使你的应用程序对残疾用户更具可访问性。例如，在模态窗口中，你可能会使用 experimental_useOpaqueIdentifier 为模态窗口的标题生成一个唯一 ID，然后在模态容器上使用 aria-labelledby 将其与标题相关联。
测试： 编写自动化测试时，尤其是在端到端测试中，可以使用唯一 ID 来定位特定元素以进行交互或断言。这使得测试更加可靠，并且不易因组件结构的更改而中断。例如，你可以使用 experimental_useOpaqueIdentifier 生成的 ID 来定位复杂表单中的特定按钮。
服务器端渲染 (SSR) 和水合： 在服务器上渲染组件时，重要的是生成的 HTML 与在水合期间将在客户端上渲染的 HTML 相匹配。使用一致的方法在两种环境中生成唯一 ID 有助于确保平滑的水合过程，并避免潜在的不匹配或警告。experimental_useOpaqueIdentifier 旨在在 SSR 环境中正常工作。
避免键冲突： 虽然 React 的 key prop 主要用于优化列表渲染，但唯一 ID 也可以在处理动态生成的元素或组件时，在避免命名冲突方面发挥作用。

如何使用 `experimental_useOpaqueIdentifier`

用法很简单：

            import { experimental_useOpaqueIdentifier as useOpaqueIdentifier } from 'react';

function MyComponent() {
  const uniqueId = useOpaqueIdentifier();

  return (
    <div id={uniqueId}>
      <p>This element has a unique ID.</p>
    </div>
  );
}

在此示例中，在 MyComponent 组件中调用 useOpaqueIdentifier()。它返回一个唯一字符串，该字符串被分配给 <div> 元素的 id 属性。MyComponent 的每个实例都将具有不同的唯一 ID。

实际示例和用例

1. 可访问的模态对话框

让我们使用 experimental_useOpaqueIdentifier 创建一个可访问的模态对话框：

            import { experimental_useOpaqueIdentifier as useOpaqueIdentifier } from 'react';

function Modal({ isOpen, onClose, title, children }) {
  const titleId = useOpaqueIdentifier();
  const modalId = useOpaqueIdentifier();

  if (!isOpen) {
    return null;
  }

  return (
    <div className="modal-overlay" onClick={onClose}>
      <div className="modal" onClick={(e) => e.stopPropagation()} role="dialog" aria-modal="true" aria-labelledby={titleId} id={modalId}>
        <h2 id={titleId}>{title}</h2>
        <div className="modal-content">{children}</div>
        <button onClick={onClose}>Close</button>
      </div>
    </div>
  );
}

export default Modal;

在这个例子中：

我们为模态窗口的标题 (titleId) 和模态容器本身 (modalId) 生成唯一 ID。
模态容器上的 aria-labelledby 属性设置为 titleId，从而建立模态窗口及其标题之间的可访问关系。
role="dialog" 和 aria-modal="true" 属性进一步增强了模态窗口对辅助技术的可访问性。

2. 用于测试元素的唯一 ID

考虑一个带有动态生成的列表项的组件：

            import { experimental_useOpaqueIdentifier as useOpaqueIdentifier } from 'react';

function DynamicList({ items }) {
  return (
    <ul>
      {items.map((item, index) => {
        const itemId = useOpaqueIdentifier();
        return <li key={index} id={itemId}>{item}</li>;
      })}
    </ul>
  );
}

export default DynamicList;

现在，在你的测试中，你可以使用它们的唯一 ID 轻松定位特定的列表项：

            // Example using Jest and React Testing Library
import { render, screen } from '@testing-library/react';
import DynamicList from './DynamicList';


describe('DynamicList', () => {
  it('should render each item with a unique ID', () => {
    const items = ['Item 1', 'Item 2', 'Item 3'];
    render(<DynamicList items={items} />);

    const listItem1 = screen.getByRole('listitem', {name: 'Item 1'});
    const listItem2 = screen.getByRole('listitem', {name: 'Item 2'});
    const listItem3 = screen.getByRole('listitem', {name: 'Item 3'});

    expect(listItem1).toHaveAttribute('id');
    expect(listItem2).toHaveAttribute('id');
    expect(listItem3).toHaveAttribute('id');

    expect(listItem1.id).not.toEqual(listItem2.id);
    expect(listItem1.id).not.toEqual(listItem3.id);
    expect(listItem2.id).not.toEqual(listItem3.id);
  });
});

这使得你的测试更能适应组件渲染逻辑的变化。

3. 避免 SSR 中的水合不匹配

使用服务器端渲染 (SSR) 时，确保服务器上生成的 HTML 与客户端上生成的 HTML 相匹配对于正确的水合至关重要。experimental_useOpaqueIdentifier 通过提供一种一致的方式在两种环境中生成唯一 ID 来帮助防止水合不匹配。

以下是一个简化的示例。正确的 SSR 设置涉及更复杂的服务器端渲染和客户端水合逻辑。

            // Component (shared between server and client)
import { experimental_useOpaqueIdentifier as useOpaqueIdentifier } from 'react';

function MyComponent() {
  const uniqueId = useOpaqueIdentifier();
  return <div id={uniqueId}>Hello from MyComponent</div>;
}

export default MyComponent;

            // Simplified Server-Side Rendering (Node.js with Express)
import express from 'express';
import { renderToString } from 'react-dom/server';
import MyComponent from './MyComponent';

const app = express();

app.get('/', (req, res) => {
  const renderedComponent = renderToString(<MyComponent />);
  const html = `
    <!DOCTYPE html>
    <html>
    <head>
      <title>SSR Example</title>
    </head>
    <body>
      <div id="root">${renderedComponent}</div>
      <script src="/client.js"></script>
    </body>
    </html>
  `;
  res.send(html);
});

            // Simplified Client-Side Hydration (client.js)
import React from 'react';
import ReactDOM from 'react-dom/client';
import MyComponent from './MyComponent';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<MyComponent />);

通过使用 experimental_useOpaqueIdentifier，服务器上生成的唯一 ID 将与客户端在水合期间生成的唯一 ID 相同，从而防止潜在的不匹配。

注意事项和最佳实践

实验性状态： 请注意，experimental_useOpaqueIdentifier 是实验性的，其 API 可能会发生变化。在你的决策过程中考虑这一点，并准备好在必要时调整你的代码。
不透明标识符： 不要依赖于生成的 ID 的特定格式或结构。将它们视为不透明的字符串，其唯一目的是提供唯一性。
性能： 虽然 experimental_useOpaqueIdentifier 旨在提高效率，但避免在代码的性能关键部分过度使用它。考虑你是否真的需要在每个实例中使用唯一 ID。
替代方案： 如果你需要更多地控制唯一 ID 的格式或结构，你可以考虑使用像 uuid 这样的库或实现你自己的 ID 生成逻辑。但是，experimental_useOpaqueIdentifier 为许多常见的用例提供了一个方便且内置的解决方案。
可访问性是关键： 使用唯一 ID 时，始终优先考虑可访问性，尤其是在使用 ARIA 属性时。确保你的组件结构合理且标记正确，以便为每个人提供良好的用户体验。

`experimental_useOpaqueIdentifier` 的替代方案

虽然 experimental_useOpaqueIdentifier 提供了一种方便的方式来生成唯一 ID，但还存在其他方法，每种方法都有其自身的权衡：

UUID 库 (例如，uuid)： 这些库根据 UUID 标准生成通用唯一标识符 (UUID)。UUID 保证在不同的系统和环境中都是唯一的。但是，它们通常比 experimental_useOpaqueIdentifier 生成的 ID 更长，这可能会在某些情况下影响性能。
自定义 ID 生成： 你可以使用计数器、随机数生成器或其他技术来实现你自己的 ID 生成逻辑。这使你可以最大程度地控制 ID 的格式和结构，但它也要求你管理确保唯一性和避免冲突的复杂性。
带有 ID 计数器的 Context API： 你可以创建一个 React Context 来管理全局 ID 计数器。然后，每个组件都可以使用上下文并递增计数器以生成唯一 ID。这种方法对于管理多个组件的 ID 可能很有用，但它需要仔细管理上下文和计数器，以避免竞争条件或其他问题。

最佳方法取决于你的具体要求和约束。选择 ID 生成方法时，请考虑以下因素：

唯一性要求： ID 在不同的系统和环境中保证唯一性有多重要？
性能： ID 生成对应用程序的性能有多大影响？
控制： 你需要对 ID 的格式和结构进行多少控制？
复杂性： 你愿意在你的代码库中引入多少复杂性？

对比表

这是一个对比表，重点介绍了不同 ID 生成方法的优缺点：

方法	优点	缺点
`experimental_useOpaqueIdentifier`	方便，内置，专为 React 设计，适用于 SSR	实验性，不透明 ID，API 可能会发生变化
UUID 库 (例如，`uuid`)	通用唯一，标准格式	ID 较长，可能影响性能
自定义 ID 生成	最大程度的控制，可自定义格式	需要仔细管理，可能发生冲突
带有 ID 计数器的 Context API	集中式 ID 管理，适用于跨组件 ID	需要仔细管理上下文和计数器，可能发生竞争条件

结论

experimental_useOpaqueIdentifier 提供了一种简单有效的方式来生成 React 组件中的唯一 ID，尤其适用于可访问性、测试和 SSR 场景。虽然其实验性状态需要谨慎，但它为构建更健壮和可维护的 React 应用程序提供了一个有价值的工具。通过了解其用途、用例和局限性，你可以利用其强大功能来增强你的开发工作流程并创造更好的用户体验。请记住随时关注 Hook 成熟后的任何 API 更改。

随着 React 生态系统的不断发展，采用像 experimental_useOpaqueIdentifier 这样的新功能对于保持领先地位和构建现代、可访问且高性能的 Web 应用程序至关重要。始终考虑不同方法之间的权衡，并选择最适合你的特定需求和约束的方法。

进一步学习

官方 React 文档
ARIA Authoring Practices Guide (APG)
React Testing Library 文档
探索 experimental_useOpaqueIdentifier 的 React 源代码，以更深入地了解其实现。