316 lines
8.5 KiB
Markdown
316 lines
8.5 KiB
Markdown
# 导航模板页面使用指南
|
||
|
||
## 📋 概述
|
||
|
||
创建了一个完整的导航页面模板 (`src/pages/navigation-template.astro`)，展示了如何使用 SearchBar 和 NavigationCard 组件创建优雅的导航页面。
|
||
|
||
**模板位置：** `/navigation-template`
|
||
**源文件：** `src/pages/navigation-template.astro`
|
||
|
||
---
|
||
|
||
## 🎯 主要功能
|
||
|
||
### 1. **SearchBar 搜索功能**
|
||
- ✅ 磨砂玻璃效果
|
||
- ✅ 实时搜索过滤
|
||
- ✅ 优雅的动画效果
|
||
- ✅ 支持搜索标题和描述
|
||
|
||
### 2. **NavigationCard 导航卡片**
|
||
- ✅ 图标支持（Emoji）
|
||
- ✅ 标题和描述
|
||
- ✅ 自定义链接
|
||
- ✅ 渐入动画效果
|
||
|
||
### 3. **两种布局模式**
|
||
- **简单网格布局**：适合单一类别的导航项
|
||
- **分类布局**：适合多个类别的导航项
|
||
|
||
### 4. **莫兰迪蓝色系**
|
||
- 统一的配色方案
|
||
- 优雅的视觉效果
|
||
|
||
---
|
||
|
||
## 🔧 使用方法
|
||
|
||
### 步骤 1：配置导航数据
|
||
|
||
在页面顶部的 frontmatter 中定义导航项：
|
||
|
||
```astro
|
||
const navigationItems = [
|
||
{
|
||
title: '项目名称',
|
||
description: '项目的简短描述',
|
||
href: '/项目链接',
|
||
icon: '🚀',
|
||
tags: ['标签1', '标签2'], // 用于搜索，不会显示在卡片上
|
||
delay: 0 // 动画延迟（毫秒）
|
||
},
|
||
// ... 更多项目
|
||
];
|
||
```
|
||
|
||
### 步骤 2：添加 SearchBar
|
||
|
||
使用 AnimatedElement 包裹 SearchBar 来添加动画：
|
||
|
||
```astro
|
||
<AnimatedElement animation="fadeInUp" delay={200} trigger="load">
|
||
<SearchBar placeholder="🔍 搜索项目、标签或关键词..." />
|
||
</AnimatedElement>
|
||
```
|
||
|
||
**SearchBar 组件属性：**
|
||
- `placeholder` (可选): 搜索框提示文字，默认 "搜索..."
|
||
|
||
### 步骤 3：显示导航卡片
|
||
|
||
**简单网格布局：**
|
||
|
||
```astro
|
||
<NavigationGrid>
|
||
{navigationItems.map(item => (
|
||
<AnimatedElement
|
||
animation="fadeInUp"
|
||
delay={item.delay + 500}
|
||
trigger="load"
|
||
>
|
||
<NavigationCard
|
||
title={item.title}
|
||
description={item.description}
|
||
href={item.href}
|
||
icon={item.icon}
|
||
revealDirection="up"
|
||
/>
|
||
</AnimatedElement>
|
||
))}
|
||
</NavigationGrid>
|
||
```
|
||
|
||
**分类布局：**
|
||
|
||
```astro
|
||
{categorizedNavigation.map((category, categoryIndex) => (
|
||
<div class="category-section">
|
||
<AnimatedElement animation="fadeInUp" delay={categoryIndex * 200} trigger="scroll">
|
||
<h2 class="category-title">
|
||
<span class="category-icon">{category.icon}</span>
|
||
{category.category}
|
||
</h2>
|
||
</AnimatedElement>
|
||
|
||
<NavigationGrid>
|
||
{category.items.map((item, itemIndex) => (
|
||
<AnimatedElement
|
||
animation="fadeInUp"
|
||
delay={categoryIndex * 200 + itemIndex * 100 + 900}
|
||
trigger="scroll"
|
||
>
|
||
<NavigationCard
|
||
title={item.title}
|
||
description={item.description}
|
||
href={item.href}
|
||
icon={item.icon}
|
||
revealDirection="up"
|
||
/>
|
||
</AnimatedElement>
|
||
))}
|
||
</NavigationGrid>
|
||
</div>
|
||
))}
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 组件说明
|
||
|
||
### NavigationCard 属性
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `title` | `string` | 必需 | 卡片标题 |
|
||
| `description` | `string` | - | 卡片描述 |
|
||
| `href` | `string` | 必需 | 链接地址 |
|
||
| `icon` | `string` | - | 图标（支持 Emoji 或 Font Awesome） |
|
||
| `color` | `'primary' \| 'secondary' \| 'accent'` | `'primary'` | 卡片颜色主题 |
|
||
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 卡片大小 |
|
||
| `buttonLabel` | `string` | - | 按钮文字 |
|
||
| `revealDirection` | `'up' \| 'down' \| 'left' \| 'right' \| 'fade' \| 'none'` | - | 动画方向 |
|
||
| `revealDelay` | `string` | - | 动画延迟 |
|
||
|
||
### AnimatedElement 属性
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `animation` | `'fadeIn' \| 'fadeInUp' \| 'fadeInDown' \| ...` | `'fadeIn'` | 动画类型 |
|
||
| `delay` | `number` | `0` | 延迟时间（毫秒） |
|
||
| `duration` | `number` | `600` | 动画持续时间（毫秒） |
|
||
| `trigger` | `'load' \| 'scroll' \| 'hover' \| 'click'` | `'load'` | 触发方式 |
|
||
| `easing` | `string` | `'ease-out'` | 缓动函数 |
|
||
|
||
---
|
||
|
||
## 🎨 动画延迟配置建议
|
||
|
||
为了获得最佳的视觉效果，建议使用以下延迟时间配置：
|
||
|
||
```javascript
|
||
// 首屏内容 (trigger="load")
|
||
const TIMING = {
|
||
PAGE_TITLE: 0, // 页面标题
|
||
SEARCH_BAR: 200, // 搜索栏
|
||
SECTION_TITLE: 400, // 区域标题
|
||
FIRST_CARD: 500, // 第一张卡片
|
||
CARD_INCREMENT: 100 // 每张卡片递增
|
||
};
|
||
|
||
// 滚动后内容 (trigger="scroll")
|
||
const SCROLL_TIMING = {
|
||
CATEGORY_TITLE: 0, // 分类标题
|
||
FIRST_CARD: 100, // 第一张卡片
|
||
CARD_INCREMENT: 100 // 每张卡片递增
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 颜色自定义
|
||
|
||
模板使用了莫兰迪蓝色系，可以通过 CSS 变量自定义：
|
||
|
||
```css
|
||
.navigation-page {
|
||
--nav-color-primary: #5b778e; /* 主色调 */
|
||
--nav-color-primary-dark: #2c4a6b; /* 深色主色调 */
|
||
--nav-color-primary-deeper: #1f3a52; /* 更深的主色调 */
|
||
--nav-color-accent: #b2c5d5; /* 强调色 */
|
||
--nav-color-text: #2f3844; /* 文字颜色 */
|
||
--nav-color-subtext: #566171; /* 副文字颜色 */
|
||
--nav-color-border: rgba(91, 119, 142, 0.2); /* 边框颜色 */
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 响应式设计
|
||
|
||
模板自动适配不同屏幕尺寸：
|
||
|
||
- **桌面端**：3 列网格布局
|
||
- **平板端**：2 列网格布局
|
||
- **移动端**：单列布局
|
||
|
||
---
|
||
|
||
## 💡 使用示例
|
||
|
||
### 示例 1：简单导航页面
|
||
|
||
创建 `src/pages/my-projects.astro`：
|
||
|
||
```astro
|
||
---
|
||
import BaseLayout from '../layouts/BaseLayout.astro';
|
||
import Header from '../components/Header.astro';
|
||
import Footer from '../components/Footer.astro';
|
||
import AnimatedElement from '../components/AnimatedElement.astro';
|
||
import SearchBar from '../components/navigation/SearchBar.astro';
|
||
import NavigationCard from '../components/navigation/NavigationCard.astro';
|
||
import NavigationGrid from '../components/navigation/NavigationGrid.astro';
|
||
|
||
const projects = [
|
||
{
|
||
title: '个人博客',
|
||
description: '使用 Astro 构建的现代化博客系统',
|
||
href: '/blog',
|
||
icon: '📝',
|
||
delay: 0
|
||
},
|
||
{
|
||
title: '项目展示',
|
||
description: '展示我的开发项目和作品集',
|
||
href: '/portfolio',
|
||
icon: '💼',
|
||
delay: 100
|
||
}
|
||
];
|
||
---
|
||
|
||
<BaseLayout title="我的项目" description="个人项目展示">
|
||
<Header />
|
||
<main class="navigation-page">
|
||
<div class="container mx-auto px-4 py-8">
|
||
<AnimatedElement animation="fadeInUp" delay={0} trigger="load">
|
||
<h1 class="page-title">我的项目</h1>
|
||
</AnimatedElement>
|
||
|
||
<AnimatedElement animation="fadeInUp" delay={200} trigger="load">
|
||
<SearchBar placeholder="🔍 搜索项目..." />
|
||
</AnimatedElement>
|
||
|
||
<NavigationGrid>
|
||
{projects.map(project => (
|
||
<AnimatedElement
|
||
animation="fadeInUp"
|
||
delay={project.delay + 500}
|
||
trigger="load"
|
||
>
|
||
<NavigationCard
|
||
title={project.title}
|
||
description={project.description}
|
||
href={project.href}
|
||
icon={project.icon}
|
||
/>
|
||
</AnimatedElement>
|
||
))}
|
||
</NavigationGrid>
|
||
</div>
|
||
</main>
|
||
<Footer />
|
||
</BaseLayout>
|
||
```
|
||
|
||
### 示例 2：分类导航页面
|
||
|
||
参考模板中的 `categorizedNavigation` 配置，创建多层级的导航结构。
|
||
|
||
---
|
||
|
||
## 📂 相关文件
|
||
|
||
- **模板文件：** `src/pages/navigation-template.astro`
|
||
- **SearchBar 组件：** `src/components/navigation/SearchBar.astro`
|
||
- **NavigationCard 组件：** `src/components/navigation/NavigationCard.astro`
|
||
- **NavigationGrid 组件：** `src/components/navigation/NavigationGrid.astro`
|
||
- **AnimatedElement 组件：** `src/components/AnimatedElement.astro`
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
- [搜索栏优化文档](./SEARCH_BAR_OPTIMIZATION.md)
|
||
- [组件使用指南](./COMPONENTS_GUIDE.md)
|
||
- [动画系统说明](./ANIMATION_DELAY_SYSTEM.md)
|
||
- [报告模板总结](./REPORT_TEMPLATE_SUMMARY.md)
|
||
|
||
---
|
||
|
||
## ✨ 特性总结
|
||
|
||
1. ✅ **完整的模板示例** - 开箱即用的导航页面模板
|
||
2. ✅ **搜索功能** - 实时过滤导航项
|
||
3. ✅ **优雅动画** - 渐入式动画效果
|
||
4. ✅ **响应式设计** - 自适应各种屏幕尺寸
|
||
5. ✅ **莫兰迪配色** - 统一的视觉风格
|
||
6. ✅ **灵活布局** - 支持简单和分类两种布局
|
||
7. ✅ **详细文档** - 包含使用说明和代码示例
|
||
8. ✅ **TypeScript 类型安全** - 组件接口清晰
|
||
|
||
---
|
||
|
||
**创建日期：** 2025年10月1日
|
||
**最后更新：** 2025年10月1日
|