张翔
11 KiB
11 KiB
组件文档
组件概述
项目组件采用分层架构设计，分为基础 UI 组件、布局组件、业务区块组件和视觉效果组件。
组件分类
1. UI 基础组件 (src/components/ui/)
基于 shadcn/ui 的可复用基础组件，遵循 Radix UI 的无状态设计原则。
Button 按钮
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 卡片
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card';
<Card>
<CardHeader>
<CardTitle>标题</CardTitle>
<CardDescription>描述文字</CardDescription>
</CardHeader>
<CardContent>内容区域</CardContent>
<CardFooter>底部操作</CardFooter>
</Card>
Input 输入框
import { Input } from '@/components/ui/input';
<Input
type="text"
placeholder="请输入..."
className="w-full"
/>
Textarea 文本域
import { Textarea } from '@/components/ui/textarea';
<Textarea
placeholder="请输入内容..."
rows={4}
className="w-full"
/>
Dialog 对话框
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 下拉菜单
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 提示
import { Toast, ToastAction } from '@/components/ui/toast';
<Toast>
<ToastTitle>提示标题</ToastTitle>
<ToastDescription>提示内容</ToastDescription>
<ToastAction>操作</ToastAction>
</Toast>
Badge 徽章
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 页头导航
import { Header } from '@/components/layout/header';
// 在布局中使用
<Header />
功能特性：
- 响应式导航菜单
- 滚动时样式变化
- 移动端汉堡菜单
- 键盘导航支持
- 焦点陷阱
Footer 页脚
import { Footer } from '@/components/layout/footer';
// 在布局中使用
<Footer />
功能特性：
- 公司信息展示
- 快速链接
- 服务项目
- 联系方式
- 微信公众号二维码
MobileMenu 移动端菜单
import { MobileMenu } from '@/components/layout/mobile-menu';
// 由 Header 内部调用
MobileTabBar 移动端底部导航
import { MobileTabBar } from '@/components/layout/mobile-tab-bar';
// 在根布局中使用
<MobileTabBar />
Breadcrumb 面包屑
import { Breadcrumb } from '@/components/layout/breadcrumb';
<Breadcrumb items={[
{ label: '首页', href: '/' },
{ label: '服务', href: '/services' },
{ label: '软件开发' },
]} />
3. 页面区块组件 (src/components/sections/)
HeroSection 首页 Hero 区域
import { HeroSection } from '@/components/sections/hero-section';
<HeroSection />
功能特性：
- 动态背景效果
- 公司标语展示
- CTA 按钮
- 统计数据展示
- 滚动动画
ServicesSection 核心业务区块
import { ServicesSection } from '@/components/sections/services-section';
<ServicesSection />
功能特性：
- 服务卡片网格
- 图标 + 标题 + 描述
- 悬停效果
- 链接到详情页
ProductsSection 产品服务区块
import { ProductsSection } from '@/components/sections/products-section';
<ProductsSection />
CasesSection 成功案例区块
import { CasesSection } from '@/components/sections/cases-section';
<CasesSection />
AboutSection 关于我们区块
import { AboutSection } from '@/components/sections/about-section';
<AboutSection />
NewsSection 新闻动态区块
import { NewsSection } from '@/components/sections/news-section';
<NewsSection />
ContactSection 联系区块
import { ContactSection } from '@/components/sections/contact-section';
<ContactSection />
InsightsSection 洞察区块
import { InsightsSection } from '@/components/sections/insights-section';
<InsightsSection />
TestimonialsSection 客户评价区块
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 结构化数据
import { OrganizationSchema, WebsiteSchema } from '@/components/seo/structured-data';
// 在布局中使用
<OrganizationSchema />
<WebsiteSchema />
支持的 Schema 类型：
- Organization - 组织信息
- Website - 网站信息
- BreadcrumbList - 面包屑
- Article - 文章
6. 分析组件 (src/components/analytics/)
WebVitals 性能监控
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 媒体查询
import { useMediaQuery } from '@/hooks/use-media-query';
const isMobile = useMediaQuery('(max-width: 768px)');
useScrollReveal 滚动显示
import { useScrollReveal } from '@/hooks/use-scroll-reveal';
const { ref, isVisible } = useScrollReveal();
useFocusTrap 焦点陷阱
import { useFocusTrap } from '@/hooks/use-focus-trap';
const focusTrapRef = useFocusTrap<HTMLDivElement>(isActive);
useIntersectionObserver 交叉观察
import { useIntersectionObserver } from '@/hooks/use-intersection-observer';
const { ref, entry } = useIntersectionObserver({
threshold: 0.5,
});
工具函数 (src/lib/)
utils.ts 通用工具
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 常量配置
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 动画组件
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. 文件结构
// 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 属性
- 支持键盘导航
- 管理焦点状态
- 提供跳过链接