| name | code-style-react |
| description | React 组件通用编码规范。编写、审查或重构 React 组件（.tsx）时使用，尤其涉及组件定义（export function + IXxxProps）、design/ui 分层、与 DI/Observable 桥接（useDependency/useObservable/useObservableRef）、自定义 hooks、Tailwind + cva + cn() 样式方案、语义色 token、组件注册插槽（ComponentManager/IUIPartsService/connectInjector）、i18n（LocaleService.t）时。可独立使用；与 code-style-architecture 搭配效果最佳。 |
通用 React 组件规范
概述
核心心智：组件是 Observable 的渲染函数——业务逻辑在 service，组件只做「DI 取服务 → 订阅流 → 渲染 → 派发命令」。
关键规则速查 (违反必改)
组件定义
export interface IRuleFormProps {
ruleId: string;
onClose?: () => void;
}
export function RuleForm({ ruleId, onClose }: IRuleFormProps) { ... }
- 视图组件用
export function 具名声明（不用箭头函数常量），named export，不用 default export
- Props 接口
IXxxProps，export interface 定义在组件文件顶部
- 默认值走参数解构默认值，不用
defaultProps
- React 19 风格：不用
forwardRef（ref 作为普通 prop），设计组件用 React.ComponentProps<'button'> & VariantProps<...> 交叉类型
- 视图组件不做
memo 包裹——靠 Observable 精确订阅控制刷新
三层组件体系
design 包（纯展示，无业务无 DI） → ui 包（宿主基座：workbench/插槽/菜单） → *-ui 业务包（views/）
状态与逻辑
- 取服务：
useDependency(IXxxService)；订阅流：useObservable(service.xxx$, default)
- 只读最新值不触发渲染：
useObservableRef
- 自定义 hooks 放
views/hooks/，命名 useXxx，内部只做「DI + Observable → 派生值」
- 写操作走
commandService.executeCommand(XxxCommand.id, params)；纯 UI 编排（弹菜单、设目标）走轻量 service；组件不直接改数据
样式
- Tailwind 原子类 + cva 变体 +
cn() 合并；无 CSS Modules / CSS-in-JS
- 颜色只用语义 token 类（如
bg-surface / text-content / border-line），禁止硬编码色值与 dark: 双写切色（颜色随主题 CSS 变量自动切换）
cn() 条件类名用对象语法 { 'class': cond }；静态类名放第一个参数- 仅「运行时计算的像素值」用内联
style，且提为模块常量
i18n
- 文案禁止硬编码：
localeService.t('<包名>.<分组>.<键>')
- locale 文件按语言拆分
src/locale/{zh-CN,en-US,...}.ts，顶层键 = 包名
章节索引 — 按需打开
| # | 主题 | 文件 | 何时查阅 |
|---|
| 1 | 组件定义与文件组织 | references/01-component.md | 新建组件、决定放哪层时 |
| 2 | 状态·DI·hooks | references/02-state-di.md | 桥接 Observable、写自定义 hook、判断逻辑归属时 |
| 3 | 样式方案 | references/03-styling.md | 写类名、建 cva 变体、处理主题色时 |
| 4 | 组件注册插槽与 i18n | references/04-slots-i18n.md | 插件向宿主注入 UI、取文案时 |
