component-naming

组件命名规范技能

此技能可帮助你在整个代码库中统一 React 组件的命名规范。

何时使用此技能

• 创建新的 React 组件
• 在 PR 中审查组件名称
• 重构现有组件
• 确保代码库命名一致

命名规则

1. PascalCase

所有 React 组件都使用 PascalCase：

// ✅ Good
export const TrendChart = () => {};
export const HeroPost = () => {};

// ❌ Bad
export const trendChart = () => {};
export const trend_chart = () => {};

2. 领域 + 角色模式

将领域上下文与组件角色结合，让名称更清晰：

// ✅ Good - Clear domain and role
export const TrendChart = () => {};       // Trend (domain) + Chart (role)
export const HeroPost = () => {};         // Hero (domain) + Post (role)
export const MetricCard = () => {};       // Metric (domain) + Card (role)
export const LatestCoePremium = () => {}; // LatestCoe (domain) + Premium (role)

// ❌ Bad - Too generic or unclear
export const Chart = () => {};            // No domain context
export const Data = () => {};             // Meaningless
export const Item = () => {};             // No specificity

3. 子部分使用复合组件

使用点号表示相关子组件：

// ✅ Good - Compound component pattern
export const HeroPost = () => {};
HeroPost.Image = () => {};
HeroPost.Title = () => {};
HeroPost.Meta = () => {};

// Usage
<HeroPost>
  <HeroPost.Image src={...} />
  <HeroPost.Title>...</HeroPost.Title>
  <HeroPost.Meta date={...} />
</HeroPost>

// ❌ Bad - Flat naming for related components
export const HeroPostImage = () => {};
export const HeroPostTitle = () => {};
export const HeroPostMeta = () => {};

4. 避免使用有问题的后缀

切勿使用以下后缀：

// ❌ Avoid these suffixes
export const MetricCardContainer = () => {};  // -Container
export const ChartWrapper = () => {};         // -Wrapper
export const DataComponent = () => {};        // -Component
export const ListElement = () => {};          // -Element

// ✅ Use clear domain + role instead
export const MetricCard = () => {};
export const TrendChart = () => {};
export const RegistrationList = () => {};

5. 避免描述布局或样式

名称应描述用途，而非外观：

// ❌ Bad - Describes layout/styling
export const LeftSidebar = () => {};
export const BigHeader = () => {};
export const RedButton = () => {};
export const TwoColumnLayout = () => {};

// ✅ Good - Describes purpose
export const NavigationSidebar = () => {};
export const PageHeader = () => {};
export const DangerButton = () => {};
export const ComparisonLayout = () => {};

文件命名规范

文件名使用与组件名称对应的 kebab-case：

组件	文件名
TrendChart	trend-chart.tsx
HeroPost	hero-post.tsx
MetricCard	metric-card.tsx
LatestCoePremium	latest-coe-premium.tsx

验证清单

审查组件名称时：

• 使用 PascalCase
• 具有明确的领域上下文（而不只是“Card”“List”或“Item”）
• 具有明确的角色（Chart、Card、List、Banner 等）
• 不使用 -Container、-Wrapper、-Component 后缀
• 不描述布局或样式（Left、Big、Red、TwoColumn）
• 文件名使用 kebab-case，且与组件名称对应
• 相关子组件采用复合模式

代码库中的示例

发现的良好模式：

• TrendAreaChart - Trends 领域 + Area Chart 角色
• MarketShareDonut - Market Share 领域 + Donut 角色
• TopMakesChart - Top Makes 领域 + Chart 角色
• PremiumBanner - Premium 领域 + Banner 角色
• MetricCard - Metric 领域 + Card 角色
• LatestCoePremium - Latest COE 领域 + Premium 角色

应避免的反模式：

• 通用名称：Chart、Card、List、Data
• 布局名称：LeftPanel、MainContent、TopSection
• 滥用后缀：CardContainer、ListWrapper、ItemComponent

相关文件

• apps/web/AGENTS.md - Web 应用组件规范
• apps/web/src/components/ - Web 应用组件
• apps/web/src/app/admin/components/ - 管理界面组件