1# @ohos.router (页面路由) 2 3本模块提供通过不同的url访问不同的页面，包括跳转到应用内的指定页面、用应用内的某个页面替换当前页面、返回上一页面或指定的页面等。 4 5> **说明** 6> 7> - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - 页面路由需要在页面渲染完成之后才能调用，在onInit和onReady生命周期中页面还处于渲染阶段，禁止调用页面路由方法。 10 11## 导入模块 12 13``` 14import router from '@ohos.router' 15``` 16 17## router.pushUrl<sup>9+</sup> 18 19pushUrl(options: RouterOptions): Promise<void> 20 21跳转到应用内的指定页面。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------- | ------------------------------- | ---- | --------- | 29| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 30 31**返回值：** 32 33| 类型 | 说明 | 34| ------------------- | --------- | 35| Promise<void> | 异常返回结果。 | 36 37**错误码：** 38 39以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 40 41| 错误码ID | 错误信息 | 42| --------- | ------- | 43| 100001 | if UI execution context not found. | 44| 100002 | if the uri is not exist. | 45| 100003 | if the pages are pushed too much. | 46 47**示例：** 48 49```js 50router.pushUrl({ 51 url: 'pages/routerpage2', 52 params: { 53 data1: 'message', 54 data2: { 55 data3: [123, 456, 789] 56 } 57 } 58}) 59 .then(() => { 60 // success 61 }) 62 .catch(err => { 63 console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); 64 }) 65``` 66 67## router.pushUrl<sup>9+</sup> 68 69pushUrl(options: RouterOptions, callback: AsyncCallback<void>): void 70 71跳转到应用内的指定页面。 72 73**系统能力：** SystemCapability.ArkUI.ArkUI.Full 74 75**参数：** 76 77| 参数名 | 类型 | 必填 | 说明 | 78| ------- | ------------------------------- | ---- | --------- | 79| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 80| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 81 82**错误码：** 83 84以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 85 86| 错误码ID | 错误信息 | 87| --------- | ------- | 88| 100001 | if UI execution context not found. | 89| 100002 | if the uri is not exist. | 90| 100003 | if the pages are pushed too much. | 91 92**示例：** 93 94```js 95router.pushUrl({ 96 url: 'pages/routerpage2', 97 params: { 98 data1: 'message', 99 data2: { 100 data3: [123, 456, 789] 101 } 102 } 103}, (err) => { 104 if (err) { 105 console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); 106 return; 107 } 108 console.info('pushUrl success'); 109}); 110``` 111## router.pushUrl<sup>9+</sup> 112 113pushUrl(options: RouterOptions, mode: RouterMode): Promise<void> 114 115跳转到应用内的指定页面。 116 117**系统能力：** SystemCapability.ArkUI.ArkUI.Full 118 119**参数：** 120 121| 参数名 | 类型 | 必填 | 说明 | 122| ------- | ------------------------------- | ---- | ---------- | 123| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 124| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 125 126**返回值：** 127 128| 类型 | 说明 | 129| ------------------- | --------- | 130| Promise<void> | 异常返回结果。 | 131 132**错误码：** 133 134以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 135 136| 错误码ID | 错误信息 | 137| --------- | ------- | 138| 100001 | if UI execution context not found. | 139| 100002 | if the uri is not exist. | 140| 100003 | if the pages are pushed too much. | 141 142**示例：** 143 144```js 145router.pushUrl({ 146 url: 'pages/routerpage2', 147 params: { 148 data1: 'message', 149 data2: { 150 data3: [123, 456, 789] 151 } 152 } 153}, router.RouterMode.Standard) 154 .then(() => { 155 // success 156 }) 157 .catch(err => { 158 console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); 159 }) 160``` 161 162## router.pushUrl<sup>9+</sup> 163 164pushUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void 165 166跳转到应用内的指定页面。 167 168**系统能力：** SystemCapability.ArkUI.ArkUI.Full 169 170**参数：** 171 172| 参数名 | 类型 | 必填 | 说明 | 173| ------- | ------------------------------- | ---- | ---------- | 174| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 175| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 176| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 177 178**错误码：** 179 180以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 181 182| 错误码ID | 错误信息 | 183| --------- | ------- | 184| 100001 | if UI execution context not found. | 185| 100002 | if the uri is not exist. | 186| 100003 | if the pages are pushed too much. | 187 188**示例：** 189 190```js 191router.pushUrl({ 192 url: 'pages/routerpage2', 193 params: { 194 data1: 'message', 195 data2: { 196 data3: [123, 456, 789] 197 } 198 } 199}, router.RouterMode.Standard, (err) => { 200 if (err) { 201 console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); 202 return; 203 } 204 console.info('pushUrl success'); 205}); 206``` 207 208## router.replaceUrl<sup>9+</sup> 209 210replaceUrl(options: RouterOptions): Promise<void> 211 212用应用内的某个页面替换当前页面，并销毁被替换的页面。 213 214**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 215 216**参数：** 217 218| 参数名 | 类型 | 必填 | 说明 | 219| ------- | ------------------------------- | ---- | ------------------ | 220| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 221 222**返回值：** 223 224| 类型 | 说明 | 225| ------------------- | --------- | 226| Promise<void> | 异常返回结果。 | 227 228**错误码：** 229 230以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 231 232| 错误码ID | 错误信息 | 233| --------- | ------- | 234| 100001 | if UI execution context not found, only throw in standard system. | 235| 200002 | if the uri is not exist. | 236 237**示例：** 238 239```js 240router.replaceUrl({ 241 url: 'pages/detail', 242 params: { 243 data1: 'message' 244 } 245}) 246 .then(() => { 247 // success 248 }) 249 .catch(err => { 250 console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); 251 }) 252``` 253 254## router.replaceUrl<sup>9+</sup> 255 256replaceUrl(options: RouterOptions, callback: AsyncCallback<void>): void 257 258用应用内的某个页面替换当前页面，并销毁被替换的页面。 259 260**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 261 262**参数：** 263 264| 参数名 | 类型 | 必填 | 说明 | 265| ------- | ------------------------------- | ---- | ------------------ | 266| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 267| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 268 269**错误码：** 270 271以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 272 273| 错误码ID | 错误信息 | 274| --------- | ------- | 275| 100001 | if UI execution context not found, only throw in standard system. | 276| 200002 | if the uri is not exist. | 277 278**示例：** 279 280```js 281router.replaceUrl({ 282 url: 'pages/detail', 283 params: { 284 data1: 'message' 285 } 286}, (err) => { 287 if (err) { 288 console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); 289 return; 290 } 291 console.info('replaceUrl success'); 292}); 293``` 294 295## router.replaceUrl<sup>9+</sup> 296 297replaceUrl(options: RouterOptions, mode: RouterMode): Promise<void> 298 299用应用内的某个页面替换当前页面，并销毁被替换的页面。 300 301**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 302 303**参数：** 304 305| 参数名 | 类型 | 必填 | 说明 | 306| ------- | ------------------------------- | ---- | ---------- | 307| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 308| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 309 310 311**返回值：** 312 313| 类型 | 说明 | 314| ------------------- | --------- | 315| Promise<void> | 异常返回结果。 | 316 317**错误码：** 318 319以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 320 321| 错误码ID | 错误信息 | 322| --------- | ------- | 323| 100001 | if can not get the delegate, only throw in standard system. | 324| 200002 | if the uri is not exist. | 325 326**示例：** 327 328```js 329router.replaceUrl({ 330 url: 'pages/detail', 331 params: { 332 data1: 'message' 333 } 334}, router.RouterMode.Standard) 335 .then(() => { 336 // success 337 }) 338 .catch(err => { 339 console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); 340 }) 341``` 342 343## router.replaceUrl<sup>9+</sup> 344 345replaceUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void 346 347用应用内的某个页面替换当前页面，并销毁被替换的页面。 348 349**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 350 351**参数：** 352 353| 参数名 | 类型 | 必填 | 说明 | 354| ------- | ------------------------------- | ---- | ---------- | 355| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 356| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 357| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 358 359**错误码：** 360 361以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 362 363| 错误码ID | 错误信息 | 364| --------- | ------- | 365| 100001 | if UI execution context not found, only throw in standard system. | 366| 200002 | if the uri is not exist. | 367 368**示例：** 369 370```js 371router.replaceUrl({ 372 url: 'pages/detail', 373 params: { 374 data1: 'message' 375 } 376}, router.RouterMode.Standard, (err) => { 377 if (err) { 378 console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); 379 return; 380 } 381 console.info('replaceUrl success'); 382}); 383``` 384 385## router.back 386 387back(options?: RouterOptions ): void 388 389返回上一页面或指定的页面。 390 391**系统能力：** SystemCapability.ArkUI.ArkUI.Full 392 393**参数：** 394 395| 参数名 | 类型 | 必填 | 说明 | 396| ------- | ------------------------------- | ---- | ------------------------------------------------------------ | 397| options | [RouterOptions](#routeroptions) | 否 | 返回页面描述信息，其中参数url指路由跳转时会返回到指定url的界面，如果页面栈上没有url页面，则不响应该情况。如果url未设置，则返回上一页，页面不会重新构建，页面栈里面的page不会回收，出栈后会被回收。 | 398 399**示例：** 400 401```js 402router.back({url:'pages/detail'}); 403``` 404 405## router.clear 406 407clear(): void 408 409清空页面栈中的所有历史页面，仅保留当前页面作为栈顶页面。 410 411**系统能力：** SystemCapability.ArkUI.ArkUI.Full 412 413**示例：** 414 415```js 416router.clear(); 417``` 418 419## router.getLength 420 421getLength(): string 422 423获取当前在页面栈内的页面数量。 424 425**系统能力：** SystemCapability.ArkUI.ArkUI.Full 426 427**返回值：** 428 429| 类型 | 说明 | 430| ------ | ------------------ | 431| string | 页面数量，页面栈支持最大数值是32。 | 432 433**示例：** 434 435```js 436let size = router.getLength(); 437console.log('pages stack size = ' + size); 438``` 439 440## router.getState 441 442getState(): RouterState 443 444获取当前页面的状态信息。 445 446**系统能力：** SystemCapability.ArkUI.ArkUI.Full 447 448**返回值：** 449 450| 类型 | 说明 | 451| --------------------------- | ------- | 452| [RouterState](#routerstate) | 页面状态信息。 | 453 454**示例：** 455 456```js 457let page = router.getState(); 458console.log('current index = ' + page.index); 459console.log('current name = ' + page.name); 460console.log('current path = ' + page.path); 461``` 462 463## RouterState 464 465页面状态信息。 466 467**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 468 469| 名称 | 类型 | 必填 | 说明 | 470| ----- | ------ | ---- | ------------------------------------------------------------ | 471| index | number | 是 | 表示当前页面在页面栈中的索引。从栈底到栈顶，index从1开始递增。 | 472| name | string | 否 | 表示当前页面的名称，即对应文件名。 | 473| path | string | 是 | 表示当前页面的路径。 | 474 475## router.showAlertBeforeBackPage<sup>9+</sup> 476 477showAlertBeforeBackPage(options: EnableAlertOptions): void 478 479开启页面返回询问对话框。 480 481**系统能力：** SystemCapability.ArkUI.ArkUI.Full 482 483**参数：** 484 485| 参数名 | 类型 | 必填 | 说明 | 486| ------- | ---------------------------------------- | ---- | --------- | 487| options | [EnableAlertOptions](#enablealertoptions) | 是 | 文本弹窗信息描述。 | 488 489**错误码：** 490 491以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 492 493| 错误码ID | 错误信息 | 494| --------- | ------- | 495| 100001 | if UI execution context not found. | 496 497**示例：** 498 499 ```js 500try { 501 router.showAlertBeforeBackPage({ 502 message: 'Message Info' 503 }); 504} catch(error) { 505 console.error(`showAlertBeforeBackPage failed, code is ${error.code}, message is ${error.message}`); 506} 507 ``` 508## EnableAlertOptions 509 510页面返回询问对话框选项。 511 512**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。 513 514| 名称 | 类型 | 必填 | 说明 | 515| ------- | ------ | ---- | -------- | 516| message | string | 是 | 询问对话框内容。 | 517 518## router.hideAlertBeforeBackPage<sup>9+</sup> 519 520hideAlertBeforeBackPage(): void 521 522禁用页面返回询问对话框。 523 524**系统能力：** SystemCapability.ArkUI.ArkUI.Full 525 526**示例：** 527 528```js 529router.hideAlertBeforeBackPage(); 530``` 531 532## router.getParams 533 534getParams(): Object 535 536获取发起跳转的页面往当前页传入的参数。 537 538**系统能力：** SystemCapability.ArkUI.ArkUI.Full 539 540**返回值：** 541 542| 类型 | 说明 | 543| ------ | ---------------------------------- | 544| object | 发起跳转的页面往当前页传入的参数。 | 545 546**示例：** 547 548``` 549router.getParams(); 550``` 551 552## RouterOptions 553 554路由跳转选项。 555 556**系统能力：** SystemCapability.ArkUI.ArkUI.Lite。 557 558| 名称 | 类型 | 必填 | 说明 | 559| ------ | ------ | ---- | ------------------------------------------------------------ | 560| url | string | 是 | 表示目标页面的url，可以用以下两种格式：<br/>- 页面绝对路径，由配置文件中pages列表提供，例如：<br/> - pages/index/index<br/> - pages/detail/detail<br/>- 特殊值，如果url的值是"/"，则跳转到首页。 | 561| params | object | 否 | 表示路由跳转时要同时传递到目标页面的数据。跳转到目标页面后，使用router.getParams()获取传递的参数，此外，在类web范式中，参数也可以在页面中直接使用，如this.keyValue(keyValue为跳转时params参数中的key值)，如果目标页面中已有该字段，则其值会被传入的字段值覆盖。 | 562 563 564 > **说明：** 565 > 页面路由栈支持的最大Page数量为32。 566 567## RouterMode<sup>9+</sup> 568 569路由跳转模式。 570 571**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 572 573| 名称 | 说明 | 574| -------- | ------------------------------------------------------------ | 575| Standard | 多实例模式，也是默认情况下的跳转模式。 <br/>目标页面会被添加到页面栈顶，无论栈中是否存在相同url的页面。<br/>**说明：**不使用路由跳转模式时，则按照默认的多实例模式进行跳转。 | 576| Single | 单实例模式。<br/>如果目标页面的url已经存在于页面栈中，则会将离栈顶最近的同url页面移动到栈顶，该页面成为新建页。<br />如果目标页面的url在页面栈中不存在同url页面，则按照默认的多实例模式进行跳转。 | 577 578## 完整示例 579 580### 基于JS扩展的类Web开发范式 581 582```js 583// 在当前页面中 584export default { 585 pushPage() { 586 router.push({ 587 url: 'pages/detail/detail', 588 params: { 589 data1: 'message' 590 } 591 }); 592 } 593} 594``` 595```js 596// 在detail页面中 597export default { 598 onInit() { 599 console.info('showData1:' + router.getParams()['data1']); 600 } 601} 602``` 603 604### 基于TS扩展的声明式开发范式 605 606```ts 607// 通过router.pushUrl跳转至目标页携带params参数 608import router from '@ohos.router' 609 610@Entry 611@Component 612struct Index { 613 async routePage() { 614 let options = { 615 url: 'pages/second', 616 params: { 617 text: '这是第一页的值', 618 data: { 619 array: [12, 45, 78] 620 } 621 } 622 } 623 try { 624 await router.pushUrl(options) 625 } catch (err) { 626 console.info(` fail callback, code: ${err.code}, msg: ${err.msg}`) 627 } 628 } 629 630 build() { 631 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 632 Text('这是第一页') 633 .fontSize(50) 634 .fontWeight(FontWeight.Bold) 635 Button() { 636 Text('next page') 637 .fontSize(25) 638 .fontWeight(FontWeight.Bold) 639 }.type(ButtonType.Capsule) 640 .margin({ top: 20 }) 641 .backgroundColor('#ccc') 642 .onClick(() => { 643 this.routePage() 644 }) 645 } 646 .width('100%') 647 .height('100%') 648 } 649} 650``` 651 652```ts 653// 在second页面中接收传递过来的参数 654import router from '@ohos.router' 655 656@Entry 657@Component 658struct Second { 659 private content: string = "这是第二页" 660 @State text: string = router.getParams()['text'] 661 @State data: object = router.getParams()['data'] 662 @State secondData: string = '' 663 664 build() { 665 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 666 Text(`${this.content}`) 667 .fontSize(50) 668 .fontWeight(FontWeight.Bold) 669 Text(this.text) 670 .fontSize(30) 671 .onClick(() => { 672 this.secondData = (this.data.['array'][1]).toString() 673 }) 674 .margin({ top: 20 }) 675 Text(`第一页传来的数值:${this.secondData}`) 676 .fontSize(20) 677 .margin({ top: 20 }) 678 .backgroundColor('red') 679 } 680 .width('100%') 681 .height('100%') 682 } 683} 684``` 685 686## router.push<sup>(deprecated)</sup> 687 688push(options: RouterOptions): void 689 690跳转到应用内的指定页面。 691 692从API version9开始不再维护，建议使用[pushUrl<sup>9+</sup>](#routerpushurl9) 693 694**系统能力：** SystemCapability.ArkUI.ArkUI.Full 695 696**参数：** 697 698| 参数名 | 类型 | 必填 | 说明 | 699| ------- | ------------------------------- | ---- | --------- | 700| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 701 702 703**示例：** 704 705```js 706router.push({ 707 url: 'pages/routerpage2', 708 params: { 709 data1: 'message', 710 data2: { 711 data3: [123, 456, 789] 712 } 713 } 714}); 715``` 716 717## router.replace<sup>(deprecated)</sup> 718 719replace(options: RouterOptions): void 720 721用应用内的某个页面替换当前页面，并销毁被替换的页面。 722 723从API version9开始不再维护，建议使用[replaceUrl<sup>9+</sup>](#routerreplaceurl9) 724 725**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 726 727**参数：** 728 729| 参数名 | 类型 | 必填 | 说明 | 730| ------- | ------------------------------- | ---- | ------------------ | 731| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 732 733**示例：** 734 735```js 736router.replace({ 737 url: 'pages/detail', 738 params: { 739 data1: 'message' 740 } 741}); 742``` 743 744## router.enableAlertBeforeBackPage<sup>(deprecated)</sup> 745 746enableAlertBeforeBackPage(options: EnableAlertOptions): void 747 748开启页面返回询问对话框。 749 750从API version9开始不再维护，建议使用[showAlertBeforeBackPage<sup>9+</sup>](#routershowalertbeforebackpage9) 751 752**系统能力：** SystemCapability.ArkUI.ArkUI.Full 753 754**参数：** 755 756| 参数名 | 类型 | 必填 | 说明 | 757| ------- | ---------------------------------------- | ---- | --------- | 758| options | [EnableAlertOptions](#enablealertoptions) | 是 | 文本弹窗信息描述。 | 759 760**示例：** 761 762 ```js 763 router.enableAlertBeforeBackPage({ 764 message: 'Message Info' 765 }); 766 ``` 767 768## router.disableAlertBeforeBackPage<sup>(deprecated)</sup> 769 770disableAlertBeforeBackPage(): void 771 772禁用页面返回询问对话框。 773 774从API version9开始不再维护，建议使用[hideAlertBeforeBackPage<sup>9+</sup>](#routerhidealertbeforebackpage9) 775 776**系统能力：** SystemCapability.ArkUI.ArkUI.Full 777 778**示例：** 779 780```js 781router.disableAlertBeforeBackPage(); 782```