文档翻页设计
基于 shadcn/ui 的扁平化翻页组件设计规范和实现细节
本文档详细介绍了基于 shadcn/ui 的扁平化翻页组件的设计理念、实现细节和最佳实践。
🎯 设计目标
用户体验目标
- 直观性: 清晰的方向指示,用户一眼就能理解如何导航
- 可访问性: 支持键盘导航和屏幕阅读器
- 响应式: 完美适配桌面和移动设备
- 性能: 轻量级实现,不影响页面加载速度
技术目标
- 可复用性: 组件化设计,易于在不同项目中复用
- 可定制性: 支持主题定制和样式调整
- 类型安全: 完整的 TypeScript 类型定义
- SEO友好: 语义化 HTML 结构
🎨 设计灵感
我们参考了多个优秀的文档站点翻页设计:
Next.js 文档
- 简洁的卡片式设计
- 清晰的上一页/下一页标签
- 文档标题预览
Vercel 文档
- 扁平化设计风格
- 优雅的悬停效果
- 明确的方向指示
Tailwind CSS 文档
- 紧凑的布局设计
- 直观的图标使用
- 良好的视觉层次
🔧 组件实现
主要组件:DocPagination
typescript
<DocPagination
prevDoc={{ slug: 'docs/previous', title: '上一页标题' }}
nextDoc={{ slug: 'docs/next', title: '下一页标题' }}
/>
设计特点
-
扁平化卡片设计
- 使用
outline按钮样式 - 圆角边框和阴影效果
- 悬停时的背景色变化
- 使用
-
响应式布局
- 移动端:垂直堆叠布局
- 桌面端:水平并排布局
- 自动适配不同屏幕尺寸
-
视觉层次
- 方向标签使用小字号和上标样式
- 文档标题使用较大的字体和粗体
- 图标位置固定,提供视觉锚点
简化版本:CompactDocPagination
适用于空间有限的场景:
typescript
<CompactDocPagination
prevDoc={{ slug: 'docs/previous', title: '上一页' }}
nextDoc={{ slug: 'docs/next', title: '下一页' }}
/>
🎯 交互细节
悬停效果
- 图标动画: 轻微的缩放和位移效果
- 背景变化: 悬停时背景色变为 accent 色
- 平滑过渡: 200ms 的过渡动画
键盘导航
- Tab 键: 在按钮间切换焦点
- Enter/Space: 激活链接
- 屏幕阅读器: 提供清晰的 ARIA 标签
📱 响应式设计
移动端 (< 768px)
css
.flex-col {
display: flex;
flex-direction: column;
gap: 1rem;
}
桌面端 (>= 768px)
css
.hidden.md\:flex {
display: none;
}
@media (min-width: 768px) {
.hidden.md\:flex {
display: flex;
gap: 1rem;
}
}
♿ 可访问性
ARIA 属性
aria-label="文档导航": 为导航区域提供描述aria-hidden="true": 隐藏装饰性图标sr-only: 为屏幕阅读器提供额外信息
键盘支持
- Tab 键顺序符合视觉流
- 焦点状态清晰可见
- 支持 Enter 和 Space 键激活
🎨 主题定制
颜色变量
css
:root {
--pagination-border: hsl(var(--border));
--pagination-bg: hsl(var(--background));
--pagination-hover: hsl(var(--accent));
--pagination-text: hsl(var(--foreground));
--pagination-muted: hsl(var(--muted-foreground));
}
自定义样式
通过 className 属性支持自定义样式:
typescript
<DocPagination
prevDoc={prevDoc}
nextDoc={nextDoc}
className="my-custom-class"
/>
🚀 性能优化
代码分割
- 组件使用动态导入
- 按需加载,减少初始包大小
缓存策略
- 分页数据在构建时预计算
- 使用静态生成提高性能
📋 使用示例
基本用法
typescript
import { DocPagination } from '@/components/features/docs/doc-pagination';
function DocPage() {
return (
<div>
<h1>文档标题</h1>
<DocPagination
prevDoc={{ slug: 'intro', title: '介绍' }}
nextDoc={{ slug: 'guide', title: '使用指南' }}
/>
</div>
);
}
高级用法
typescript
import { getPrevNextDocs } from '@/components/features/docs/pagination-utils';
function DocPage({ currentDoc, allDocs }) {
const { prev, next } = getPrevNextDocs(allDocs, currentDoc.slug);
return (
<DocPagination
prevDoc={prev}
nextDoc={next}
className="mt-16 border-t pt-8"
/>
);
}
🎯 最佳实践
1. 内容组织
- 按照逻辑顺序组织文档
- 确保文档间的自然流转
- 提供清晰的导航路径
2. 标题设计
- 使用描述性的文档标题
- 保持标题简洁明了
- 避免过长的标题文本
3. 视觉一致性
- 在整个站点保持一致的样式
- 遵循设计系统的规范
- 确保与其他组件的视觉协调
🔮 未来改进
计划功能
- 面包屑导航集成
- 进度指示器
- 快速跳转到特定章节
- 深色模式优化
- 国际化支持
性能优化
- 预加载相邻页面
- 更智能的缓存策略
- 渐进式加载动画
📚 参考资源
这个翻页组件设计遵循了现代文档站点的最佳实践,提供了优秀的用户体验和可访问性支持。通过扁平化设计和响应式布局,确保了在各种设备上都能提供一致的导航体验。