implementing-navigation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Navigation Patterns & Routing Implementation

导航模式与路由实现

Purpose

用途

This skill provides comprehensive guidance for implementing navigation systems across both frontend and backend applications. It covers client-side navigation patterns (menus, tabs, breadcrumbs) and routing (React Router, Next.js) as well as server-side route configuration (Flask, Django, FastAPI).

本Skill为前后端应用的导航系统实现提供全面指导，涵盖客户端导航模式（菜单、标签页、面包屑）与路由（React Router、Next.js），以及服务端路由配置（Flask、Django、FastAPI）。

When to Use

适用场景

Use this skill when:

Building primary navigation (top, side, mega menus)
Implementing secondary navigation (breadcrumbs, tabs, pagination)
Setting up client-side routing (React Router, Next.js)
Configuring server-side routes (Flask, Django, FastAPI)
Creating mobile navigation patterns (hamburger, bottom nav)
Implementing keyboard-accessible navigation
Building command palettes or search-driven navigation
Creating multi-step wizards or steppers
Ensuring WCAG 2.1 AA compliance for navigation

在以下场景中使用本Skill：

构建主导航（顶部、侧边、巨型菜单）
实现二级导航（面包屑、标签页、分页）
设置客户端路由（React Router、Next.js）
配置服务端路由（Flask、Django、FastAPI）
打造移动端导航模式（汉堡菜单、底部导航）
实现键盘可访问的导航
构建命令面板或搜索驱动型导航
创建多步骤向导或分步组件
确保导航符合WCAG 2.1 AA标准

Navigation Decision Framework

导航决策框架

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

信息架构 → 导航模式

扁平化（1-2级）      → 顶部导航
层级较深（3+级）       → 侧边导航
电商/大型站点       → 巨型菜单
线性流程         → 分步向导/流程
长内容          → 目录
高级用户           → 命令面板
多区块页面    → 标签页
大型数据集       → 分页

Frontend Navigation Components

前端导航组件

Primary Navigation Patterns

主导航模式

Top Navigation (Horizontal)

Best for shallow hierarchies, marketing sites
5-7 primary links maximum for cognitive load
See
```
references/menu-patterns.md
```
for implementation

Side Navigation (Vertical)

Best for deep hierarchies, admin panels, dashboards
Supports multi-level nesting and collapsible sections
See
```
references/menu-patterns.md
```
for sidebar patterns

Mega Menu

Best for e-commerce, content-heavy sites
Rich content with images and descriptions
See
```
references/menu-patterns.md
```
for mega menu structure

顶部导航（水平）

适用于浅层级架构、营销类站点
为降低认知负荷，最多设置5-7个主链接
实现细节请参考
```
references/menu-patterns.md
```

侧边导航（垂直）

适用于深层级架构、管理面板、仪表盘
支持多级嵌套与可折叠区块
侧边栏模式请参考
```
references/menu-patterns.md
```

巨型菜单

适用于电商、内容密集型站点
支持包含图片与描述的富内容
巨型菜单结构请参考
```
references/menu-patterns.md
```

Secondary Navigation Components

二级导航组件

Breadcrumbs

Shows hierarchical path and current location
Essential for deep sites and e-commerce
See
```
references/navigation-components.md
```
for breadcrumb patterns

Tabs

Content switching without page reload
URL synchronization for bookmarking
See
```
references/navigation-components.md
```
for tab implementation

Pagination

For search results, product lists, articles
Consider virtualization for performance
See
```
references/navigation-components.md
```
for pagination patterns

面包屑

展示层级路径与当前位置
对深层站点与电商平台至关重要
面包屑模式请参考
```
references/navigation-components.md
```

标签页

无需刷新页面即可切换内容
支持URL同步以便书签保存
标签页实现细节请参考
```
references/navigation-components.md
```

分页

适用于搜索结果、产品列表、文章列表
考虑使用虚拟化提升性能
分页模式请参考
```
references/navigation-components.md
```

Client-Side Routing

客户端路由

React Router (Industry Standard)

Type-safe routing with loader patterns
Nested routes and lazy loading support
See
```
references/client-routing.md
```
for React Router patterns

Next.js App Router

File-based routing with RSC support
Parallel and intercepting routes
See
```
references/client-routing.md
```
for Next.js routing

React Router（行业标准）

支持类型安全的路由与加载器模式
支持嵌套路由与懒加载
React Router模式请参考
```
references/client-routing.md
```

Next.js App Router

基于文件的路由，支持RSC
支持并行路由与拦截路由
Next.js路由请参考
```
references/client-routing.md
```

Backend Routing Patterns

后端路由模式

Python Web Frameworks

Python Web框架

Flask

Blueprint-based organization
Route decorators and URL rules
See
```
references/flask-routing.md
```
for Flask patterns

Django

URL configuration with namespaces
Path converters and regex patterns
See
```
references/django-urls.md
```
for Django URL conf

FastAPI

Router-based organization
Path operations and dependencies
See
```
references/fastapi-routing.md
```
for FastAPI routers

Flask

基于Blueprint的组织方式
路由装饰器与URL规则
Flask模式请参考
```
references/flask-routing.md
```

Django

带命名空间的URL配置
路径转换器与正则表达式模式
Django URL配置请参考
```
references/django-urls.md
```

FastAPI

基于Router的组织方式
路径操作与依赖管理
FastAPI路由请参考
```
references/fastapi-routing.md
```

Mobile Navigation

移动端导航

Patterns for Touch Devices

触控设备适配模式

Hamburger Menu

Slide-out drawer for primary navigation
See
```
references/menu-patterns.md
```
for mobile drawer

Bottom Navigation

3-5 primary actions, thumb-friendly
See
```
references/menu-patterns.md
```
for bottom nav

Tab Bar

Horizontal scrollable tabs with swipe
Natural for mobile-first applications

汉堡菜单

滑出式抽屉用于主导航
移动端抽屉实现请参考
```
references/menu-patterns.md
```

底部导航

3-5个主操作，便于拇指操作
底部导航实现请参考
```
references/menu-patterns.md
```

标签栏

可水平滚动的标签页，支持滑动切换
适配移动端优先的应用

Accessibility Requirements

无障碍要求

Keyboard Navigation

键盘导航

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

Tab       → 向前切换链接
Shift+Tab → 向后切换链接
Enter     → 激活链接/按钮
Space     → 激活按钮
方向键 → 在菜单内导航
Escape    → 关闭下拉菜单/模态框

ARIA Patterns

ARIA模式

Essential ARIA attributes for accessible navigation:

See
```
references/accessibility-navigation.md
```
for complete ARIA patterns
Includes landmark roles, states, and properties
Screen reader optimization techniques

无障碍导航必备的ARIA属性：

完整ARIA模式请参考
```
references/accessibility-navigation.md
```
包含地标角色、状态与属性
屏幕阅读器优化技巧

Focus Management

焦点管理

Visible focus indicators (2px minimum, 3:1 contrast)
Focus trap for modals and dropdowns
Skip navigation link for keyboard users
See
```
references/accessibility-navigation.md
```
for focus patterns

可见的焦点指示器（最小2px，对比度3:1）
模态框与下拉菜单的焦点陷阱
为键盘用户提供跳过导航链接
焦点模式请参考
```
references/accessibility-navigation.md
```

Implementation Utilities

实现工具

Navigation Structure Management

导航结构管理

Generate and validate navigation trees:

bash

undefined

生成并验证导航树：

bash

undefined

Validate navigation structure

验证导航结构

node scripts/validate_navigation_tree.js nav-config.json

Generate breadcrumb trails

生成面包屑路径

node scripts/calculate_breadcrumbs.js current-path

undefined

node scripts/calculate_breadcrumbs.js current-path

undefined

Route Generation (Python)

路由生成（Python）

Generate route configurations:

bash

undefined

生成路由配置：

bash

undefined

Generate Flask/Django/FastAPI routes

生成Flask/Django/FastAPI路由

python scripts/generate_routes.py --framework flask --config routes.yaml

undefined

python scripts/generate_routes.py --framework flask --config routes.yaml

undefined

Code Examples

代码示例

Frontend Examples

前端示例

For working navigation implementations:

```
examples/horizontal-menu.tsx
```
- Responsive top navigation
```
examples/tab-navigation.tsx
```
- Tabs with URL sync
```
examples/mobile-navigation.tsx
```
- Hamburger and drawer

可运行的导航实现示例：

```
examples/horizontal-menu.tsx
```
- 响应式顶部导航
```
examples/tab-navigation.tsx
```
- 带URL同步的标签页
```
examples/mobile-navigation.tsx
```
- 汉堡菜单与抽屉

Backend Examples

后端示例

For routing configuration:

```
examples/flask_routes.py
```
- Flask blueprint setup
```
examples/django_urls.py
```
- Django URL patterns
```
examples/fastapi_routes.py
```
- FastAPI router organization

路由配置示例：

```
examples/flask_routes.py
```
- Flask Blueprint配置
```
examples/django_urls.py
```
- Django URL模式
```
examples/fastapi_routes.py
```
- FastAPI Router组织

Navigation Configuration

导航配置

For complex navigation structures, use the configuration schema:

```
assets/navigation-config-schema.json
```
- Navigation tree schema
```
assets/route-templates.json
```
- Common route patterns

Validate configurations before implementation using the validation script.

针对复杂导航结构，使用以下配置 schema：

```
assets/navigation-config-schema.json
```
- 导航树schema
```
assets/route-templates.json
```
- 通用路由模式

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

Library Recommendations

库推荐

Frontend Routing

前端路由

React Router is the recommended solution for React applications:

Industry standard with excellent TypeScript support
Built-in accessibility with NavLink active states
See
```
references/library-comparison.md
```
for alternatives

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

行业标准，具备出色的TypeScript支持
内置无障碍特性，包含NavLink激活状态
替代方案请参考
```
references/library-comparison.md
```

Component Libraries

组件库

For rapid development, consider:

Headless UI libraries (Radix UI, React Aria)
Accessible by default
Work with any styling approach

如需快速开发，可考虑：

无头UI库（Radix UI、React Aria）
默认支持无障碍
兼容任意样式方案

Progressive Enhancement

渐进式增强

Build navigation that works without JavaScript:

Server-rendered HTML navigation
Progressive enhancement with client-side routing
Fallback for JavaScript failures

构建无需JavaScript即可运行的导航：

服务端渲染的HTML导航
通过客户端路由实现渐进式增强
为JavaScript故障提供降级方案

Performance Considerations

性能考量

Lazy load route components
Prefetch navigation targets
Use route-based code splitting
Implement loading states for navigation

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

Testing Navigation

导航测试

Essential navigation tests:

Keyboard navigation flow
Screen reader announcements
Mobile touch interactions
Route parameter validation
Deep linking functionality

必备的导航测试项：

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

Next Steps

后续步骤

Analyze the information architecture
Select appropriate navigation pattern
Implement with accessibility first
Add progressive enhancement
Test across devices and assistive technologies

For detailed implementation guides, explore the referenced documentation files based on specific requirements.

分析信息架构
选择合适的导航模式
优先以无障碍为核心进行实现
添加渐进式增强
跨设备与辅助技术进行测试

如需详细实现指南，请根据具体需求查阅参考文档。