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```ts 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```ts 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```ts 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```ts 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 500router.showAlertBeforeBackPage({ 501 message: 'Message Info' 502}) 503 .then(() => { 504 // success 505 }) 506 .catch(err => { 507 console.error(`showAlertBeforeBackPage failed, code is ${error.code}, message is ${error.message}`); 508 }) 509 ``` 510## EnableAlertOptions 511 512页面返回询问对话框选项。 513 514**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。 515 516| 名称 | 类型 | 必填 | 说明 | 517| ------- | ------ | ---- | -------- | 518| message | string | 是 | 询问对话框内容。 | 519 520## router.hideAlertBeforeBackPage<sup>9+</sup> 521 522hideAlertBeforeBackPage(): void 523 524禁用页面返回询问对话框。 525 526**系统能力：** SystemCapability.ArkUI.ArkUI.Full 527 528**示例：** 529 530```js 531router.hideAlertBeforeBackPage(); 532``` 533 534## router.getParams 535 536getParams(): Object 537 538获取发起跳转的页面往当前页传入的参数。 539 540**系统能力：** SystemCapability.ArkUI.ArkUI.Full 541 542**返回值：** 543 544| 类型 | 说明 | 545| ------ | ---------------------------------- | 546| object | 发起跳转的页面往当前页传入的参数。 | 547 548**示例：** 549 550``` 551router.getParams(); 552``` 553 554## RouterOptions 555 556路由跳转选项。 557 558**系统能力：** SystemCapability.ArkUI.ArkUI.Lite。 559 560| 名称 | 类型 | 必填 | 说明 | 561| ------ | ------ | ---- | ------------------------------------------------------------ | 562| url | string | 是 | 表示目标页面的url，可以用以下两种格式：<br/>- 页面绝对路径，由配置文件中pages列表提供，例如：<br/> - pages/index/index<br/> - pages/detail/detail<br/>- 特殊值，如果url的值是"/"，则跳转到首页。 | 563| params | object | 否 | 表示路由跳转时要同时传递到目标页面的数据，切换到其他页面时，当前接收的数据失效。跳转到目标页面后，使用router.getParams()获取传递的参数，此外，在类web范式中，参数也可以在页面中直接使用，如this.keyValue(keyValue为跳转时params参数中的key值)，如果目标页面中已有该字段，则其值会被传入的字段值覆盖。<br/>**说明：** <br/>params参数不能传递方法和系统接口返回的对象（例如，媒体接口定义和返回的PixelMap对象）。建议开发者提取系统接口返回的对象中需要被传递的基础类型属性，自行构造object类型对象进行传递。 | 564 565 566 > **说明：** 567 > 页面路由栈支持的最大Page数量为32。 568 569## RouterMode<sup>9+</sup> 570 571路由跳转模式。 572 573**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 574 575| 名称 | 说明 | 576| -------- | ------------------------------------------------------------ | 577| Standard | 多实例模式，也是默认情况下的跳转模式。 <br/>目标页面会被添加到页面栈顶，无论栈中是否存在相同url的页面。<br/>**说明：**不使用路由跳转模式时，则按照默认的多实例模式进行跳转。 | 578| Single | 单实例模式。<br/>如果目标页面的url已经存在于页面栈中，则会将离栈顶最近的同url页面移动到栈顶，该页面成为新建页。<br />如果目标页面的url在页面栈中不存在同url页面，则按照默认的多实例模式进行跳转。 | 579 580## 完整示例 581 582### 基于JS扩展的类Web开发范式 583 584```js 585// 在当前页面中 586export default { 587 pushPage() { 588 router.push({ 589 url: 'pages/detail/detail', 590 params: { 591 data1: 'message' 592 } 593 }); 594 } 595} 596``` 597```js 598// 在detail页面中 599export default { 600 onInit() { 601 console.info('showData1:' + router.getParams()['data1']); 602 } 603} 604``` 605 606### 基于TS扩展的声明式开发范式 607 608```ts 609// 通过router.pushUrl跳转至目标页携带params参数 610import router from '@ohos.router' 611 612@Entry 613@Component 614struct Index { 615 async routePage() { 616 let options = { 617 url: 'pages/second', 618 params: { 619 text: '这是第一页的值', 620 data: { 621 array: [12, 45, 78] 622 } 623 } 624 } 625 try { 626 await router.pushUrl(options) 627 } catch (err) { 628 console.info(` fail callback, code: ${err.code}, msg: ${err.msg}`) 629 } 630 } 631 632 build() { 633 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 634 Text('这是第一页') 635 .fontSize(50) 636 .fontWeight(FontWeight.Bold) 637 Button() { 638 Text('next page') 639 .fontSize(25) 640 .fontWeight(FontWeight.Bold) 641 }.type(ButtonType.Capsule) 642 .margin({ top: 20 }) 643 .backgroundColor('#ccc') 644 .onClick(() => { 645 this.routePage() 646 }) 647 } 648 .width('100%') 649 .height('100%') 650 } 651} 652``` 653 654```ts 655// 在second页面中接收传递过来的参数 656import router from '@ohos.router' 657 658@Entry 659@Component 660struct Second { 661 private content: string = "这是第二页" 662 @State text: string = router.getParams()['text'] 663 @State data: object = router.getParams()['data'] 664 @State secondData: string = '' 665 666 build() { 667 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 668 Text(`${this.content}`) 669 .fontSize(50) 670 .fontWeight(FontWeight.Bold) 671 Text(this.text) 672 .fontSize(30) 673 .onClick(() => { 674 this.secondData = (this.data['array'][1]).toString() 675 }) 676 .margin({ top: 20 }) 677 Text(`第一页传来的数值:${this.secondData}`) 678 .fontSize(20) 679 .margin({ top: 20 }) 680 .backgroundColor('red') 681 } 682 .width('100%') 683 .height('100%') 684 } 685} 686``` 687 688## router.push<sup>(deprecated)</sup> 689 690push(options: RouterOptions): void 691 692跳转到应用内的指定页面。 693 694从API version9开始不再维护，建议使用[pushUrl<sup>9+</sup>](#routerpushurl9) 695 696**系统能力：** SystemCapability.ArkUI.ArkUI.Full 697 698**参数：** 699 700| 参数名 | 类型 | 必填 | 说明 | 701| ------- | ------------------------------- | ---- | --------- | 702| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 703 704 705**示例：** 706 707```js 708router.push({ 709 url: 'pages/routerpage2', 710 params: { 711 data1: 'message', 712 data2: { 713 data3: [123, 456, 789] 714 } 715 } 716}); 717``` 718 719## router.replace<sup>(deprecated)</sup> 720 721replace(options: RouterOptions): void 722 723用应用内的某个页面替换当前页面，并销毁被替换的页面。 724 725从API version9开始不再维护，建议使用[replaceUrl<sup>9+</sup>](#routerreplaceurl9) 726 727**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 728 729**参数：** 730 731| 参数名 | 类型 | 必填 | 说明 | 732| ------- | ------------------------------- | ---- | ------------------ | 733| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 734 735**示例：** 736 737```js 738router.replace({ 739 url: 'pages/detail', 740 params: { 741 data1: 'message' 742 } 743}); 744``` 745 746## router.enableAlertBeforeBackPage<sup>(deprecated)</sup> 747 748enableAlertBeforeBackPage(options: EnableAlertOptions): void 749 750开启页面返回询问对话框。 751 752从API version9开始不再维护，建议使用[showAlertBeforeBackPage<sup>9+</sup>](#routershowalertbeforebackpage9) 753 754**系统能力：** SystemCapability.ArkUI.ArkUI.Full 755 756**参数：** 757 758| 参数名 | 类型 | 必填 | 说明 | 759| ------- | ---------------------------------------- | ---- | --------- | 760| options | [EnableAlertOptions](#enablealertoptions) | 是 | 文本弹窗信息描述。 | 761 762**示例：** 763 764 ```js 765 router.enableAlertBeforeBackPage({ 766 message: 'Message Info' 767 }); 768 ``` 769 770## router.disableAlertBeforeBackPage<sup>(deprecated)</sup> 771 772disableAlertBeforeBackPage(): void 773 774禁用页面返回询问对话框。 775 776从API version9开始不再维护，建议使用[hideAlertBeforeBackPage<sup>9+</sup>](#routerhidealertbeforebackpage9) 777 778**系统能力：** SystemCapability.ArkUI.ArkUI.Full 779 780**示例：** 781 782```js 783router.disableAlertBeforeBackPage(); 784```