# 鸿蒙-学习测试

**Repository Path**: ZhuXiuLong/harmony-osdemo

## Basic Information

- **Project Name**: 鸿蒙-学习测试
- **Description**: 📖📖📖📖📖📖📖📖📖📖
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-10-02
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: HarmonyOSStudy

## README

# HarmonyOS 项目路由架构文档

本文档详细说明本项目的路由架构规则，帮助开发者快速理解和创建新的路由视图。

## 目录

1. [整体架构概览](#整体架构概览)
2. [Application 模块分类架构](#application-模块分类架构)
3. [模块层级路由（Ability 跳转）](#模块层级路由ability-跳转)
4. [模块内 Navigation 路由](#模块内-navigation-路由)
5. [Router 页面跳转](#router-页面跳转)
6. [如何新建路由视图](#如何新建路由视图)
7. [注意事项](#注意事项)

---

## 整体架构概览

本项目采用三层路由架构，包含多个功能模块：

### 项目模块列表

所有模块在 [build-profile.json5](file:///c:\Users\24837\DevecostudioProjects\harmony-osdemo\build-profile.json5) 中配置：

| 模块名 | 路径 | 说明 |
|--------|------|------|
| `application` | `./application` | 应用入口模块（Entry） |
| `arkUI` | `./1_Framework/arkUI` | ArkUI 框架演示模块 |
| `arkTS` | `./1_Framework/arkTS` | ArkTS 语言特性模块 |
| `coreFileKit` | `./1_Framework/coreFileKit` | 文件管理框架模块 |
| `formKit` | `./1_Framework/formKit` | 卡片框架模块 |
| `arkWeb` | `./1_Framework/arkWeb` | Web 组件模块 |
| `stageModel` | `./1_Framework/stageModel` | 阶段模型演示模块 |
| `audioFeature` | `./1_Framework/stageModel2/audioFeature` | 音频特性模块 |
| `videoFeature` | `./1_Framework/stageModel2/videoFeature` | 视频特性模块 |
| `libraryHSP` | `./1_Framework/stageModel2/libraryHSP` | HSP 共享库模块 |
| `library` | `./1_Framework/stageModel2/library` | 普通共享库模块 |
| `security` | `./2_System/security` | 系统安全模块 |
| `network` | `./2_System/network` | 网络模块 |
| `media` | `./3_Media/media` | 媒体模块 |
| `scanKit` | `./3_Media/scanKit` | 扫码服务模块 |
| `service` | `./5_Service/service` | 基础服务模块 |
| `pushKit` | `./5_Service/pushKit` | 推送服务模块 |
| `AI` | `./6_AI/AI` | AI 能力模块 |
| `drawing` | `./7_Graphic/drawing` | 图形绘制模块 |
| `multiDevelop` | `./8_Multi_development/multiDevelop` | 多端开发模块 |
| `ndkDemo` | `./9_NDK/ndkDemo` | NDK 开发演示模块 |
| `test` | `./0_TEST/test` | 测试模块 |
| `WeChatShare` | `./0_TEST/WeChatShare` | 微信分享测试模块 |

### 路由架构图

```
┌─────────────────────────────────────────────────────────────┐
│                    Entry 模块 (application)                  │
│                    Index.ets - 应用入口                      │
│                    通过 startAbility 跳转到各 Feature 模块    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              Feature 模块 (如 arkUI、media 等)               │
│              abilityIndex1.ets - 模块首页                    │
│              使用 Navigation 管理子页面                       │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐    ┌─────────────────────────────┐
│   Navigation 路由系统    │    │      Router 路由系统         │
│   (推荐，用于子页面)      │    │   (用于独立 Entry 页面)      │
│   route_map.json        │    │   main_pages.json           │
└─────────────────────────┘    └─────────────────────────────┘
```

---

## 模块层级路由（Ability 跳转）

### 入口文件

**文件路径**: `application/src/main/ets/pages/Index.ets`

### 跳转方式

使用 `startAbility` 方法跳转到不同 Feature 模块的 Ability：

```typescript
const abilityContext = getContext(this) as common.UIAbilityContext
abilityContext.startAbility({
  bundleName: 'name.zxl.www',
  moduleName: item.split('-')[0],  // 如: "arkUI"
  abilityName: item.split('-')[1]   // 如: "Module1Ability"
})
```

### 路由映射配置

在 `Index.ets` 中定义模块路由映射：

```typescript
module_route: Record<string, string> = {
  "arkUI-Module1Ability": '框架-ArkUI',
  "media-Media_featureAbility": '媒体-Media Kit',
  // ... 其他模块
}
```

### 配置说明

- **Key 格式**: `{moduleName}-{abilityName}`
- **Value**: 按钮显示的文本

### 新增模块步骤

1. 在 `module_route` 中添加新的模块映射
2. 确保对应模块的 Ability 已在 `module.json5` 中声明

---

## 模块内 Navigation 路由

### 核心概念

Navigation 路由是本项目的**主要路由方式**，用于模块内部的页面跳转。

### 文件结构

```
arkUI/src/main/
├── ets/
│   ├── pages/
│   │   └── abilityIndex1.ets          # 模块首页，Navigation 根容器
│   └── ArkTS_API/
│       └── apiDEMO.ets                # 子导航页面示例
├── resources/base/profile/
│   └── route_map.json                 # Navigation 路由表
└── module.json5                       # 模块配置，声明路由表路径
```

### 路由表配置

**文件路径**: `arkUI/src/main/resources/base/profile/route_map.json`

```json
{
  "routerMap": [
    {
      "name": "apiDEMO",
      "pageSourceFile": "src/main/ets/ArkTS_API/apiDEMO.ets",
      "buildFunction": "apiDEMOBuilder"
    }
  ]
}
```

### 路由表字段说明

| 字段 | 说明 | 示例 |
|------|------|------|
| `name` | 路由标识名，跳转时使用 | `"apiDEMO"` |
| `pageSourceFile` | 页面文件相对路径 | `"src/main/ets/ArkTS_API/apiDEMO.ets"` |
| `buildFunction` | 页面构建函数名 | `"apiDEMOBuilder"` |

### 页面文件结构

**示例**: `apiDEMO.ets`

```typescript
// 1. Builder 函数：路由表的入口
@Builder
function apiDEMOBuilder() {
  NavDestination() {
    apiDEMO()
  }
}

// 2. 组件定义
@Component
export struct apiDEMO {
  navPathStack: NavPathStack = new NavPathStack()
  
  // 子路由映射（可选，用于嵌套导航）
  route_map: Record<string, string> = {
    "displayTest": 'display',
    "windowDEMO": 'window',
    // ...
  }
  
  build() {
    Navigation(this.navPathStack) {
      Column({ space: 10 }) {
        // 子页面跳转按钮
        ForEach(Object.keys(this.route_map), (item: string) => {
          Button(this.route_map[item])
            .onClick(() => {
              // 3. 跳转到子页面
              this.navPathStack.pushPathByName(item, null)
            })
        })
      }
    }
  }
}
```

### 跳转方式

```typescript
// 在 Navigation 容器内跳转
this.navPathStack.pushPathByName('路由名称', 参数)

// 示例
this.navPathStack.pushPathByName('apiDEMO', null)
```

### 模块配置

**文件路径**: `arkUI/src/main/module.json5`

```json
{
  "module": {
    "routerMap": "$profile:route_map"
  }
}
```

---

## Router 页面跳转

### 适用场景

Router 跳转用于**独立的 Entry 页面**，通常是：
- 需要独立生命周期的页面
- 需要跨模块跳转的页面
- 作为 Ability 的入口页面

### 路由配置

**文件路径**: `arkUI/src/main/resources/base/profile/main_pages.json`

```json
{
  "src": [
    "pages/abilityIndex1",
    "ArkTS_Component/Navigation_Switching/router/page1",
    "ArkTS_Component/Navigation_Switching/router/page2"
  ]
}
```

### 跳转方式

```typescript
import { router } from '@kit.ArkUI'

// 跳转页面
router.pushUrl({
  url: 'ArkTS_Component/Navigation_Switching/router/page1'
}, router.RouterMode.Single)

// 带模式参数
router.pushUrl({
  url: '页面路径'
}, router.RouterMode.Standard)  // 或 RouterMode.Single
```

### RouterMode 说明

| 模式 | 说明 |
|------|------|
| `Standard` | 标准模式，每次跳转都创建新实例 |
| `Single` | 单例模式，如果页面已存在则复用 |

---

## 如何新建路由视图

### 方式一：新增 Navigation 子页面（推荐）

适用于模块内部的页面跳转：

1. **创建页面文件**

   在模块的 `ets` 目录下创建新文件，如：
   ```
   arkUI/src/main/ets/ArkTS_Component/newFeature/newPage.ets
   ```

2. **编写页面代码**

   ```typescript
   @Builder
   function newPageBuilder() {
     NavDestination() {
       newPage()
     }
   }

   @Component
   export struct newPage {
     build() {
       Column() {
         Text('新页面内容')
       }
     }
   }
   ```

3. **注册路由表**

   在 `route_map.json` 中添加：
   ```json
   {
     "name": "newPage",
     "pageSourceFile": "src/main/ets/ArkTS_Component/newFeature/newPage.ets",
     "buildFunction": "newPageBuilder"
   }
   ```

4. **添加跳转入口**

   在父页面的 `route_map` 中添加：
   ```typescript
   route_map: Record<string, string> = {
     "newPage": '新功能页面'
   }
   ```

### 方式二：新增 Router 页面

适用于需要独立生命周期的页面：

1. **创建页面文件**

   如：`arkUI/src/main/ets/pages/newEntryPage.ets`

2. **编写页面代码**

   ```typescript
   @Entry
   @Component
   struct NewEntryPage {
     build() {
       Column() {
         Text('Entry 页面内容')
       }
     }
   }
   ```

3. **注册到 main_pages.json**

   ```json
   {
     "src": [
       "pages/newEntryPage"
     ]
   }
   ```

4. **添加跳转按钮**

   ```typescript
   Button('跳转新页面')
     .onClick(() => {
       router.pushUrl({
         url: 'pages/newEntryPage'
       })
     })
   ```

### 方式三：新增 Feature 模块

适用于创建全新的功能模块：

1. **创建新模块**

   使用 DevEco Studio 创建新的 Feature 模块

2. **配置 Ability**

   在 `module.json5` 中声明 Ability：
   ```json
   {
     "abilities": [
       {
         "name": "NewFeatureAbility",
         "srcEntry": "./ets/abilities/NewFeatureAbility.ets"
       }
     ]
   }
   ```

3. **在 Entry 模块注册**

   在 `application/src/main/ets/pages/Index.ets` 中添加：
   ```typescript
   module_route: Record<string, string> = {
     "newModule-NewFeatureAbility": '新功能模块'
   }
   ```

---

## 路由选择建议

| 场景 | 推荐方式 | 原因 |
|------|----------|------|
| 模块内部页面跳转 | Navigation | 性能好，支持转场动画，返回栈管理方便 |
| 跨模块页面跳转 | Router + main_pages.json | 支持独立生命周期，可作为 Ability 入口 |
| 弹窗/浮层 | Navigation + NavDestination | 可以复用页面栈管理 |
| 深层嵌套页面 | Navigation | 自动管理返回栈，支持手势返回 |

---

## 注意事项

1. **路径格式**
   - `route_map.json` 中的 `pageSourceFile` 使用相对 `src/main` 的路径
   - `main_pages.json` 中的路径不包含 `.ets` 后缀

2. **Builder 函数命名**
   - 必须与 `route_map.json` 中的 `buildFunction` 字段一致
   - 建议使用 `{ComponentName}Builder` 的命名规范

3. **导出声明**
   - Navigation 子页面组件需要 `export` 关键字
   - Router 页面组件需要 `@Entry` 装饰器

4. **模块配置**
   - 确保 `module.json5` 中正确声明了 `routerMap`
   - 修改路由配置后需要重新编译才能生效

5. **Ability 名称匹配（重要）**
   - 使用 `startAbility` 跳转时，`abilityName` 必须与目标模块 `module.json5` 中声明的 Ability `name` 完全一致
   - 常见错误：Ability 名称大小写不匹配、缺少后缀（如 `_featureAbility`）
   - **建议**：在添加新模块跳转前，先检查目标模块 `module.json5` 中的实际 Ability 名称

   **示例对比**：
   | 模块 | 错误的 Ability 名称 | 正确的 Ability 名称 |
   |------|-------------------|-------------------|
   | arkTS | `ArkTSAbility` | `ArkTsAPI_featureAbility` |
   | service | `ServiceAbility` | `Service_featureAbility` |
   | ndkDemo | `NDKDemoAbility` | `NdkDemoAbility` |

## Application 模块分类架构

Application 模块（入口模块）采用分类导航架构，将 23 个功能模块按类别分组：

### 分类结构

```
Index.ets (主页面 - 9个分类按钮)
    │
    ├── 框架模块 (FrameworkCategory)
    │   ├── arkUI - Module1Ability
    │   ├── arkTS - ArkTsAPI_featureAbility
    │   ├── coreFileKit - Core_file_kit_featureAbility
    │   ├── formKit - FormKitAbility
    │   ├── arkWeb - ArkWebAbility
    │   └── stageModel - StageModelAbility
    │
    ├── 系统模块 (SystemCategory)
    │   ├── security - System_featureAbility
    │   └── network - NetworkAbility
    │
    ├── 媒体模块 (MediaCategory)
    │   ├── media - Media_featureAbility
    │   └── scanKit - ScanKitAbility
    │
    ├── 服务模块 (ServiceCategory)
    │   ├── service - Service_featureAbility
    │   └── pushKit - PushKitAbility
    │
    ├── AI 模块 (AICategory)
    │   └── AI - AIAbility
    │
    ├── 图形模块 (GraphicCategory)
    │   └── drawing - DrawingAbility
    │
    ├── 多端开发模块 (MultiDevCategory)
    │   └── multiDevelop - MultiDevelopAbility
    │
    ├── NDK 模块 (NDKCategory)
    │   └── ndkDemo - NdkDemoAbility
    │
    └── 测试模块 (TestCategory)
        ├── test - TestAbility
        └── WeChatShare - WeChatShareAbility
```

### 文件位置

- **主页面**: `application/src/main/ets/pages/Index.ets`
- **分类页面**: `application/src/main/ets/categoryPages/`
  - `FrameworkCategory.ets` - 框架模块分类
  - `SystemCategory.ets` - 系统模块分类
  - `MediaCategory.ets` - 媒体模块分类
  - `ServiceCategory.ets` - 服务模块分类
  - `AICategory.ets` - AI 模块分类
  - `GraphicCategory.ets` - 图形模块分类
  - `MultiDevCategory.ets` - 多端开发模块分类
  - `NDKCategory.ets` - NDK 模块分类
  - `TestCategory.ets` - 测试模块分类
- **路由表**: `application/src/main/resources/base/profile/route_map.json`

### 添加新模块到分类

1. 在对应的分类文件中添加模块按钮配置：
   ```typescript
   "moduleName-AbilityName": '显示名称'
   ```

2. 确保 Ability 名称与目标模块 `module.json5` 中的声明一致

3. 重新编译运行