1# 组件导航 (Navigation)(推荐) 2 3组件导航（Navigation）主要用于实现页面间以及组件内部的页面跳转，支持在不同组件间传递跳转参数，提供灵活的跳转栈操作，从而更便捷地实现对不同页面的访问和复用。本文将从组件导航（Navigation）的显示模式、路由操作、子页面管理、跨包跳转以及跳转动效等几个方面进行详细介绍。 4 5[Navigation](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md)是路由导航的根视图容器，一般作为页面（@Entry）的根容器，包括单栏（Stack）、分栏（Split）和自适应（Auto）三种显示模式。Navigation组件适用于模块内和跨模块的路由切换，通过组件级路由能力实现更加自然流畅的转场体验，并提供多种标题栏样式来呈现更好的标题和内容联动效果。一次开发，多端部署场景下，Navigation组件能够自动适配窗口显示大小，在窗口较大的场景下自动切换分栏展示效果。 6 7Navigation组件主要包含导航页和子页。导航页由标题栏（包含菜单栏）、内容区和工具栏组成，可以通过[hideNavBar](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#hidenavbar9)属性进行隐藏，导航页不存在页面栈中，与子页，以及子页之间可以通过路由操作进行切换。 8 9在API Version 9上，Navigation需要配合[NavRouter](../reference/apis-arkui/arkui-ts/ts-basic-components-navrouter.md)组件实现页面路由。从API Version 10开始，更推荐使用[NavPathStack](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navpathstack10)实现页面路由。 10 11 12## 设置页面显示模式 13 14Navigation组件通过mode属性设置页面的显示模式。 15 16- 自适应模式 17 18 Navigation组件默认为自适应模式，此时mode属性为NavigationMode.Auto。自适应模式下，当页面宽度大于等于一定阈值( API version 9及以前：520vp，API version 10及以后：600vp )时，Navigation组件采用分栏模式，反之采用单栏模式。 19 20 21 ``` 22 Navigation() { 23 // ... 24 } 25 .mode(NavigationMode.Auto) 26 ``` 27 28- 单页面模式 29 30 **图1** 单页面布局示意图 31 32  33 34 将mode属性设置为NavigationMode.Stack，Navigation组件即可设置为单页面显示模式。 35 36 37 ```ts 38 Navigation() { 39 // ... 40 } 41 .mode(NavigationMode.Stack) 42 ``` 43 44  45 46- 分栏模式 47 48 **图2** 分栏布局示意图 49 50  51 52 将mode属性设置为NavigationMode.Split，Navigation组件即可设置为分栏显示模式。 53 54 55 ```ts 56 @Entry 57 @Component 58 struct NavigationExample { 59 @State TooTmp: ToolbarItem = { 60 'value': "func", 'icon': "./image/ic_public_highlights.svg", 'action': () => { 61 } 62 } 63 @Provide('pageInfos') pageInfos: NavPathStack = new NavPathStack() 64 private arr: number[] = [1, 2, 3]; 65 66 @Builder 67 PageMap(name: string) { 68 if (name === "NavDestinationTitle1") { 69 pageOneTmp() 70 } else if (name === "NavDestinationTitle2") { 71 pageTwoTmp() 72 } else if (name === "NavDestinationTitle3") { 73 pageThreeTmp() 74 } 75 } 76 77 build() { 78 Column() { 79 Navigation(this.pageInfos) { 80 TextInput({ placeholder: 'search...' }) 81 .width("90%") 82 .height(40) 83 .backgroundColor('#FFFFFF') 84 85 List({ space: 12 }) { 86 ForEach(this.arr, (item: number) => { 87 ListItem() { 88 Text("Page" + item) 89 .width("100%") 90 .height(72) 91 .backgroundColor('#FFFFFF') 92 .borderRadius(24) 93 .fontSize(16) 94 .fontWeight(500) 95 .textAlign(TextAlign.Center) 96 .onClick(() => { 97 this.pageInfos.pushPath({ name: "NavDestinationTitle" + item }) 98 }) 99 } 100 }, (item: number) => item.toString()) 101 } 102 .width("90%") 103 .margin({ top: 12 }) 104 } 105 .title("主标题") 106 .mode(NavigationMode.Split) 107 .navDestination(this.PageMap) 108 .menus([ 109 { 110 value: "", icon: "./image/ic_public_search.svg", action: () => { 111 } 112 }, 113 { 114 value: "", icon: "./image/ic_public_add.svg", action: () => { 115 } 116 }, 117 { 118 value: "", icon: "./image/ic_public_add.svg", action: () => { 119 } 120 }, 121 { 122 value: "", icon: "./image/ic_public_add.svg", action: () => { 123 } 124 }, 125 { 126 value: "", icon: "./image/ic_public_add.svg", action: () => { 127 } 128 } 129 ]) 130 .toolbarConfiguration([this.TooTmp, this.TooTmp, this.TooTmp]) 131 } 132 .height('100%') 133 .width('100%') 134 .backgroundColor('#F1F3F5') 135 } 136 } 137 138 // PageOne.ets 139 @Component 140 export struct pageOneTmp { 141 @Consume('pageInfos') pageInfos: NavPathStack; 142 143 build() { 144 NavDestination() { 145 Column() { 146 Text("NavDestinationContent1") 147 }.width('100%').height('100%') 148 }.title("NavDestinationTitle1") 149 .onBackPressed(() => { 150 const popDestinationInfo = this.pageInfos.pop() // 弹出路由栈栈顶元素 151 console.log('pop' + '返回值' + JSON.stringify(popDestinationInfo)) 152 return true 153 }) 154 } 155 } 156 157 // PageTwo.ets 158 @Component 159 export struct pageTwoTmp { 160 @Consume('pageInfos') pageInfos: NavPathStack; 161 162 build() { 163 NavDestination() { 164 Column() { 165 Text("NavDestinationContent2") 166 }.width('100%').height('100%') 167 }.title("NavDestinationTitle2") 168 .onBackPressed(() => { 169 const popDestinationInfo = this.pageInfos.pop() // 弹出路由栈栈顶元素 170 console.log('pop' + '返回值' + JSON.stringify(popDestinationInfo)) 171 return true 172 }) 173 } 174 } 175 176 // PageThree.ets 177 @Component 178 export struct pageThreeTmp { 179 @Consume('pageInfos') pageInfos: NavPathStack; 180 181 build() { 182 NavDestination() { 183 Column() { 184 Text("NavDestinationContent3") 185 }.width('100%').height('100%') 186 }.title("NavDestinationTitle3") 187 .onBackPressed(() => { 188 const popDestinationInfo = this.pageInfos.pop() // 弹出路由栈栈顶元素 189 console.log('pop' + '返回值' + JSON.stringify(popDestinationInfo)) 190 return true 191 }) 192 } 193 } 194 ``` 195 196  197 198 199## 设置标题栏模式 200 201标题栏在界面顶部，用于呈现界面名称和操作入口，Navigation组件通过titleMode属性设置标题栏模式。 202 203> **说明：** 204> Navigation或NavDestination未设置主副标题并且没有返回键时，不显示标题栏。 205 206- Mini模式 207 208 普通型标题栏，用于一级页面不需要突出标题的场景。 209 210 **图3** Mini模式标题栏 211 212  213 214 215 ```ts 216 Navigation() { 217 // ... 218 } 219 .titleMode(NavigationTitleMode.Mini) 220 ``` 221 222 223- Full模式 224 225 强调型标题栏，用于一级页面需要突出标题的场景。 226 227 **图4** Full模式标题栏 228 229  230 231 232 ```ts 233 Navigation() { 234 // ... 235 } 236 .titleMode(NavigationTitleMode.Full) 237 ``` 238 239 240## 设置菜单栏 241 242菜单栏位于Navigation组件的右上角，开发者可以通过menus属性进行设置。menus支持Array<[NavigationMenuItem](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navigationmenuitem)>和[CustomBuilder](../reference/apis-arkui/arkui-ts/ts-types.md#custombuilder8)两种参数类型。使用Array<NavigationMenuItem>类型时，竖屏最多支持显示3个图标，横屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。 243 244**图5** 设置了3个图标的菜单栏 245 246 247 248```ts 249let TooTmp: NavigationMenuItem = {'value': "", 'icon': "./image/ic_public_highlights.svg", 'action': ()=> {}} 250Navigation() { 251 // ... 252} 253.menus([TooTmp, 254 TooTmp, 255 TooTmp]) 256``` 257 258图片也可以引用resources中的资源。 259 260```ts 261let TooTmp: NavigationMenuItem = {'value': "", 'icon': "resources/base/media/ic_public_highlights.svg", 'action': ()=> {}} 262Navigation() { 263 // ... 264} 265.menus([TooTmp, 266 TooTmp, 267 TooTmp]) 268``` 269 270**图6** 设置了4个图标的菜单栏 271 272 273 274```ts 275let TooTmp: NavigationMenuItem = {'value': "", 'icon': "./image/ic_public_highlights.svg", 'action': ()=> {}} 276Navigation() { 277 // ... 278} 279// 竖屏最多支持显示3个图标，多余的图标会被放入自动生成的更多图标。 280.menus([TooTmp, 281 TooTmp, 282 TooTmp, 283 TooTmp]) 284``` 285 286 287## 设置工具栏 288 289工具栏位于Navigation组件的底部，开发者可以通过[toolbarConfiguration](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#toolbarconfiguration10)属性进行设置。 290 291 292 **图7** 工具栏 293 294 295 296```ts 297let TooTmp: ToolbarItem = {'value': "func", 'icon': "./image/ic_public_highlights.svg", 'action': ()=> {}} 298let TooBar: ToolbarItem[] = [TooTmp,TooTmp,TooTmp] 299Navigation() { 300 // ... 301} 302.toolbarConfiguration(TooBar) 303``` 304 305## 路由操作 306 307Navigation路由相关的操作都是基于页面栈[NavPathStack](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navpathstack10)提供的方法进行，每个Navigation都需要创建并传入一个NavPathStack对象，用于管理页面。主要涉及页面跳转、页面返回、页面替换、页面删除、参数获取、路由拦截等功能。 308 309从API version 12开始，页面栈允许被继承。开发者可以在派生类中自定义属性和方法，也可以重写父类的方法。派生类对象可以替代基类NavPathStack对象使用。具体示例代码参见：[页面栈继承示例代码](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#示例10定义路由栈派生类)。 310 311> **说明：** 312> 313> 不建议开发者通过监听生命周期的方式管理自己的页面栈。 314 315```ts 316@Entry 317@Component 318struct Index { 319 // 创建一个页面栈对象并传入Navigation 320 pageStack: NavPathStack = new NavPathStack() 321 322 build() { 323 Navigation(this.pageStack) { 324 } 325 .title('Main') 326 } 327} 328``` 329 330### 页面跳转 331 332NavPathStack通过Push相关的接口去实现页面跳转的功能，主要分为以下三类: 333 3341. 普通跳转，通过页面的name去跳转，并可以携带param。 335 336 ```ts 337 this.pageStack.pushPath({ name: "PageOne", param: "PageOne Param" }) 338 this.pageStack.pushPathByName("PageOne", "PageOne Param") 339 ``` 340 3412. 带返回回调的跳转，跳转时添加onPop回调，能在页面出栈时获取返回信息，并进行处理。 342 343 ```ts 344 this.pageStack.pushPathByName('PageOne', "PageOne Param", (popInfo) => { 345 console.log('Pop page name is: ' + popInfo.info.name + ', result: ' + JSON.stringify(popInfo.result)) 346 }); 347 ``` 348 3493. 带错误码的跳转，跳转结束会触发异步回调，返回错误码信息。 350 351 ```ts 352 this.pageStack.pushDestination({name: "PageOne", param: "PageOne Param"}) 353 .catch((error: BusinessError) => { 354 console.error(`Push destination failed, error code = ${error.code}, error.message = ${error.message}.`); 355 }).then(() => { 356 console.info('Push destination succeed.'); 357 }); 358 this.pageStack.pushDestinationByName("PageOne", "PageOne Param") 359 .catch((error: BusinessError) => { 360 console.error(`Push destination failed, error code = ${error.code}, error.message = ${error.message}.`); 361 }).then(() => { 362 console.info('Push destination succeed.'); 363 }); 364 ``` 365 366### 页面返回 367 368NavPathStack通过Pop相关接口去实现页面返回功能。 369 370```ts 371// 返回到上一页 372this.pageStack.pop() 373// 返回到上一个PageOne页面 374this.pageStack.popToName("PageOne") 375// 返回到索引为1的页面 376this.pageStack.popToIndex(1) 377// 返回到根首页（清除栈中所有页面） 378this.pageStack.clear() 379``` 380 381### 页面替换 382 383NavPathStack通过Replace相关接口去实现页面替换功能。 384 385```ts 386// 将栈顶页面替换为PageOne 387this.pageStack.replacePath({ name: "PageOne", param: "PageOne Param" }) 388this.pageStack.replacePathByName("PageOne", "PageOne Param") 389// 带错误码的替换，跳转结束会触发异步回调，返回错误码信息 390this.pageStack.replaceDestination({name: "PageOne", param: "PageOne Param"}) 391 .catch((error: BusinessError) => { 392 console.error(`Replace destination failed, error code = ${error.code}, error.message = ${error.message}.`); 393 }).then(() => { 394 console.info('Replace destination succeed.'); 395 }) 396``` 397 398### 页面删除 399 400NavPathStack通过Remove相关接口去实现删除页面栈中特定页面的功能。 401 402```ts 403// 删除栈中name为PageOne的所有页面 404this.pageStack.removeByName("PageOne") 405// 删除指定索引的页面 406this.pageStack.removeByIndexes([1,3,5]) 407// 删除指定id的页面 408this.pageStack.removeByNavDestinationId("1"); 409``` 410 411### 移动页面 412 413NavPathStack通过Move相关接口去实现移动页面栈中特定页面到栈顶的功能。 414 415```ts 416// 移动栈中name为PageOne的页面到栈顶 417this.pageStack.moveToTop("PageOne"); 418// 移动栈中索引为1的页面到栈顶 419this.pageStack.moveIndexToTop(1); 420``` 421 422### 参数获取 423 424NavPathStack通过Get相关接口去获取页面的一些参数。 425 426```ts 427// 获取栈中所有页面name集合 428this.pageStack.getAllPathName() 429// 获取索引为1的页面参数 430this.pageStack.getParamByIndex(1) 431// 获取PageOne页面的参数 432this.pageStack.getParamByName("PageOne") 433// 获取PageOne页面的索引集合 434this.pageStack.getIndexByName("PageOne") 435``` 436 437### 路由拦截 438 439NavPathStack提供了[setInterception](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#setinterception12)方法，用于设置Navigation页面跳转拦截回调。该方法需要传入一个NavigationInterception对象，该对象包含三个回调函数： 440 441| 名称 | 描述 | 442| ------------ | ------------------------------------------------------ | 443| willShow | 页面跳转前回调，允许操作栈，在当前跳转生效。 | 444| didShow | 页面跳转后回调，在该回调中操作栈会在下一次跳转生效。 | 445| modeChange | Navigation单双栏显示状态发生变更时触发该回调。 | 446 447> **说明：** 448> 449> 无论是哪个回调，在进入回调时页面栈都已经发生了变化。 450 451开发者可以在willShow回调中通过修改路由栈来实现路由拦截重定向的能力。 452 453```ts 454this.pageStack.setInterception({ 455 willShow: (from: NavDestinationContext | "navBar", to: NavDestinationContext | "navBar", 456 operation: NavigationOperation, animated: boolean) => { 457 if (typeof to === "string") { 458 console.log("target page is navigation home page."); 459 return; 460 } 461 // 将跳转到PageTwo的路由重定向到PageOne 462 let target: NavDestinationContext = to as NavDestinationContext; 463 if (target.pathInfo.name === 'PageTwo') { 464 target.pathStack.pop(); 465 target.pathStack.pushPathByName('PageOne', null); 466 } 467 } 468}) 469``` 470 471### 单例跳转 472 473通过设置[LaunchMode](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#launchmode12枚举说明)为LaunchMode.MOVE_TO_TOP_SINGLETON或LaunchMode.POP_TO_SINGLETON，可以实现Navigation路由栈的单实例跳转。单实例跳转的规则如下： 474 4751. 当指定为LaunchMode.MOVE_TO_TOP_SINGLETON时，系统会从栈底到栈顶查找具有指定名称的NavDestination。找到后，该页面将被移动到栈顶（replace操作会用指定的NavDestination替换当前栈顶）。 4762. 若指定为LaunchMode.POP_TO_SINGLETON，系统同样会从栈底到栈顶查找具有指定名称的NavDestination。找到后，便会移除该NavDestination上方的所有页面（replace操作会用指定的NavDestination替换当前栈顶）。 477 478有关单实例路由栈操作的示例代码，可以参考[Navigation单例跳转示例](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#示例2使用路由栈方法)。 479 480## 子页面 481 482[NavDestination](../reference/apis-arkui/arkui-ts/ts-basic-components-navdestination.md)是Navigation子页面的根容器，用于承载子页面的一些特殊属性以及生命周期等。NavDestination可以设置独立的标题栏和菜单栏等属性，使用方法与Navigation相同。NavDestination也可以通过mode属性设置不同的显示类型，用于满足不同页面的诉求。 483 484### 页面显示类型 485 486- 标准类型 487 488 NavDestination组件默认为标准类型，此时mode属性为NavDestinationMode.STANDARD。标准类型的NavDestination的生命周期跟随其在NavPathStack页面栈中的位置变化而改变。 489 490- 弹窗类型 491 492 NavDestination设置mode为NavDestinationMode.DIALOG弹窗类型，此时整个NavDestination默认透明显示。弹窗类型的NavDestination显示和消失时不会影响下层标准类型的NavDestination的显示和生命周期，两者可以同时显示。 493 494 ```ts 495 // Dialog NavDestination 496 @Entry 497 @Component 498 struct Index { 499 @Provide('NavPathStack') pageStack: NavPathStack = new NavPathStack() 500 501 @Builder 502 PagesMap(name: string) { 503 if (name == 'DialogPage') { 504 DialogPage() 505 } 506 } 507 508 build() { 509 Navigation(this.pageStack) { 510 Button('Push DialogPage') 511 .margin(20) 512 .width('80%') 513 .onClick(() => { 514 this.pageStack.pushPathByName('DialogPage', ''); 515 }) 516 } 517 .mode(NavigationMode.Stack) 518 .title('Main') 519 .navDestination(this.PagesMap) 520 } 521 } 522 523 @Component 524 export struct DialogPage { 525 @Consume('NavPathStack') pageStack: NavPathStack; 526 527 build() { 528 NavDestination() { 529 Stack({ alignContent: Alignment.Center }) { 530 Column() { 531 Text("Dialog NavDestination") 532 .fontSize(20) 533 .margin({ bottom: 100 }) 534 Button("Close").onClick(() => { 535 this.pageStack.pop() 536 }).width('30%') 537 } 538 .justifyContent(FlexAlign.Center) 539 .backgroundColor(Color.White) 540 .borderRadius(10) 541 .height('30%') 542 .width('80%') 543 }.height("100%").width('100%') 544 } 545 .backgroundColor('rgba(0,0,0,0.5)') 546 .hideTitleBar(true) 547 .mode(NavDestinationMode.DIALOG) 548 } 549 } 550 ``` 551  552 553### 页面生命周期 554 555Navigation作为路由容器，其生命周期承载在NavDestination组件上，以组件事件的形式开放。 556 557其生命周期大致可分为三类，自定义组件生命周期、通用组件生命周期和自有生命周期。其中，[aboutToAppear](../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#abouttoappear)和[aboutToDisappear](../reference/apis-arkui/arkui-ts/ts-custom-component-lifecycle.md#abouttodisappear)是自定义组件的生命周期(NavDestination外层包含的自定义组件)，[OnAppear](../reference/apis-arkui/arkui-ts/ts-universal-events-show-hide.md#onappear)和[OnDisappear](../reference/apis-arkui/arkui-ts/ts-universal-events-show-hide.md#ondisappear)是组件的通用生命周期。剩下的生命周期为NavDestination独有。 558 559生命周期时序如下图所示： 560 561 562 563- **aboutToAppear**：在创建自定义组件后，执行其build()函数之前执行（NavDestination创建之前），允许在该方法中改变状态变量，更改将在后续执行build()函数中生效。 564- **onWillAppear**：NavDestination创建后，挂载到组件树之前执行，在该方法中更改状态变量会在当前帧显示生效。 565- **onAppear**：通用生命周期事件，NavDestination组件挂载到组件树时执行。 566- **onWillShow**：NavDestination组件布局显示之前执行，此时页面不可见（应用切换到前台不会触发）。 567- **onShown**：NavDestination组件布局显示之后执行，此时页面已完成布局。 568- **onActive**: NavDestination处于激活态（处于栈顶可操作，且上层无特殊组件遮挡）触发。 569- **onWillHide**：NavDestination组件触发隐藏之前执行（应用切换到后台不会触发）。 570- **onInactive**: NavDestination组件处于非激活态（处于非栈顶不可操作，或处于栈顶时上层有特殊组件遮挡）触发。 571- **onHidden**：NavDestination组件触发隐藏后执行（非栈顶页面push进栈，栈顶页面pop出栈或应用切换到后台）。 572- **onWillDisappear**：NavDestination组件即将销毁之前执行，如果有转场动画，会在动画前触发（栈顶页面pop出栈）。 573- **onDisappear**：通用生命周期事件，NavDestination组件从组件树上卸载销毁时执行。 574- **aboutToDisappear**：自定义组件析构销毁之前执行，不允许在该方法中改变状态变量。 575 576### 页面监听和查询 577 578为了方便组件跟页面解耦，在NavDestination子页面内部的自定义组件可以通过全局方法监听或查询到页面的一些状态信息。 579 580- 页面信息查询 581 582 自定义组件提供[queryNavDestinationInfo](../reference/apis-arkui/arkui-ts/ts-custom-component-api.md#querynavdestinationinfo)方法，可以在NavDestination内部查询到当前所属页面的信息，返回值为[NavDestinationInfo](../reference/apis-arkui/js-apis-arkui-observer.md#navdestinationinfo)，若查询不到则返回undefined。 583 584 ```ts 585 import { uiObserver } from '@kit.ArkUI'; 586 587 // NavDestination内的自定义组件 588 @Component 589 struct MyComponent { 590 navDesInfo: uiObserver.NavDestinationInfo | undefined 591 592 aboutToAppear(): void { 593 this.navDesInfo = this.queryNavDestinationInfo(); 594 } 595 596 build() { 597 Column() { 598 Text("所属页面Name: " + this.navDesInfo?.name) 599 }.width('100%').height('100%') 600 } 601 } 602 ``` 603- 页面状态监听 604 605 通过[observer.on('navDestinationUpdate')](../reference/apis-arkui/js-apis-arkui-observer.md#observeronnavdestinationupdate)提供的注册接口可以注册NavDestination生命周期变化的监听，使用方式如下： 606 607 ```ts 608 uiObserver.on('navDestinationUpdate', (info) => { 609 console.info('NavDestination state update', JSON.stringify(info)); 610 }); 611 ``` 612 613 也可以注册页面切换的状态回调，能在页面发生路由切换的时候拿到对应的页面信息[NavDestinationSwitchInfo](..//reference/apis-arkui/js-apis-arkui-observer.md#navdestinationswitchinfo12)，并且提供了UIAbilityContext和UIContext不同范围的监听： 614 615 ```ts 616 // 在UIAbility中使用 617 import { UIContext, uiObserver } from '@kit.ArkUI'; 618 619 // callBackFunc 是开发者定义的监听回调函数 620 function callBackFunc(info: uiObserver.NavDestinationSwitchInfo) {} 621 uiObserver.on('navDestinationSwitch', this.context, callBackFunc); 622 623 // 可以通过窗口的getUIContext()方法获取对应的UIContent 624 uiContext: UIContext | null = null; 625 uiObserver.on('navDestinationSwitch', this.uiContext, callBackFunc); 626 ``` 627 628## 页面转场 629 630Navigation默认提供了页面切换的转场动画，通过页面栈操作时，会触发不同的转场效果（API version 13之前，Dialog类型的页面默认无转场动画。从API version13开始，Dialog类型的页面支持系统转场动画。），Navigation也提供了关闭系统转场、自定义转场以及共享元素转场的能力。 631 632### 关闭转场 633 634- 全局关闭 635 636 Navigation通过NavPathStack中提供的[disableAnimation](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#disableanimation11)方法可以在当前Navigation中关闭或打开所有转场动画。 637 ```ts 638 pageStack: NavPathStack = new NavPathStack() 639 640 aboutToAppear(): void { 641 this.pageStack.disableAnimation(true) 642 } 643 ``` 644- 单次关闭 645 646 NavPathStack中提供的Push、Pop、Replace等接口中可以设置animated参数，默认为true表示有转场动画，需要单次关闭转场动画可以置为false，不影响下次转场动画。 647 ```ts 648 pageStack: NavPathStack = new NavPathStack() 649 650 this.pageStack.pushPath({ name: "PageOne" }, false) 651 this.pageStack.pop(false) 652 ``` 653 654### 自定义转场 655 656- Navigation自定义转场 657 658 Navigation自定义转场动画能力通过[customNavContentTransition](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#customnavcontenttransition11)事件提供，可以通过以下三步定义自定义转场动画： 659 660 1. 构建一个自定义转场动画工具类CustomNavigationUtils，通过一个Map管理各页面的自定义动画对象CustomTransition。页面在创建时注册其自定义转场动画对象，在销毁时取消注册。 661 2. 实现一个转场协议对象[NavigationAnimatedTransition](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navigationanimatedtransition11)。其中，timeout属性表示转场结束的超时时间，默认为1000ms，transition属性为自定义的转场动画方法。开发者需在此实现自己的转场动画逻辑，系统在转场开始时会调用此方法，onTransitionEnd为转场结束时的回调。 662 3. 调用customNavContentTransition方法并返回实现的转场协议对象，若返回undefined，则使用系统默认转场。 663 664 具体示例代码可参考[Navigation自定义转场示例](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#示例3设置可交互转场动画)。 665 666- NavDestination自定义转场 667 668 NavDestination支持自定义转场动画，通过设置[customTransition](../reference/apis-arkui/arkui-ts/ts-basic-components-navdestination.md#customtransition15)属性即可实现单个页面的自定义转场效果。要实现这一功能，需完成以下步骤： 669 670 1. 实现[NavDestination的转场代理](../reference/apis-arkui/arkui-ts/ts-basic-components-navdestination.md#navdestinationtransitiondelegate15)，针对不同的堆栈操作类型返回自定义的转场协议对象[NavDestinationTransition](../reference/apis-arkui/arkui-ts/ts-basic-components-navdestination.md#navdestinationtransition15)。其中，event是必填参数，需在此处编写自定义转场动画的逻辑；而onTransitionEnd、duration、curve与delay为可选参数，分别对应动画结束后的回调、动画持续时间、动画曲线类型与开始前的延时。若在转场代理中返回多个转场协议对象，这些动画效果将逐层叠加。 671 2. 通过调用NavDestination组件的customTransition属性，并传入上述实现的转场代理，完成自定义转场的设置。 672 673 具体示例代码可以参考[NavDestination自定义转场示例](../reference/apis-arkui/arkui-ts/ts-basic-components-navdestination.md#示例2设置navdestination自定义转场)。 674 675### 共享元素转场 676 677NavDestination之间切换时可以通过[geometryTransition](../reference/apis-arkui/arkui-ts/ts-transition-animation-geometrytransition.md#geometrytransition)实现共享元素转场。配置了共享元素转场的页面同时需要关闭系统默认的转场动画。 6781. 为需要实现共享元素转场的组件添加geometryTransition属性，id参数必须在两个NavDestination之间保持一致。 679 680 ```ts 681 // 起始页配置共享元素id 682 NavDestination() { 683 Column() { 684 // ... 685 Image($r('app.media.startIcon')) 686 .geometryTransition('sharedId') 687 .width(100) 688 .height(100) 689 } 690 } 691 .title('FromPage') 692 693 // 目的页配置共享元素id 694 NavDestination() { 695 Column() { 696 // ... 697 Image($r('app.media.startIcon')) 698 .geometryTransition('sharedId') 699 .width(200) 700 .height(200) 701 } 702 } 703 .title('ToPage') 704 ``` 705 7062. 将页面路由的操作，放到animateTo动画闭包中，配置对应的动画参数以及关闭系统默认的转场。 707 708 ```ts 709 NavDestination() { 710 Column() { 711 Button('跳转目的页') 712 .width('80%') 713 .height(40) 714 .margin(20) 715 .onClick(() => { 716 this.getUIContext()?.animateTo({ duration: 1000 }, () => { 717 this.pageStack.pushPath({ name: 'ToPage' }, false) 718 }) 719 }) 720 } 721 } 722 .title('FromPage') 723 ``` 724 725## 跨包动态路由 726 727通过静态import页面再进行路由跳转的方式会造成不同模块之间的依赖耦合，以及首页加载时间长等问题。 728 729动态路由设计的初衷旨在解决多个模块（HAR/HSP）能够复用相同的业务逻辑，实现各业务模块间的解耦，同时支持路由功能的扩展与整合。 730 731**动态路由的优势：** 732 733- 路由定义除了跳转的URL以外，可以丰富的配置扩展信息，如横竖屏默认模式，是否需要鉴权等等，做路由跳转时统一处理。 734- 给每个路由页面设置一个名字，按照名称进行跳转而不是文件路径。 735- 页面的加载可以使用动态import（按需加载），防止首个页面加载大量代码导致卡顿。 736 737动态路由提供[系统路由表](#系统路由表)和[自定义路由表](#自定义路由表)两种实现方式。 738 739- 系统路由表相对自定义路由表，使用更简单，只需要添加对应页面跳转配置项，即可实现页面跳转。 740 741- 自定义路由表使用起来更复杂，但是可以根据应用业务进行定制处理。 742 743支持自定义路由表和系统路由表混用。 744 745### 系统路由表 746 747系统路由表是动态路由的一种实现方式。从API version 12开始，Navigation支持使用系统路由表的方式进行动态路由。各业务模块（[HSP](../quick-start/in-app-hsp.md)/[HAR](../quick-start/har-package.md)）中需要独立配置route_map.json文件，在触发路由跳转时，应用只需要通过NavPathStack提供的路由方法，传入需要路由的页面配置名称，此时系统会自动完成路由模块的动态加载、页面组件构建，并完成路由跳转，从而实现了开发层面的模块解耦。系统路由表不支持预览器及模拟器。其主要步骤如下： 748 7491. 在跳转目标模块的配置文件module.json5添加路由表配置： 750 751 ```json 752 { 753 "module" : { 754 "routerMap": "$profile:route_map" 755 } 756 } 757 ``` 7582. 添加完路由配置文件地址后，需要在工程resources/base/profile中创建route_map.json文件。添加如下配置信息： 759 760 ```json 761 { 762 "routerMap": [ 763 { 764 "name": "PageOne", 765 "pageSourceFile": "src/main/ets/pages/PageOne.ets", 766 "buildFunction": "PageOneBuilder", 767 "data": { 768 "description" : "this is PageOne" 769 } 770 } 771 ] 772 } 773 ``` 774 775 配置说明如下： 776 777 | 配置项 | 说明 | 778 |---|---| 779 | name | 跳转页面名称。| 780 | pageSourceFile | 跳转目标页在包内的路径，相对src目录的相对路径。| 781 | buildFunction | 跳转目标页的入口函数名称，必须以@Builder修饰。 | 782 | data | 应用自定义字段。可以通过配置项读取接口getConfigInRouteMap获取。| 783 7843. 在跳转目标页面中，需要配置入口Builder函数，函数名称需要和route_map.json配置文件中的buildFunction保持一致，否则在编译时会报错。 785 786 ```ts 787 // 跳转页面入口函数 788 @Builder 789 export function PageOneBuilder() { 790 PageOne() 791 } 792 793 @Component 794 struct PageOne { 795 pathStack: NavPathStack = new NavPathStack() 796 797 build() { 798 NavDestination() { 799 } 800 .title('PageOne') 801 .onReady((context: NavDestinationContext) => { 802 this.pathStack = context.pathStack 803 }) 804 } 805 } 806 ``` 8074. 通过pushPathByName等路由接口进行页面跳转。(注意：此时Navigation中可以不用配置navDestination属性。) 808 809 ```ts 810 @Entry 811 @Component 812 struct Index { 813 pageStack : NavPathStack = new NavPathStack(); 814 815 build() { 816 Navigation(this.pageStack){ 817 }.onAppear(() => { 818 this.pageStack.pushPathByName("PageOne", null, false); 819 }) 820 .hideNavBar(true) 821 } 822 } 823 ``` 824 825### 自定义路由表 826 827自定义路由表是动态路由的一种实现方式。开发者可以通过自定义路由表的方式来实现跨包动态路由，具体实现方法请参考<!--RP1-->[Navigation自定义动态路由](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/ApplicationModels/DynamicRouter)<!--RP1End--> 示例。 828 829**实现方案：** 830 8311. 定义页面跳转配置项。 832 - 使用资源文件进行定义，通过资源管理[@ohos.resourceManager](../reference/apis-localization-kit/js-apis-resource-manager.md)在运行时对资源文件解析。 833 - 在ets文件中配置路由加载配置项，一般包括路由页面名称（即pushPath等接口中页面的别名），文件所在模块名称（hsp/har的模块名），加载页面在模块内的路径（相对src目录的路径）。 8342. 加载目标跳转页面，通过[动态import](../arkts-utils/arkts-dynamic-import.md)将跳转目标页面所在的模块在运行时加载，在模块加载完成后，调用模块中的方法，通过import在模块的方法中加载模块中显示的目标页面，并返回页面加载完成后定义的Builder函数。 8353. 触发页面跳转，在Navigation的[navDestination](../reference/apis-arkui/arkui-ts/ts-basic-components-navigation.md#navdestination10)属性执行步骤2中加载的Builder函数，即可跳转到目标页面。 836<!--RP2--><!--RP2End-->
