# 组件文档

## 组件概述

项目组件采用分层架构设计，分为基础 UI 组件、布局组件、业务区块组件和视觉效果组件。

## 组件分类

### 1. UI 基础组件 (`src/components/ui/`)

基于 shadcn/ui 的可复用基础组件，遵循 Radix UI 的无状态设计原则。

#### Button 按钮

```tsx
import { Button } from '@/components/ui/button';

// 基础用法
<Button>默认按钮</Button>

// 变体
<Button variant="default">默认</Button>
<Button variant="destructive">危险</Button>
<Button variant="outline">边框</Button>
<Button variant="secondary">次要</Button>
<Button variant="ghost">幽灵</Button>
<Button variant="link">链接</Button>

// 尺寸
<Button size="default">默认</Button>
<Button size="sm">小</Button>
<Button size="lg">大</Button>
<Button size="icon">图标</Button>
```

#### Card 卡片

```tsx
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card';

<Card>
  <CardHeader>
    <CardTitle>标题</CardTitle>
    <CardDescription>描述文字</CardDescription>
  </CardHeader>
  <CardContent>内容区域</CardContent>
  <CardFooter>底部操作</CardFooter>
</Card>
```

#### Input 输入框

```tsx
import { Input } from '@/components/ui/input';

<Input 
  type="text" 
  placeholder="请输入..." 
  className="w-full"
/>
```

#### Textarea 文本域

```tsx
import { Textarea } from '@/components/ui/textarea';

<Textarea 
  placeholder="请输入内容..."
  rows={4}
  className="w-full"
/>
```

#### Dialog 对话框

```tsx
import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription } from '@/components/ui/dialog';

<Dialog>
  <DialogTrigger asChild>
    <Button>打开对话框</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>标题</DialogTitle>
      <DialogDescription>描述</DialogDescription>
    </DialogHeader>
    {/* 内容 */}
  </DialogContent>
</Dialog>
```

#### DropdownMenu 下拉菜单

```tsx
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@/components/ui/dropdown-menu';

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="ghost">菜单</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>选项1</DropdownMenuItem>
    <DropdownMenuItem>选项2</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

#### Toast 提示

```tsx
import { Toast, ToastAction } from '@/components/ui/toast';

<Toast>
  <ToastTitle>提示标题</ToastTitle>
  <ToastDescription>提示内容</ToastDescription>
  <ToastAction>操作</ToastAction>
</Toast>
```

#### Badge 徽章

```tsx
import { Badge } from '@/components/ui/badge';

<Badge>默认</Badge>
<Badge variant="secondary">次要</Badge>
<Badge variant="destructive">危险</Badge>
<Badge variant="outline">边框</Badge>
```

#### 特殊 UI 组件

| 组件 | 描述 |
|------|------|
| `RippleButton` | 水波纹效果按钮 |
| `SealButton` | 印章风格按钮 |
| `GlassCard` | 毛玻璃效果卡片 |
| `AnimatedCard` | 动画卡片 |
| `InsightCard` | 洞察卡片 |
| `TestimonialCard` | 客户评价卡片 |
| `LoadingSkeleton` | 加载骨架屏 |
| `OptimizedImage` | 优化图片组件 |
| `ErrorBoundary` | 错误边界组件 |
| `BackButton` | 返回按钮 |
| `AnimatedNumber` | 数字动画 |
| `FlipClock` | 翻页时钟 |
| `PageHeader` | 页面头部 |
| `PageTransitions` | 页面过渡 |
| `ScrollAnimations` | 滚动动画 |

### 2. 布局组件 (`src/components/layout/`)

#### Header 页头导航

```tsx
import { Header } from '@/components/layout/header';

// 在布局中使用
<Header />
```

**功能特性：**
- 响应式导航菜单
- 滚动时样式变化
- 移动端汉堡菜单
- 键盘导航支持
- 焦点陷阱

#### Footer 页脚

```tsx
import { Footer } from '@/components/layout/footer';

// 在布局中使用
<Footer />
```

**功能特性：**
- 公司信息展示
- 快速链接
- 服务项目
- 联系方式
- 微信公众号二维码

#### MobileMenu 移动端菜单

```tsx
import { MobileMenu } from '@/components/layout/mobile-menu';

// 由 Header 内部调用
```

#### MobileTabBar 移动端底部导航

```tsx
import { MobileTabBar } from '@/components/layout/mobile-tab-bar';

// 在根布局中使用
<MobileTabBar />
```

#### Breadcrumb 面包屑

```tsx
import { Breadcrumb } from '@/components/layout/breadcrumb';

<Breadcrumb items={[
  { label: '首页', href: '/' },
  { label: '服务', href: '/services' },
  { label: '软件开发' },
]} />
```

### 3. 页面区块组件 (`src/components/sections/`)

#### HeroSection 首页 Hero 区域

```tsx
import { HeroSection } from '@/components/sections/hero-section';

<HeroSection />
```

**功能特性：**
- 动态背景效果
- 公司标语展示
- CTA 按钮
- 统计数据展示
- 滚动动画

#### ServicesSection 核心业务区块

```tsx
import { ServicesSection } from '@/components/sections/services-section';

<ServicesSection />
```

**功能特性：**
- 服务卡片网格
- 图标 + 标题 + 描述
- 悬停效果
- 链接到详情页

#### ProductsSection 产品服务区块

```tsx
import { ProductsSection } from '@/components/sections/products-section';

<ProductsSection />
```

#### CasesSection 成功案例区块

```tsx
import { CasesSection } from '@/components/sections/cases-section';

<CasesSection />
```

#### AboutSection 关于我们区块

```tsx
import { AboutSection } from '@/components/sections/about-section';

<AboutSection />
```

#### NewsSection 新闻动态区块

```tsx
import { NewsSection } from '@/components/sections/news-section';

<NewsSection />
```

#### ContactSection 联系区块

```tsx
import { ContactSection } from '@/components/sections/contact-section';

<ContactSection />
```

#### InsightsSection 洞察区块

```tsx
import { InsightsSection } from '@/components/sections/insights-section';

<InsightsSection />
```

#### TestimonialsSection 客户评价区块

```tsx
import { TestimonialsSection } from '@/components/sections/testimonials-section';

<TestimonialsSection />
```

### 4. 视觉效果组件 (`src/components/effects/`)

#### 渐变效果

| 组件 | 描述 |
|------|------|
| `GradientFlow` | 流动渐变背景 |
| `GradientFlowOptimized` | 优化的流动渐变 |
| `GradientAnimation` | 渐变动画 |
| `GradientGrid` | 渐变网格 |
| `GradientOrbs` | 渐变球体 |
| `MeshGradient` | 网格渐变 |

#### 粒子效果

| 组件 | 描述 |
|------|------|
| `DataParticleFlow` | 数据粒子流动 |
| `ParticleGalaxy` | 粒子星系 |
| `SubtleParticles` | 微妙粒子 |
| `MouseInteractiveParticles` | 鼠标交互粒子 |

#### 几何效果

| 组件 | 描述 |
|------|------|
| `GeometricShapes` | 几何形状 |
| `GeometricAbstract` | 几何抽象 |
| `GridLines` | 网格线 |
| `TechGridFlow` | 科技网格 |

#### 其他效果

| 组件 | 描述 |
|------|------|
| `GlowEffect` | 发光效果 |
| `ParallaxEffect` | 视差效果 |
| `FluidWaveBackground` | 流体波浪背景 |
| `InkTechFusion` | 水墨科技融合 |
| `SubtleDots` | 微妙点阵 |
| `SealAnimationEnhanced` | 印章动画增强 |
| `AdvancedFloatingEffects` | 高级浮动效果 |

### 5. SEO 组件 (`src/components/seo/`)

#### StructuredData 结构化数据

```tsx
import { OrganizationSchema, WebsiteSchema } from '@/components/seo/structured-data';

// 在布局中使用
<OrganizationSchema />
<WebsiteSchema />
```

**支持的 Schema 类型：**
- Organization - 组织信息
- Website - 网站信息
- BreadcrumbList - 面包屑
- Article - 文章

### 6. 分析组件 (`src/components/analytics/`)

#### WebVitals 性能监控

```tsx
import { WebVitals } from '@/components/analytics/web-vitals';

// 在根布局中使用
<WebVitals />
```

**监控指标：**
- LCP (Largest Contentful Paint)
- FID (First Input Delay)
- CLS (Cumulative Layout Shift)
- TTFB (Time to First Byte)
- INP (Interaction to Next Paint)

## 自定义 Hooks (`src/hooks/`)

### useMediaQuery 媒体查询

```tsx
import { useMediaQuery } from '@/hooks/use-media-query';

const isMobile = useMediaQuery('(max-width: 768px)');
```

### useScrollReveal 滚动显示

```tsx
import { useScrollReveal } from '@/hooks/use-scroll-reveal';

const { ref, isVisible } = useScrollReveal();
```

### useFocusTrap 焦点陷阱

```tsx
import { useFocusTrap } from '@/hooks/use-focus-trap';

const focusTrapRef = useFocusTrap<HTMLDivElement>(isActive);
```

### useIntersectionObserver 交叉观察

```tsx
import { useIntersectionObserver } from '@/hooks/use-intersection-observer';

const { ref, entry } = useIntersectionObserver({
  threshold: 0.5,
});
```

## 工具函数 (`src/lib/`)

### utils.ts 通用工具

```tsx
import { cn, formatNumber, formatCurrency, debounce, throttle } from '@/lib/utils';

// 类名合并
cn('base-class', conditional && 'active-class');

// 数字格式化
formatNumber(1234567); // '1,234,567'

// 货币格式化
formatCurrency(1234.56); // '¥1,234.56'

// 防抖
const debouncedFn = debounce(fn, 300);

// 节流
const throttledFn = throttle(fn, 100);
```

### constants.ts 常量配置

```tsx
import { COMPANY_INFO, NAVIGATION, STATS, SERVICES } from '@/lib/constants';

// 公司信息
COMPANY_INFO.name;     // '四川睿新致远科技有限公司'
COMPANY_INFO.email;    // 'contact@novalon.cn'
COMPANY_INFO.phone;    // '028-88888888'

// 导航配置
NAVIGATION; // NavigationItem[]

// 统计数据
STATS; // StatItem[]

// 服务数据
SERVICES; // Service[]
```

### animations.tsx 动画组件

```tsx
import { GradientText, MagneticButton, BlurReveal, CounterWithEffect } from '@/lib/animations';

// 渐变文字
<GradientText>渐变文字</GradientText>

// 磁性按钮
<MagneticButton>
  <Button>悬停跟随</Button>
</MagneticButton>

// 模糊显示
<BlurReveal>内容</BlurReveal>

// 数字计数器
<CounterWithEffect value={100} />
```

### 其他工具模块

| 模块 | 描述 |
|------|------|
| `colors.ts` | 颜色工具函数 |
| `gradients.ts` | 渐变配置 |
| `sanitize.ts` | XSS 防护清理 |
| `csrf.ts` | CSRF Token 生成 |
| `email-templates.ts` | 邮件模板 |
| `color-contrast.ts` | 颜色对比度检查 |

## 组件开发规范

### 1. 命名规范

- 组件文件：PascalCase (如 `Button.tsx`)
- 组件名称：与文件名一致
- Props 接口：`ComponentNameProps`
- 导出方式：命名导出

### 2. 文件结构

```tsx
// 1. 导入
import { useState } from 'react';
import { cn } from '@/lib/utils';

// 2. 类型定义
interface ButtonProps {
  variant?: 'default' | 'outline';
  children: React.ReactNode;
}

// 3. 组件定义
export function Button({ variant = 'default', children }: ButtonProps) {
  return <button className={cn('btn', variant)}>{children}</button>;
}

// 4. 默认导出（可选）
export default Button;
```

### 3. 样式规范

- 优先使用 Tailwind CSS 类名
- 使用 `cn()` 合并条件类名
- 避免内联样式
- 遵循移动优先原则

### 4. 可访问性规范

- 提供适当的 ARIA 属性
- 支持键盘导航
- 管理焦点状态
- 提供跳过链接