harmony OS NEXT-Navagation基本用法

# Navagation基本用法

> Navigation组件是路由导航的根视图容器，一般作为Page页面的根容器使用，其内部默认包含了标题栏，内容栏和公工具栏，其中内容区默认首页显示导航内容（Navigation的子组件）或非首页显示（NavDestination的子组件），首页和非首页通过路由进行切换

* 使用Navigation跳转的组件不需要再使用Entry来修饰，普通组件即可
* Navigation是一个导航组件，API9和API11的使用官方推荐方式各不相同

## 1. Navagation API9的用法-(Navigation-NavRouter-(其他组件+NavDestination的用法))

### 1. 1**导航组件层次关系**

| 组件             | 作用                     | 层级规则                  |
| ---------------- | ------------------------ | ------------------------- |
| `Navigation`     | 管理所有导航页面的根容器 | 必须包含多个 `NavRouter`  |
| `NavRouter`      | 定义一个跳转入口         | 必须配对 `NavDestination` |
| `NavDestination` | 目标页面内容             |                           |

### **1. **2 按钮覆盖问题

- **代码现象**：`跳转B` 覆盖 `跳转A`
- **根本原因**：
 在 `NavRouter` 内部放置多个直接同级组件时，仅最后一个组件会被渲染。
- **ArkUI规则**：
 一个 `NavRouter` 只能关联 **一个触发元素** (如Button)，如需多个跳转需使用多个 `NavRouter`。

### 1.3 代码案例

```ts
@Entry
@Component
struct TestNavgationAPI9 {
 build() {

   Navigation() {
     // --------------------- 第一跳转入口 ---------------------
     NavRouter() { // ✅ 触发元素
       Button('跳转A')
       Button('跳转B') //放置的第二个界面会覆盖第一个
       //要跳转的界面
       NavDestination() { // ✅ 目标页面A
         Image($r('app.media.Coverpeople'))
           .width(50)
           .aspectRatio(1)
         // --------------------- 第二跳转入口 ---------------------
         NavRouter() { // ✅ 触发元素
           //第一个组件就是跳转的
           // --------------------- 第二跳转入口 ---------------------
           Text('我跳转啦') // ✅ 目标页面B
           NavDestination() {
             Text('第三个界面') // ✅ 目标页面C
           }

         }

       }

     }

   }
   .height('100%')
   .width('100%')
 }
}
```

### 1.4 效果展示


## 2.Navagation 10的用法

### 2.1 路由栈自主管理

- `NavPathStack`

 核心方法：

 ```ts
 pushPath()    // 压入新页面（保留前页）
 replacePath() // 替换当前页面（销毁前页） 
 pop()         // 回到上一页
 ```

### 2.2 页面加载控制

- **`navDestination(builder)`**
 通过 `Builder` 函数动态渲染路由目标：

* 函数动态渲染路由目标：

```ts
.navDestination(this.navDesBuilder) // 动态路由映射
```

```ts
@Builder
navDesBuilder(name: string) {
 if (name === "pageTwo") {
   NavgationChild02() // 根据 name 组装对应页面
 }
}
```

### 2.3 跨组件通信

- `@Provide` 与 `@Consume` 装饰器

 ```ts
 // 父级定义提供值
 @Provide navPathStack: NavPathStack = new NavPathStack()
 // 子组件自动获取
 @Consume navPathStack: NavPathStack
 ```

 无需显式传递，自动向下注入。

### 2.4 实现步骤

#### 1. 自己管理页面栈 创建一个页面栈 （用@Provide修饰，方便跨组件使用）

```ts
@Provide
 navPathStack: NavPathStack = new NavPathStack()
```

#### 2.将创建的页面栈实例传递给主界面

* `ps`:这一步还是蛮关键的，很多页面不展示就是这个原因

```ts
   Navigation(this.navPathStack) {
     Text('这是第一页-首页')
     Button('去下一页')
       .onClick(() => {
         this.navPathStack.pushPath({
           name: 'pageOne'
         })
       })

   }
   .height('100%')
   .width('100%')
```

#### 3.通过 `Builder` 函数动态渲染路由目标

##### 1. 先创建一个自定义Builder

```ts
 @Builder
 myNavPathStackBuilder(name: string) {
     //根据传入的名字区渲染对应的页面
   if (name === 'pageOne') {
     Children01()

   } else if (name === 'pageTwo') {
     Children02()

   } else if (name === 'pageThree') {
     Children03()

   }
 }

```

##### 2. 传入Builder

```ts
.navDestination(this.navDesBuilder)
```

* 不需要加括号，这里有个底层原因

 1. **ArkUI 的 `navDestination` 机制**

 - **设计逻辑**:框架需要在导航时动态调用构建函数生成页面。若传递this.navDesBuilder()则：
   - 代码执行时**立即运行该函数**（而非按需调用）
   - 返回结果可能为 `void` 或非组件类型，导致**渲染异常**。

 2. **`@Builder` 函数的特性**

 - **延迟执行**：`@Builder` 定义的 UI 编译时会转为**独立闭包代码块**

 - **调用时机**：由 导航框架 在需要时（如`pushPath`）根据name参数触发构建

   ```ts
   this.navPathStack.pushPath({ name: 'pageTwo' });
   // ▶️ 此时 ArkUI 内部通过 `.navDestination` 关联的 Builder 按需执行
   ```

##### 3.跳转的实现

1. 通过点击事件调用当前`navPathStack`实例`pushPath`方法
2. 传入你要跳转页面的名字，进行跳转

```ts
Button('去下一页')
       .onClick(() => {
         this.navPathStack.pushPath({
           name: 'pageOne'
         })
       })
```

#### 4.子界面的定义

```ts
@Component
struct Children01 {
   //接收主界面传递过来的页面栈
 @Consume navPathStack: NavPathStack
 build() {
   NavDestination() {
     Column({ space: 5 }) {
       Text('这是我从主页跳转的第一个界面')
         .fontSize(24)
         .fontWeight(500)
       Button('跳转到第二个页面去')
         .onClick(() => {
           this.navPathStack.pushPath({
             name: 'pageTwo'
           })
         })
     }
   }

 }
}
@Component
struct Children02 {
 @Consume
 navPathStack: NavPathStack

 build() {
   NavDestination() {
     Column({ space: 5 }) {
       Text('这是我从主页跳转的第二个界面')
         .fontSize(24)
         .fontWeight(500)
       Button('跳转到第三个页面去')
         .onClick(() => {
           this.navPathStack.pushPath({
             name: 'pageThree'
           })
         })
     }
   }

 }
}

@Component
struct Children03 {
 @Consume
 navPathStack: NavPathStack

 build() {
   NavDestination() {
     Column() {
       Text('这是我从主页跳转的第三个界面')
         .fontSize(24)
         .fontWeight(500)
     }

   }

 }
}
```

#### 5.效果展示


## 3.NavagationAPI10使用的补充内容

### 3.1 常见的API

| 配置组合          | 代码示例                                                     | 效果描述                            |
| ----------------- | ------------------------------------------------------------ | ----------------------------------- |
| 默认状态          | `Navigation()  .title('主标题')`                             | 标题栏显示 "主标题"，采用 Free 模式 |
| 精简模式+隐藏标题 | `Navigation()  .titleMode(NavigationTitleMode.Mini)  .hideTitleBar(true)` | 标题栏完全不可见                    |
| 子页面独立配置    | `NavDestination()  .title('子页标题')  .hideTitleBar(true)`  |                                     |

### 3.2 传参获取参数的实现

#### 1.定义数据结构

```ts
interface hobby {
 name: string,
 hobby: string
}
```

#### 2.即将跳转页面传入参数

```ts
  NavDestination() {
     Column({ space: 5 }) {
       Text('这是我从主页跳转的第二个界面')
         .fontSize(24)
         .fontWeight(500)
       Button('跳转到第三个页面去')
         .onClick(() => {
           this.navPathStack.pushPath({
             name: 'pageThree',
             param: { name: '猫猫球', hobby: '喜欢玩毛线球' } as hobby
           })
         })
     }
   }
```

#### 3.跳转的页面接收数据

```ts
@Component
struct Children03 {
 @State
 hobby: hobby[] = [] as hobby[]
 @Consume
 navPathStack: NavPathStack

 aboutToAppear(): void {
   this.hobby = this.navPathStack.getParamByName('pageThree') as hobby[]
   promptAction.showToast({
     message: JSON.stringify(this.hobby)
   })
 }

 build() {
   NavDestination() {
     Column() {
       Text('这是我从主页跳转的第三个界面')
       Text('这是我获取的数据')
       Text(this.hobby[0].name)
       Text(this.hobby[0].hobby)
         .fontWeight(500)
     }

   }

 }
}
```

#### 4.效果展示



审核编辑 黄宇