（3552期）Component Api Design – 系统化组件 API 设计方法论

系统化组件 API 设计方法论 专业级 React/Vue 组件 API 设计指南，涵盖 Props 设计、扩展方式、事件规范与文件结构，显著提升组件可维护性与团队协作效率 使用说明 核心用法 本技能提供系统化的前端组件设计方法论，主要服务于 React/Vue 组件的 API 设计与架构决策。核心使用场景包括：从零设计新组件、重构现有组件 API、判断组件拆分时机、制定 Props 命名规范等。 使用时需先判断用户所处阶段： 从零设计：先澄清使用场景（通用 vs 业务）、调用方、技术栈约束，区分通用组件（中性、可覆盖、不自取数据）与业务组件（可带语义、样式可写死）的设计原则 改造现有组件：先阅读代码定位问题（props 过多？职责不清？），再针对性给出改法 具体决策：直接给出场景化建议并附理由 Props 设计决策规则 | 场景 | 建议 ||------|------|| 能用 children 表达 | 不加 prop（如 <Button icon={<Icon />}> 优于 iconName 字符串） || 仅一处使用的特殊行为 | 调用方处理，不加 prop || 三处以上需要 | 加 prop || 两种状态 | 布尔（disabled） || 三种及以上 | 枚举（variant="primary\|secondary"） || 需外部控制 | 受控模式 value + onChange || 独立使用 | 非受控 defaultValue || 表单/按钮类 | 必须透传 HTML 属性（...rest）支持 aria-、data- | 文件结构规范 <150 行无子组件：单 .tsx 文件 有样式/子组件：目录化结构（index.tsx + 实现 + types.ts + 样式） 避免过早拆分，按需演进 显著优点 决策框架清晰：将模糊的「怎么设计好」转化为可执行的判断规则（3 处以上才加 prop、布尔 vs 枚举的量化标准） 反例驱动教学：每个正确做法配对错误示例，降低理解成本 场景化区分：通用组件与业务组件的双轨设计原则，避免一刀切 工程实践完整：涵盖 TypeScript 类型、受控/非受控、无障碍透传、文件结构等落地细节 潜在局限 框架偏向：示例以 React 为主，Vue 开发者需自行映射（slots ↔ render props，emit ↔ onXxx） 生态依赖：Radix/shadcn/Tailwind 的建议需根据实际项目调整 复杂度边界：对超大型组件库（如 Ant Design 级别）的跨组件依赖、版本兼容性等未深入涉及 适合人群 中级前端工程师：系统提升组件设计能力，摆脱「凭感觉设计」 技术负责人：建立团队组件规范，统一代码评审标准 全栈开发者：快速产出可维护的 UI 层代码 常规风险 过度设计陷阱：技能虽强调「职责单一」，但初学者可能在业务组件上套用通用组件的「绝对中性」原则，导致不必要的抽象层 透传滥用：盲目 ...rest 可能引入非预期的 HTML 属性，需配合类型约束（Omit<HTMLAttributes, 'customProp'>） 受控/非受控混淆：同时支持两种模式时，内部状态管理复杂度上升，需确保 useControllableState 类实现无 bug 原始说明 Designs reusable React/Vue component APIs and file structure for clarity, flexibility, and maintainability. Use when 设计组件, 组件API, 封装组件, component design, or...