## 资源脚本/ 验证组件.sh 参考文献/ 组件模式.md # 组件架构此技能将指导您使用 GoodVibes 精度和分析工具设计和实现 UI 组件。在构建具有适当组合、状态管理和性能优化的 React、Vue 或 Svelte 组件时使用此工作流程。 ## 何时使用此技能在以下情况下加载此技能： * 构建新的UI组件或组件库 * 重构组件层次结构或组合模式 * 优化组件渲染性能 * 组织组件文件结构 * 实现设计系统或原子设计模式 * 组件框架之间的迁移 * 审查组件架构的可维护性触发短语：“构建组件”、“创建 UI”、“组件结构”、“渲染优化”、“状态提升”、“组件组合”。 ## 核心工作流程 ### 第一阶段：发现在构建组件之前，请了解代码库中的现有模式。 #### 步骤1.1：映射组件结构使用“discover”查找所有组件文件并了解组织模式。发现：查询： - id：react_components 类型：全局模式：[“**/*.tsx”，“**/*.jsx”] - id：vue_components 类型：全局模式：[“**/*.vue”] - ID：svelte_components 类型：全局模式：[“**/*.svelte”] 详细程度：files_only **这揭示了什么：** * 使用的框架（React、Vue、Svelte 或混合） * 组件文件组织（基于特征、原子、平面） * 命名约定（PascalCase、kebab-case） * 文件共置模式（带有测试、样式的组件） #### 步骤 1.2：分析组件模式使用“discover”来查找组合模式、状态管理和样式方法。发现：查询： - id：composition_patterns 类型：grep 模式：“(children|render|slot|as\\s*=)” glob: "**/*.{tsx,jsx,vue,svelte}" - ID：状态管理类型：grep 模式：“（useState | useReducer |反应性|可写| createSignal）” glob: "**/*.{ts,tsx,js,jsx,vue,svelte}" - ID：造型方法类型：grep 模式：“(className|styled|css|tw`|@apply)” glob: "**/*.{tsx,jsx,vue,svelte}" - id: 性能_钩子类型：grep 模式：“(useMemo|useCallback|memo|计算|\\$:)” glob: "**/*.{ts,tsx,js,jsx,vue,svelte}" 详细程度：files_only **这揭示了什么：** * 构图策略（儿童道具、渲染道具、插槽） * 状态管理模式（钩子、存储、信号） * 样式解决方案（CSS 模块、Tailwind、样式组件） * 使用的性能优化技术 #### 步骤 1.3：提取组件符号使用带有符号提取的“ precision_read”来了解组件导出。精度读取：文件： - path: "src/components/Button/index.tsx" # 示例组件摘录：符号 symbol_filter：[“功能”，“类”，“接口”，“类型”] 详细程度：标准 **这揭示了什么：** * 组件导出模式（命名与默认） * Props接口定义 * 辅助函数和钩子 * 类型定义和泛型 #### 步骤 1.4：读取代表性组件阅读 2-3 个结构良好的组件以了解实现模式。精度读取：文件： - 路径：“src/components/Button/Button.tsx” 摘录：内容 - 路径：“src/components/Form/Form.tsx” 摘录：内容输出：每个项目的最大数量：100 详细程度：标准 ### 第二阶段：决策 #### 步骤2.1：选择组件组织模式请参阅“references/component-patterns.md”以获取组织决策树。 **常见模式：** * **原子设计** \- 原子、分子、有机体、模板、页面 * **基于功能** \- 按功能/域分组 * **Flat** \- 所有组件都位于单个目录中 * **混合** \- 共享组件 + 功能组件 **决定因素：** * 团队规模（更大的团队 -> 更多的结构） * 应用程序复杂性（复杂 -> 基于功能） *设计系统存在（是->原子设计） * 组件可重用性（高->shared/ui目录） #### 步骤 2.2：选择构图模式详细比较请参见“references/component-patterns.md”。 **图案选择指南：** 图案|使用时间 |框架支持 ---|---|--- 儿童道具|简单的包装组件 | React、Vue（插槽）、Svelte 渲染道具 |动态渲染逻辑|反应（遗留）复合成分|相关组件共享状态 |反应、Vue、Svelte 高阶组件 |跨领域关注点 |反应（遗留）挂钩/组合件 |逻辑复用 |反应、Vue 3、Svelte 老虎机|基于模板的合成 | Vue，苗条 **现代推荐：** * **React** ：Hooks + 子属性（避免 HOC/渲染属性） * **Vue** ：组合 API + 插槽 * **Svelte**：动作+插槽 #### 步骤2.3：选择状态管理策略 **组件级状态：** * 将本地状态用于仅涉及 UI 的问题（模态、表单、切换） * 仅当兄弟姐妹需要共享时才解除状态 * 导出状态而不是复制 **应用程序级状态：** * **React** ：上下文 + useReducer、Zustand、Jotai * **Vue** ：Pinia (Vue 3)、Vuex (Vue 2) * **Svelte** ：商店、上下文 API 有关状态管理决策树，请参阅“references/component-patterns.md”。 ### 第三阶段：实施 #### 步骤 3.1：定义组件接口从 props 的 TypeScript 接口开始。 **反应示例：** 从'react'导入{ReactNode}；接口 ButtonProps { /** 按钮内容 */ 孩子们：ReactNode； /** 视觉风格变体 */ 变体？： '主要' | '次要' | '幽灵' | '危险'; /** 尺寸预设 */ 尺寸？： 'sm' | 'md' | 'lg'; /** 加载状态 */ 正在加载？：布尔值； /** 禁用状态 */ 禁用？：布尔值； /** 点击处理程序 */ onClick?: () => void; /** 附加 CSS 类 */ 类名？：字符串； } **最佳实践：** * 使用 JSDoc 注释记录所有 props * 对变体道具使用可区分的联合 * 使用“?”明确可选属性 * 提供合理的默认值 * 避免“任何”类型 **Vue 3 示例：** 从“vue”导入{defineComponent，PropType}；导出默认定义组件（{ 道具：{ 变体：{ 类型：字符串作为 PropType<'primary' | '次要' | '幽灵' | '危险'>, 默认值：“主要”， }, 尺寸：{ 类型：字符串作为 PropType<'sm' | 'md' | 'lg'>, 默认值：'md'， }, 正在加载：{ 类型：布尔值，默认值：假， }, 禁用：{ 类型：布尔值，默认值：假， }, }, }); **精简示例：** // Button.svelte (Svelte 4) <脚本语言=“ts”> 导出 let 变体：'primary' | '次要' | '幽灵' | '危险' = '主要'; 导出让大小：'sm' | 'md' | 'lg' = 'md'; 导出让 isLoading = false; 导出让禁用=假; // Button.svelte（Svelte 5 - 使用 $props rune） <脚本语言=“ts”> 让 { 变体 = 'primary'，size = 'md'，isLoading = false，disabled = false }: { 变体？： '主要' | '次要' | '幽灵' | '危险'; 尺寸？： 'sm' | 'md' | 'lg'; 正在加载？：布尔值；禁用？：布尔值； } = $props(); #### 步骤 3.2：实现组件逻辑遵循特定于框架的组件实现模式。 **与组合物反应：** 从'react'导入{forwardRef}；从 '@/lib/utils' 导入 { cn }；从'./Spinner'导入{Spinner}； const 按钮变体 = { 变体：{ 主要：'bg-blue-600悬停：bg-blue-700文本白色'，次要：'bg-gray-200悬停：bg-gray-300 text-gray-900'，幽灵：'悬停：bg-gray-100 text-gray-700'，危险：'bg-red-600悬停：bg-red-700文本-白色'， }, 尺寸：{ sm: 'px-3 py-1.5 文本-sm', md: 'px-4 py-2 文本库', lg: 'px-6 py-3 文本-lg', }, }; 导出 const Button =forwardRef( （ { 孩子们，变体='主要'，大小='md', 正在加载=假，禁用=假，类名, ...道具 }, 参考 ) => { 返回（ <按钮参考={参考} 类名={cn( 'inline-flex items-center justify-center rounded-md font-medium', '过渡颜色焦点可见：轮廓无焦点可见：环2'， '禁用：指针事件-无禁用：opacity-50'， ButtonVariants.variant[变体], 按钮变体.尺寸[尺寸], 类名 )} 禁用={禁用||正在加载} aria-busy={正在加载} {...道具} > {正在加载？（ <> 正在加载... ) : ( 儿童 )} ）； } ）； Button.displayName = '按钮'; **关键模式：** * 使用 `forwardRef` 公开 DOM 引用 * 传播 `...props` 以获得灵活性 * 用实用函数组成类名 * 处理加载/禁用状态 * 添加 ARIA 属性以实现可访问性 #### 步骤 3.3：组织组件文件创建具有正确文件结构的组件目录。 **标准结构：** 组件/ 按钮/ Button.tsx # 组件实现 Button.test.tsx # 单元测试 Button.stories.tsx # 故事书故事（如果使用） index.tsx # 桶导出 types.ts # 类型定义（如果复杂） **使用精密工具实施：** 精度写入：文件： - 路径：“src/components/Button/Button.tsx” 内容： | 从'react'导入{forwardRef}； // ... [完整实现] - 路径：“src/components/Button/index.tsx” 内容： | 从 './Button' 导出 { Button }；从 './Button' 导出类型 { ButtonProps }； - 路径：“src/components/Button/Button.test.tsx” 内容： | 从'@testing-library/react'导入{渲染，屏幕}；从 './Button' 导入 { Button }； // ... [测试用例] 详细程度：count_only ### 第 4 阶段：状态管理 #### 步骤 4.1：确定状态范围 **本地状态（仅限组件）：** * 表单输入 * 模态打开/关闭 * 下拉菜单展开/折叠 * 加载状态 **解除状态（父管理）：** * 跨字段表单验证 * 多步向导状态 * 具有单开行为的手风琴 **全局状态（应用程序级别）：** * 用户认证 * 主题偏好 * 购物车 * 通知 #### 步骤 4.2：实现状态模式 **反应 - 当地状态：** 从'react'导入{useState}；接口搜索结果{ id：字符串；标题：字符串；描述：字符串； } 函数搜索输入（）{ const [查询，setQuery] = useState(''); const [结果，setResults] = useState([]); const handleSearch = async () => { const data = wait fetch(`/api/search?q=${encodeURIComponent(query)}`); setResults(等待 data.json()); }; 返回（ <> setQuery(e.target.value)} /> ）； } **反应 - 解除状态：** 函数搜索页面() { const [查询，setQuery] = useState(''); const [结果，setResults] = useState([]); 返回（ <> <搜索结果结果={结果} /> ）； } **反应 - 派生状态：** 接口项{ id：字符串；类别：字符串；名称：字符串； } 接口 FilteredListProps { 项目：项目[]；过滤器：字符串； } 函数 FilteredList({ items, 过滤器 }: FilteredListProps) { // 不要将过滤后的项目存储在状态中 - 派生它们 const FilteredItems = items.filter(item => item.category === 过滤器); 返回

{item.name}

; } #### 步骤 4.3：避免支柱钻井 **使用 Context 进行深度嵌套的 props：** 从 'react' 导入 { createContext, useContext }; const ThemeContext = createContext({ theme: 'light',toggleTheme: () => {} }); 接口 ThemeProviderProps { 孩子们：ReactNode； } 导出函数 ThemeProvider({ Children }: ThemeProviderProps) { const [主题，setTheme] = useState('light'); consttoggleTheme = () => setTheme(t => t === 'light' ? 'dark' : 'light'); 返回（ {孩子} ）； } 导出 const useTheme = () => useContext(ThemeContext); ### 第 5 阶段：性能优化 #### 步骤 5.1：识别渲染问题使用分析工具来检测性能问题。 mcp__plugin_goodvibes_frontend-engine__trace_component_state：组件文件：“src/components/Dashboard.tsx” 目标组件：“仪表板” mcp__plugin_goodvibes_frontend-engine__analyze_render_triggers：组件文件：“src /组件/ ExpenseList.tsx” **这些揭示了什么：** * 组件不必要地重新渲染 * 状态更新触发级联渲染 * 每个父渲染的道具都会改变 #### 步骤 5.2：应用记忆化 **记住昂贵的计算：** 从 'react' 导入 { useMemo } ；接口数据项{ id：字符串； [键：字符串]：未知； } 接口数据表属性{ 数据：数据项[]；过滤器：记录<字符串，任意>； } 函数 DataTable({ 数据, 过滤器 }: DataTableProps) { const FilteredData = useMemo(() => { 返回 data.filter(item => matchesFilters(item,filters)); }, [数据, 过滤器]); return {/* 渲染filteredData */}

; } **记忆回调函数：** 从'react'导入{useCallback}；函数父级（）{ const [count, setCount] = useState(0); // 当计数改变时防止子进程重新渲染 const handleClick = useCallback(() => { onClick(); }, []); 返回 ; } **记忆组件：** 从“反应”导入{备忘录}；接口 ExpenseChildProps { 数据：数据项[]； } const ExpenseChild = memo(function ExpenseChild({ data }: ExpenseChildProps) { // 仅当数据改变时重新渲染 return

{/* 复杂渲染 */}

; }); #### 步骤 5.3：实施虚拟化对于大型列表，请使用虚拟化库。从'@tanstack/react-virtual'导入{useVirtualizer}；接口 VirtualListProps { 项目：T[]； } 函数 VirtualList({ items }: VirtualListProps) { constparentRef = useRef(null); const 虚拟化器 = useVirtualizer({ 计数：项目.长度， getScrollElement: () =>parentRef.current, 估计大小: () => 50, }); // 注意：此处可接受内联样式以进行虚拟化定位返回（

{virtualizer.getVirtualItems().map(virtualRow => (

{items[virtualRow.index].name}

))}

）； } #### 步骤 5.4：延迟加载组件 **反应延迟加载：** 从'react'导入{lazy, Suspense}; const HeavyComponent = lazy(() => import('./HeavyComponent')); 函数应用程序（）{ 返回（加载中...}> <重组件/> ）； } ### 第 6 阶段：无障碍 #### 步骤 6.1：语义 HTML 使用正确的 HTML 元素而不是 div。 // 不好

点我

// 好 #### 步骤 6.2：ARIA 属性为屏幕阅读器添加 ARIA 标签。接口 DialogProps { 是否打开：布尔值； onClose: () => void; 孩子们：ReactNode； } 函数 Dialog({ isOpen, onClose, Children }: DialogProps) { 返回（

对话框标题

{子项}

）； } #### 步骤 6.3：键盘导航确保所有交互元素均可通过键盘访问。函数下拉（）{ const [isOpen, setIsOpen] = useState(false); const handleKeyDown = (e: React.KeyboardEvent) => { if (e.key === 'Escape') setIsOpen(false); if (e.key === 'Enter' || e.key === ' ') setIsOpen(!isOpen); }; 返回（

<按钮 onClick={() => setIsOpen(!isOpen)} onKeyDown={handleKeyDown} aria-expanded={isOpen} aria-haspopup=“真” > 菜单 {isOpen && }

）； } #### 步骤 6.4：验证可访问性使用前端分析工具来检查可访问性。 mcp__plugin_goodvibes_frontend-engine__get_accessibility_tree：组件文件：“src/components/Dialog.tsx” ### 第 7 阶段：验证 #### 步骤 7.1：类型检查验证 TypeScript 编译。精度执行：命令： - cmd：“npm 运行类型检查” 期望：退出代码：0 冗长：最少 #### 步骤 7.2：运行组件验证脚本使用验证脚本来确保质量。 bash插件/goodvibes/skills/outcome/component-architecture/scripts/validate-components.sh。有关完整的验证套件，请参阅“scripts/validate-components.sh”。 #### 步骤 7.3：视觉回归测试如果使用 Storybook 或类似内容，请运行视觉测试。精度执行：命令： - cmd：“npm运行测试：视觉” 期望：退出代码：0 冗长：最少 ## 常见的反模式 **不要：** * 存储派生状态（从现有状态计算） * 直接改变 props 或 state * 使用索引作为动态列表的键 * 在渲染中创建新的对象/函数 * 跳过 prop 验证或 TypeScript 类型 * 使用“any”类型作为组件属性 * 混合表示和业务逻辑 * 忽略辅助功能（ARIA、键盘导航） * 过度优化（过早记忆） **做：** * 尽可能从 props 中获取状态 * 将 props 和 state 视为不可变 * 对列表项使用稳定、唯一的键 * 在渲染之外定义函数或使用`useCallback` * 使用 TypeScript 定义严格的 prop 类型 * 将容器（逻辑）与表示组件分开 * 为自定义组件添加ARIA属性 * 优化前测量（React DevTools Profiler） ## 快速参考 **发现阶段：** 发现：{查询：[组件，模式，状态，样式]，详细程度：files_only } precision_read: { files: [示例组件], extract: 符号 } **实施阶段：** precision_write：{ 文件：[Component.tsx，index.tsx，types.ts]，详细程度：count_only } **性能分析：** trace_component_state: { component_file: "src/...", target_component: "名称" } analyze_render_triggers: { component_file: "src/..." } **辅助功能检查：** get_accessibility_tree: { component_file: "src/..." } **验证阶段：** precision_exec: { 命令: [{ cmd: "npm run typecheck" }] } **实施后：** bash 脚本/validate-components.sh 。有关详细模式、框架比较和决策树，请参阅“references/component-patterns.md”。 ## 相关技能考虑使用这些补充性的 GoodVibes 技能： * **styling-system** \- 设计系统标记、主题架构和 CSS-in-JS 模式 * **状态管理** \- 全局状态模式、存储架构和数据流 * **测试策略** \- 组件测试、视觉回归和可访问性测试 * **性能审核** \- 捆绑分析、渲染分析和优化策略 * **可访问性审核** \- WCAG 合规性、屏幕阅读器测试和 ARIA 模式

组件架构

包含技能