# Apple 风格 UI 组件使用指南
本指南提供了 Apple 风格 UI 设计系统中所有组件的详细使用说明和最佳实践。
## 目录
1. [设计令牌](#设计令牌)
2. [基础组件](#基础组件)
3. [导航组件](#导航组件)
4. [数据展示组件](#数据展示组件)
5. [反馈组件](#反馈组件)
6. [媒体组件](#媒体组件)
7. [布局组件](#布局组件)
8. [动画组件](#动画组件)
9. [可访问性工具](#可访问性工具)
10. [性能优化](#性能优化)
## 设计令牌
### 字体系统
```typescript
import { LargeTitle, Title1, Body, Caption1 } from '@/components/ui/Typography'
function MyComponent() {
return (
大标题 (34pt)
标题 1 (28pt)
正文内容 (17pt)
说明文字 (12pt)
)
}
```
**最佳实践：**
- 使用语义化的字体组件而不是直接的 CSS 类
- 遵循苹果的字体层级，不要跳级使用
- 中英文混排时使用 `fontType="chinese"` 属性
### 颜色系统
```typescript
// 使用 Tailwind 类名
蓝色背景
// 使用设计令牌
import { appleColorTokens } from '@/lib/design-tokens'
const blueColor = appleColorTokens.system.blue.light
```
**最佳实践：**
- 优先使用语义化颜色（如 `apple-bg-primary`）
- 深色模式会自动切换颜色
- 使用系统颜色保持一致性
## 基础组件
### Button 按钮
```typescript
import Button from '@/components/ui/Button'
function ButtonExample() {
return (
{/* 四种变体 */}
{/* 三种尺寸 */}
{/* 状态 */}
)
}
```
**最佳实践：**
- 主要操作使用 `filled` 变体
- 次要操作使用 `tinted` 或 `gray` 变体
- 确保按钮最小尺寸为 44px（苹果触摸目标标准）
- 使用 `loading` 状态而不是禁用按钮
### Input 输入框
```typescript
import Input from '@/components/ui/Input'
function InputExample() {
return (
{/* 基础输入框 */}
{/* 状态变体 */}
{/* 带图标 */}
console.log('清除')}
/>
)
}
```
**最佳实践：**
- 始终提供 `label` 属性以支持可访问性
- 使用 `helperText` 提供额外说明
- 错误状态使用 `errorText` 而不是 `helperText`
- 合理使用图标增强用户体验
### Card 卡片
```typescript
import Card, { CardHeader, CardTitle, CardContent, CardFooter } from '@/components/ui/Card'
function CardExample() {
return (
{/* 简单卡片 */}
卡片标题
卡片内容
{/* 组合卡片 */}
高级卡片
使用组合组件构建的卡片
{/* 交互式卡片 */}
console.log('卡片点击')}
className="cursor-pointer"
>
可点击卡片
支持 hover 和 active 动画
{/* 大标题模式 */}
history.back()} />}
rightContent={ console.log('菜单')} />}
/>
{/* 标准模式 */}
}
rightContent={
}
/>
{/* 基础徽章 */}
Default
Success
Error
Warning
Info
{/* 数字徽章 */}
{/* 标签 */}
console.log('关闭')}>
可关闭标签
带图标标签
{/* 状态点 */}
{/* 线性进度条 */}
{/* 环形进度条 */}
{/* 步骤进度 */}
setShowModal(false)}
title="模态框标题"
description="模态框描述"
size="medium"
>
模态框内容
setShowConfirm(false)}
title="确认删除"
description="此操作无法撤销"
onConfirm={() => console.log('确认删除')}
/>
)
}
```
### Toast 提示
```typescript
import { useToast, ToastContainer } from '@/components/ui/Toast'
function ToastExample() {
const toast = useToast()
return (
)
}
```
## 动画组件
### AnimatedEntry 进入动画
```typescript
import AnimatedEntry, { SlideInUp, StaggeredAnimation } from '@/components/ui/AnimatedEntry'
function AnimationExample() {
return (
{/* 基础进入动画 */}
从下方滑入的卡片
{/* 预配置动画 */}
延迟 200ms 的滑入动画
{/* 交错动画 */}
{[1, 2, 3, 4].map(i => (
卡片 {i}
))}
当前字体大小: {preferences.fontSize}%
减少动画: {preferences.prefersReducedMotion ? '是' : '否'}
)
}
```
### 包容性设计
```typescript
import { createInclusiveStatusIndicator } from '@/lib/accessibility'
function StatusExample() {
const successIndicator = createInclusiveStatusIndicator('success', {
showIcon: true,
showShape: true,
size: 'medium'
})
return (
{successIndicator.icon}
)
}
```
## 性能优化
### 虚拟滚动
```typescript
import VirtualList from '@/components/ui/VirtualList'
function VirtualListExample() {
const items = Array.from({ length: 10000 }, (_, i) => ({
id: i,
name: `项目 ${i + 1}`,
description: `描述 ${i + 1}`
}))
return (
(
{item.name}
{item.description}
)}
/>
)
}
```
### 性能监控
```typescript
import { usePerformanceMonitor, useMemoryMonitor } from '@/lib/performance'
function PerformanceExample() {
usePerformanceMonitor('MyComponent')
const memoryInfo = useMemoryMonitor()
return (
{memoryInfo && (
内存使用: {Math.round(memoryInfo.usedJSHeapSize / 1024 / 1024)}MB
)}
内容
// 新方式
内容
```
### 从其他 UI 库迁移
```typescript
// Material-UI Button
// Apple UI Button
```
## 常见问题
### Q: 如何自定义主题颜色？
A: 修改 `tailwind.config.ts` 中的颜色令牌，或在 CSS 中覆盖 CSS 变量。
### Q: 动画不生效怎么办？
A: 检查用户是否启用了减少动画偏好，或者组件是否设置了 `disabled` 属性。
### Q: 如何确保可访问性？
A: 使用语义化 HTML，提供 ARIA 属性，确保键盘导航，测试对比度。
### Q: 性能优化建议？
A: 使用 React.memo，避免不必要的重渲染，大列表使用虚拟滚动。
## 总结
Apple 风格 UI 设计系统提供了完整的组件库和工具集，遵循苹果 Human Interface Guidelines 2025 标准。通过合理使用这些组件和工具，可以构建出美观、易用、高性能的用户界面。
记住始终考虑可访问性、性能和用户体验，让每个用户都能享受到优质的交互体验。