react

React

使用此技能时，应结合当前文档以及本地应用的实际版本、框架和约定来做出 React 选择。

快照：[email protected] / [email protected]（于 2026-09-09 发布；截至 2026-10-01 仍是 npm latest）。如果版本不同，请从 source-map.md 刷新。

工作流

1. 修改代码前，先确认 React 的使用场景：
   • 阅读最近的项目指南文件和包清单。
   • 检查 react、react-dom、框架、构建工具、测试技术栈、TypeScript 和 ESLint 的已安装或声明版本。
   • 确定目标是仅客户端应用、SSR、由框架管理的应用、React Server Components 应用、React Native 应用、组件库还是迁移项目。
2. 在用户要求了解最新/当前行为、版本不明确或使用 React 19+ API 时，刷新文档：
   • 优先使用当前文档工具或官方文档页面。
   • 使用 source-map.md 获取已记录的最新版本快照和官方来源链接。
3. 加载与任务相关的参考文件：
   • core-react.md：组件设计、JSX、状态、Effect、Hooks、纯度、性能和测试判断。
   • react-19.md：React 19–19.3 API、升级、Actions、表单、Server Components、Server Functions、Compiler、View Transitions、Fragment refs 和发布渠道注意事项。
   • react-dom.md：createRoot、hydrateRoot、browser()、DOM 表单、水合、服务端/静态渲染、Trusted Types、资源和逃生通道。
4. 按照现有项目风格实现：
   • 当框架负责路由、数据获取、SSR、RSC 或水合时，优先使用框架原语，而不是直接调用 React DOM API。
   • 保留本地组件边界、无障碍约定、测试和样式模式。
   • 避免引入仅 React 19.3 可用或仅 canary 可用的 API，除非应用依赖支持这些 API。
5. 验证范围最小但有意义的部分：
   • 运行项目相关的类型检查、lint、测试、构建、story 或浏览器验证命令。
   • 对于可见的 UI 更改，在可行时检查实际屏幕状态。
   • 报告无法运行的验证项。

React 判断

• 保持渲染纯粹且幂等。渲染期间不要读取时间、随机值、仅限浏览器的全局变量，也不要修改非本地值，除非该值经过安全隔离且可重复。
• 如果某个值可由 props 或状态计算得出，就在渲染期间计算。不要只为镜像另一个值而添加状态和 Effect。
• 仅使用 Effect 与外部系统同步，例如 DOM、订阅、计时器、命令式组件、分析工具或非框架的数据获取。
• 保持 Effect 依赖项准确。通过将值移出组件，或放入 Effect/Event 边界，来证明该值不是响应式的，而不是禁用 linter。
• 将由用户操作触发的副作用放在事件处理器或 Actions 中。将由渲染触发的外部同步放在 Effect 中。
• 优先使用本地状态。仅当多个组件需要协调时才提升状态。复杂转换使用 reducers，外部存储使用 useSyncExternalStore。
• 在 React 19.3 SSR 中，对于无法生成匹配 HTML 的 Client Components，优先使用 react-dom 中的 use(browser())，而不是 typeof window 或挂载状态 Effect。
• 将 <ViewTransition> 视为 Transition/Suspense 动画边界。不要为 React 管理的更新调用浏览器的 startViewTransition API。
• 除非任务明确是在构建框架基础设施，否则将 Server Components、Server Functions 以及 React DOM 服务端/静态 API 视为框架集成范畴。
• 除非项目明确使用这些渠道，否则稳定版应用应视 canary 和 experimental 文档为不可用。