specsfy-specialist-react

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React

Quando usar

适用场景

Acionar quando o pedido envolve componente, hook, context, formulário, lista, efeito ou estado em React puro (CRA, Vite, RSC-agnóstico).
Acionar também para revisar por que um componente rerenderiza demais, por que um efeito roda em loop, ou como decidir onde um estado deve viver.
Não acionar para decisão de Server vs Client Component, cache de dados ou roteamento de framework; usar
```
$specsfy-specialist-nextjs
```
nesse caso.
Não acionar para escolher ou adaptar uma biblioteca de componentes visuais prontos; usar
```
$specsfy-specialist-react-ui-components
```
com
```
$specsfy-specialist-ui-design
```
para isso.
Combinar com
```
$specsfy-specialist-typescript
```
quando o componente expõe props públicas ou modela estado com union discriminada, e com
```
$specsfy-specialist-web-accessibility
```
para auditoria aprofundada de teclado e leitor de tela.

当需求涉及纯React（CRA、Vite、RSC无关）中的组件、hook、context、表单、列表、副作用或状态时触发。
当需要排查组件重复渲染原因、副作用循环问题，或确定状态应归属位置时也可触发。
请勿用于服务端组件与客户端组件的抉择、数据缓存或框架路由场景；此类情况请使用
```
$specsfy-specialist-nextjs
```
。
请勿用于选择或适配现成视觉组件库；此类情况请结合
```
$specsfy-specialist-react-ui-components
```
与
```
$specsfy-specialist-ui-design
```
。
当组件对外暴露props或使用判别联合类型定义状态时，可结合
```
$specsfy-specialist-typescript
```
；若需深入进行键盘与屏幕阅读器审计，可结合
```
$specsfy-specialist-web-accessibility
```
。

Fluxo

流程

Para uma tela ou formulário, ler
```
INTERFACE.md
```
e a seção de interface da spec antes do código. Confirmar telas, fluxo de informação, campos, validações, padrão de abertura e estados. Se o material não existir, retornar ao
```
$specsfy-specialist-ux-design
```
e
```
$specsfy-specialist-ui-design
```
; não trocar uma interface pedida por endpoint ou componente vazio.
Confirmar versão do React, renderer, framework (se houver), convenções do projeto e estratégia de testes já em uso. Quando a tela usar shadcn/ui, identificar antes a base de primitives instalada, seguindo
```
$specsfy-specialist-shadcn-ui
```
; nunca deduzir Radix ou Base UI pela aparência do componente. Se
```
.specsfy/STACK.md
```
não declarar React ou o projeto não tiver essa dependência, não inicie esta implementação: encaminhe ao especialista da stack observada.
Modelar os estados visíveis (nominal, loading, empty, error, stale, optimistic), os eventos que os produzem e quem é o dono de cada dado.
Projetar a árvore de componentes com responsabilidades e props pequenas; preferir composição (
```
children
```
, slots) a um componente com dezenas de flags booleanas.
Manter cada estado no dono mais próximo capaz de resolvê-lo; derivar valores durante o render em vez de sincronizar com
```
useEffect
```
.
Usar effects apenas para sincronizar com um sistema externo (DOM, subscription, rede, storage) — nunca para computar algo a partir de props e state já disponíveis.
Implementar semântica HTML e navegação por teclado antes do acabamento visual; então cobrir com teste de comportamento observável.
Medir performance somente quando houver sintoma real (profiler, métrica de produção); então memoizar ou dividir o componente com medição registrada, não por precaução.
Registrar em
```
INTERFACE.md
```
cada bloco criado, alterado ou reaproveitado: responsabilidade, arquivo, props, eventos, estados, acessibilidade e telas consumidoras.

对于页面或表单，先阅读
```
INTERFACE.md
```
和需求文档中的界面部分，再查看代码。确认页面、信息流、字段、验证规则、打开模式及状态。若相关材料不存在，转交
```
$specsfy-specialist-ux-design
```
与
```
$specsfy-specialist-ui-design
```
；不得将需求的界面替换为接口或空组件。
确认React版本、渲染器、框架（若有）、项目约定及已在使用的测试策略。若页面使用shadcn/ui，需先识别已安装的原始组件基础库，遵循
```
$specsfy-specialist-shadcn-ui
```
规范；绝不能通过组件外观推断使用Radix或Base UI。若
```
.specsfy/STACK.md
```
未声明React或项目无此依赖，请勿启动本次开发：转交至对应技术栈的专家处理。
定义可见状态（正常、加载、空数据、错误、过期、乐观更新）、触发这些状态的事件，以及各数据的归属方。
设计职责单一、props精简的组件树；优先使用组合（
```
children
```
、插槽）而非带有数十个布尔标记的单一组件。
将每个状态保留在最接近且能处理它的归属方；在渲染过程中推导值，而非通过
```
useEffect
```
同步。
仅在与外部系统（DOM、订阅、网络、存储）同步时使用effects——绝不能用于从已有props和state中计算内容。
在完成视觉样式前，先实现HTML语义化与键盘导航；然后针对可观察行为编写测试。
仅当出现实际性能问题（性能分析器、生产环境指标）时才进行性能测量；然后基于记录的测量结果进行 memoize 或拆分组件，而非提前预防。
在
```
INTERFACE.md
```
中记录每个创建、修改或复用的模块：职责、文件路径、props、事件、状态、可访问性及使用该模块的页面。

Padrões

规范

Preferir composição a um componente genérico com muitas props de configuração; dividir quando a árvore de decisão interna cresce.
Em Laravel com React, usar shadcn/ui para primitives e ReUI para composições gratuitas. Página e rota compõem blocos React; grade, formulário, filtros, overlays e cartões reutilizáveis são componentes próprios e documentados em
```
INTERFACE.md
```
.
Nunca copiar uma prop para
```
state
```
só para "guardar o valor inicial"; isso cria dessincronia — leia a prop diretamente ou derive durante o render.
Não usar
```
useEffect
```
para computar um valor derivável de props/state existentes; use uma variável comum ou
```
useMemo
```
quando o cálculo for caro.
Tornar loading, empty, error, stale e success estados explícitos da UI, não branches implícitos de um único booleano
```
loading
```
.
Usar
```
key
```
estável e vinda dos dados (id) em listas; nunca o índice do array quando a ordem pode mudar, item pode ser removido ou reordenado.
Isolar cada
```
Context.Provider
```
pela frequência de mudança e responsabilidade — um context que muda a cada tecla não deve envolver a árvore inteira.
Não memoizar (
```
memo
```
/
```
useMemo
```
/
```
useCallback
```
) sem medição prévia; memoização tem custo de comparação e só compensa com renders caros ou comprovadamente frequentes.
Testar pelo comportamento observável pelo usuário (texto, papel, estado), nunca por detalhes de implementação de hooks internos.

优先使用组合而非带有大量配置props的通用组件；当内部决策逻辑树过于复杂时进行拆分。
在Laravel与React结合的项目中，使用shadcn/ui作为原始组件库，使用ReUI作为免费组合组件。页面与路由组合React模块；网格、表单、过滤器、浮层及卡片等可复用组件为自定义组件，并在
```
INTERFACE.md
```
中记录文档。
绝不能仅为“保存初始值”而将props复制到
```
state
```
中——这会导致数据不一致；直接读取props或在渲染时推导值。
请勿使用
```
useEffect
```
从已有props/state中推导值；若计算成本较高，使用普通变量或
```
useMemo
```
。
将加载、空数据、错误、过期及成功状态设为UI的显式状态，而非单一布尔值
```
loading
```
的隐式分支。
在列表中使用来自数据的稳定
```
key
```
（如id）；当列表顺序可能变化、条目可能被删除或重新排序时，绝不能使用数组索引作为key。
根据变更频率与职责隔离每个
```
Context.Provider
```
——每次按键都会变更的context不应包裹整个组件树。
若无预先测量，请勿进行 memoize（
```
memo
```
/
```
useMemo
```
/
```
useCallback
```
）；memoization存在比较成本，仅在渲染成本高或已确认渲染频繁时才值得使用。
针对用户可观察的行为（文本、角色、状态）编写测试，而非针对内部hooks的实现细节。

Antipadrões

反模式

Efeito que sincroniza estado local com uma prop (
```
useEffect(() => setX(prop), [prop])
```
) — sintoma de estado duplicado; a fonte da verdade já é a prop.
Cadeia de effects que dispara outro effect via mudança de state ("effect chain") — geralmente colapsa em um único handler de evento ou em cálculo direto durante o render.
```
useEffect
```
sem array de dependências completo, "silenciado" com
```
// eslint-disable
```
— esconde bug de closure obsoleta em vez de resolvê-lo.
Context único guardando todo o estado global da aplicação ("god context") — qualquer mudança rerenderiza toda a árvore; prefira contexts menores ou uma biblioteca de estado dedicada quando o grafo de dependências crescer.
Confundir este escopo com o de
```
$specsfy-specialist-nextjs
```
: adicionar
```
"use client"
```
em cascata para "resolver" um erro de hook, em vez de mover a interatividade para o componente folha correto.

使用副作用将本地状态与props同步（
```
useEffect(() => setX(prop), [prop])
```
）——这是状态重复的表现；数据源应为props本身。
通过状态变更触发其他副作用的副作用链（"effect chain"）——通常可合并为单个事件处理器或直接在渲染时计算。
```
useEffect
```
缺少完整的依赖数组，并用
```
// eslint-disable
```
屏蔽警告——这会隐藏过时闭包的bug，而非解决问题。
单个context存储应用所有全局状态（"god context"）——任何变更都会导致整个组件树重新渲染；当依赖关系图复杂时，优先使用更小的context或专用状态管理库。
将本技能的范围与
```
$specsfy-specialist-nextjs
```
混淆：为“解决”hook错误而批量添加
```
"use client"
```
，而非将交互逻辑移至正确的叶子组件。

Validação

验证

Percorrer a superfície alterada inteira por teclado e testar com leitor de tela quando houver papel, foco ou anúncio novo.
Escrever testes para cada estado modelado no passo 2 do Fluxo (nominal, loading, empty, error, stale, optimistic) e para a recuperação de erro.
Checar o console por warnings do React (chaves, hooks fora de ordem, atualização de estado após unmount) e por avisos de hydration quando houver SSR.
Rodar profiling ou bundle analysis somente quando uma hipótese concreta de performance existir; anexar a medição antes/depois.
Não declarar um componente "acessível" ou "performático" sem a comprovação acima; linguagem absoluta sem prova é proibida.

当出现新的角色、焦点或提示时，通过键盘遍历所有变更区域并使用屏幕阅读器测试。
为流程步骤2中定义的每个状态（正常、加载、空数据、错误、过期、乐观更新）及错误恢复场景编写测试。
检查控制台中的React警告（key、hooks顺序错误、卸载后更新状态）及SSR时的hydration警告。
仅当有明确的性能假设时才进行性能分析或包体积分析；附上分析前后的测量数据。
若无上述验证依据，不得宣称组件“可访问”或“高性能”；禁止使用无依据的绝对表述。

specsfy-specialist-react

Original

Translation

React

React

Quando usar

适用场景

Fluxo

流程

Padrões

规范

Antipadrões

反模式

Validação

验证

Skills relacionadas

相关技能