docs: 删除过时的文档和测试报告文件
删除不再需要的文档、测试报告和计划文件，包括标题层级规范、颜色优化报告、测试框架文档等
This commit is contained in:
张翔
@@ -0,0 +1,535 @@
|
||||
# 组件文档
|
||||
|
||||
## 组件概述
|
||||
|
||||
项目组件采用分层架构设计，分为基础 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 属性
|
||||
- 支持键盘导航
|
||||
- 管理焦点状态
|
||||
- 提供跳过链接
|
||||
Reference in New Issue
Block a user