# 组件架构斐流艺创项目的组件架构采用分层设计，将UI组件按功能和复用性进行分类，确保代码的可维护性和可扩展性。 ## 架构设计原则 ### 1. 分层架构项目采用清晰的分层架构设计： 1. **基础UI组件层** - 原子级UI组件 2. **业务组件层** - 功能性业务组件 3. **页面组件层** - 页面级组合组件 4. **布局组件层** - 全局布局组件 ### 2. 组件复用性 - **高内聚低耦合** - 组件职责单一，依赖关系清晰 - **可配置性** - 通过props提供灵活的配置选项 - **可组合性** - 支持组件嵌套和组合使用 ### 3. 设计系统 - **一致性** - 遵循统一的设计规范 - **可维护性** - 组件结构清晰，易于维护 - **可测试性** - 组件易于单元测试 ## 组件分类 ### 1. 基础UI组件基础UI组件位于 [src/components/ui/](file://c:\project\official\src\components\ui) 目录下，提供原子级的UI元素： ``` src/components/ui/ ├── alert.tsx ├── button.tsx ├── card.tsx ├── dialog.tsx ├── input.tsx ├── select.tsx └── ... ``` 这些组件基于 Radix UI 和 Shadcn/ui 构建，具有以下特点： - 无障碍访问支持 - 高度可定制的样式 - 类型安全的Props定义 - 一致的交互行为 ### 2. 业务组件业务组件位于各功能模块的 [components/](file://c:\project\official\src\features\docs\components) 目录下，提供特定业务功能： ``` src/features/docs/components/ ├── doc-card.tsx ├── doc-list.tsx ├── doc-sidebar.tsx └── ... src/features/links/components/ ├── link-card.tsx ├── link-list.tsx └── ... ``` 这些组件具有以下特点： - 与具体业务功能紧密相关 - 封装了业务逻辑 - 可在多个页面中复用 - 具有明确的业务语义 ### 3. 布局组件布局组件位于 [src/components/layout/](file://c:\project\official\src\components\layout) 目录下，负责页面整体布局： ``` src/components/layout/ ├── navbar/ ├── sidebar/ ├── footer.tsx ├── page-container.tsx └── ... ``` 这些组件具有以下特点： - 控制页面整体结构 - 提供响应式布局支持 - 管理全局状态和样式 - 与路由和导航相关 ### 4. MDX渲染组件 MDX渲染组件位于 [src/components/mdx/](file://c:\project\official\src\components\mdx) 目录下，专门用于渲染MDX内容： ``` src/components/mdx/ ├── mdx-components.ts ├── mdx-blockquote.tsx ├── mdx-code.tsx ├── mdx-img.tsx └── ... ``` 这些组件具有以下特点： - 专门处理Markdown内容渲染 - 支持代码高亮和语法解析 - 提供安全的内容渲染机制 - 支持自定义组件扩展 ## 组件目录结构项目采用功能驱动的组件组织方式： ``` src/ ├── components/ │ ├── ui/ - 基础UI组件 │ ├── layout/ - 布局组件 │ ├── mdx/ - MDX渲染组件 │ └── ... - 其他共享组件 └── features/ ├── docs/ │ └── components/ - 文档业务组件 └── ... - 其他功能模块组件 ``` ## 组件设计规范 ### 1. 命名规范 - 使用 PascalCase 命名组件文件和组件名 - 组件名应清晰表达其功能和用途 - 避免使用缩写，除非是广泛认知的缩写 ```typescript // 推荐 Button.tsx BlogCard.tsx UserProfile.tsx // 不推荐 btn.tsx BCard.tsx UP.tsx ``` ### 2. Props设计 - 使用 TypeScript 定义清晰的Props类型 - 提供合理的默认值 - 使用可选Props处理可选配置 - 避免Props嵌套过深 ```typescript interface ButtonProps { variant?: 'primary' | 'secondary' | 'ghost'; size?: 'sm' | 'md' | 'lg'; disabled?: boolean; onClick?: () => void; children: React.ReactNode; } ``` ### 3. 状态管理 - 优先使用受控组件 - 合理使用React Hooks管理组件状态 - 复杂状态考虑使用Zustand等状态管理库 - 避免在组件内部管理过多状态 ### 4. 样式处理 - 使用 Tailwind CSS 类名控制样式 - 避免内联样式 - 使用 clsx 或 class-variance-authority 管理条件类名 - 遵循设计系统的样式规范 ``typescript import { cn } from '@/lib/utils'; const Button: React.FC = ({ variant = 'primary', size = 'md', className, ...props }) => { return ( * ``` */ ``` ## 组件测试 ### 1. 测试策略 - 单元测试覆盖核心功能 - 快照测试确保UI一致性 - 集成测试验证组件交互 - 端到端测试验证完整流程 ### 2. 测试工具 - Vitest 用于单元测试 - React Testing Library 用于组件测试 - Jest 用于快照测试 ### 3. 测试要点 - Props变化的响应 - 用户交互的处理 - 边界条件的处理 - 错误状态的展示 ## 组件性能优化 ### 1. 渲染优化 - 使用 React.memo 避免不必要的重渲染 - 合理使用 useMemo 和 useCallback - 懒加载非关键组件 ``typescript import { memo } from 'react'; const Button = memo(({ onClick, children }: ButtonProps) => { return ( ); }); export default Button; ``` ### 2. 打包优化 - 代码分割减少初始包大小 - Tree shaking 移除未使用代码 - 按需加载组件和依赖 ### 3. 加载优化 - 骨架屏提升用户体验 - 图片懒加载减少资源消耗 - 异步组件提升首屏加载速度 ## 组件扩展性 ### 1. 插槽模式使用 React 的 children 和 render props 模式提供扩展点： ``typescript interface CardProps { title: string; actions?: React.ReactNode; children: React.ReactNode; } const Card: React.FC = ({ title, actions, children }) => { return (

{title}

{actions &&

{actions}

}

{children}

); }; ``` ### 2. 主题定制 - 支持通过CSS变量定制主题 - 提供主题切换功能 - 遵循系统主题偏好通过这套组件架构设计，项目能够确保UI组件的一致性、可维护性和可扩展性，为开发提供良好的基础。