implementing-navigation

导航模式与路由实现

目的

此技能全面介绍如何在前端和后端应用中实现导航系统。内容涵盖客户端导航模式（菜单、选项卡、面包屑）和路由（React Router、Next.js），以及服务器端路由配置（Flask、Django、FastAPI）。

适用场景

在以下情况下使用此技能：

• 构建主导航（顶部、侧边、巨型菜单）
• 实现次级导航（面包屑、选项卡、分页）
• 设置客户端路由（React Router、Next.js）
• 配置服务器端路由（Flask、Django、FastAPI）
• 创建移动端导航模式（汉堡菜单、底部导航）
• 实现支持键盘操作的导航
• 构建命令面板或搜索驱动的导航
• 创建多步向导或步骤条
• 确保导航符合 WCAG 2.1 AA 标准

导航决策框架

Information Architecture → Navigation Pattern

Flat (1-2 levels)      → Top Navigation
Deep (3+ levels)       → Side Navigation
E-commerce/Large       → Mega Menu
Linear Process         → Stepper/Wizard
Long Content          → Table of Contents
Power Users           → Command Palette
Multi-section Page    → Tabs
Large Data Sets       → Pagination

前端导航组件

主导航模式

顶部导航（水平）

• 适用于层级较浅的网站和营销网站
• 为降低认知负担，主链接最多设为 5-7 个
• 实现方式见 references/menu-patterns.md

侧边导航（垂直）

• 适用于层级较深的网站、管理面板和仪表盘
• 支持多级嵌套和可折叠分区
• 侧边栏模式见 references/menu-patterns.md

巨型菜单

• 适用于电子商务和内容丰富的网站
• 包含图像和描述等丰富内容
• 巨型菜单结构见 references/menu-patterns.md

次级导航组件

面包屑

• 显示层级路径和当前位置
• 对层级较深的网站和电子商务至关重要
• 面包屑模式见 references/navigation-components.md

选项卡

• 切换内容，无需重新加载页面
• 同步 URL，方便添加书签
• 选项卡实现方式见 references/navigation-components.md

分页

• 适用于搜索结果、商品列表和文章
• 可考虑使用虚拟化来提升性能
• 分页模式见 references/navigation-components.md

客户端路由

React Router（行业标准）

• 通过 loader 模式实现类型安全的路由
• 支持嵌套路由和延迟加载
• React Router 模式见 references/client-routing.md

Next.js App Router

• 基于文件的路由，支持 RSC
• 支持并行路由和拦截路由
• Next.js 路由方式见 references/client-routing.md

后端路由模式

Python Web 框架

Flask

• 基于 Blueprint 组织
• 路由装饰器和 URL 规则
• Flask 模式见 references/flask-routing.md

Django

• 使用命名空间配置 URL
• 路径转换器和正则表达式模式
• Django URL 配置见 references/django-urls.md

FastAPI

• 基于路由器组织
• 路径操作和依赖项
• FastAPI 路由器见 references/fastapi-routing.md

移动端导航

触控设备的模式

汉堡菜单

• 通过滑出式抽屉提供主导航
• 移动端抽屉见 references/menu-patterns.md

底部导航

• 提供 3-5 个主要操作，方便拇指触达
• 底部导航见 references/menu-patterns.md

选项卡栏

• 支持水平滚动和滑动的选项卡
• 适合移动优先的应用

无障碍要求

键盘导航

Tab       → Move forward through links
Shift+Tab → Move backward through links
Enter     → Activate link/button
Space     → Activate button
Arrow keys → Navigate within menus
Escape    → Close dropdowns/modals

ARIA 模式

无障碍导航所需的 ARIA 属性：

• 完整的 ARIA 模式见 references/accessibility-navigation.md
• 包括地标角色、状态和属性
• 屏幕阅读器优化技巧

焦点管理

• 显示清晰的焦点指示器（至少 2px，3:1 对比度）
• 为模态框和下拉菜单设置焦点陷阱
• 为键盘用户提供跳过导航链接
• 焦点模式见 references/accessibility-navigation.md

实现工具

导航结构管理

生成并验证导航树：

# Validate navigation structure
node scripts/validate_navigation_tree.js nav-config.json

# Generate breadcrumb trails
node scripts/calculate_breadcrumbs.js current-path

路由生成（Python）

生成路由配置：

# Generate Flask/Django/FastAPI routes
python scripts/generate_routes.py --framework flask --config routes.yaml

代码示例

前端示例

有关可正常使用的导航实现：

• examples/horizontal-menu.tsx - 响应式顶部导航
• examples/tab-navigation.tsx - 与 URL 同步的选项卡
• examples/mobile-navigation.tsx - 汉堡菜单和抽屉式导航

后端示例

有关路由配置：

• examples/flask_routes.py - Flask 蓝图设置
• examples/django_urls.py - Django URL 模式
• examples/fastapi_routes.py - FastAPI 路由器组织

导航配置

对于复杂的导航结构，请使用配置架构：

• assets/navigation-config-schema.json - 导航树架构
• assets/route-templates.json - 常见路由模式

使用验证脚本在实现前验证配置。

库推荐

前端路由

React Router 是 React 应用的推荐方案：

• 行业标准，提供出色的 TypeScript 支持
• 内置无障碍功能，支持 NavLink 活动状态
• 其他方案请参阅 references/library-comparison.md

组件库

如需快速开发，可考虑：

• 无头 UI 库（Radix UI、React Aria）
• 默认具备无障碍功能
• 可配合任何样式方案使用

渐进增强

构建无需 JavaScript 也能正常工作的导航：

• 服务端渲染的 HTML 导航
• 使用客户端路由实现渐进增强
• 为 JavaScript 故障提供备用方案

性能注意事项

• 延迟加载路由组件
• 预取导航目标
• 使用基于路由的代码拆分
• 为导航实现加载状态

测试导航

必要的导航测试：

• 键盘导航流程
• 屏幕阅读器播报
• 移动设备触控交互
• 路由参数验证
• 深层链接功能

后续步骤

1. 分析信息架构
2. 选择合适的导航模式
3. 优先考虑无障碍功能进行实现
4. 添加渐进增强
5. 在不同设备和辅助技术上进行测试

如需详细的实现指南，请根据具体需求查阅引用的文档文件。