1# @ohos.router (页面路由) 2 3本模块提供通过不同的url访问不同的页面，包括跳转到应用内的指定页面、同应用内的某个页面替换当前页面、返回上一页面或指定的页面等。 4 5> **说明** 6> 7> - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - 页面路由需要在页面渲染完成之后才能调用，在onInit和onReady生命周期中页面还处于渲染阶段，禁止调用页面路由方法。 10> 11> - 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见[UIContext](./js-apis-arkui-UIContext.md#uicontext)说明。 12> 13> - 从API version 10开始，可以通过使用[UIContext](./js-apis-arkui-UIContext.md#uicontext)中的[getRouter](./js-apis-arkui-UIContext.md#getrouter)方法获取当前UI上下文关联的[Router](./js-apis-arkui-UIContext.md#router)对象。 14> 15> - 为了实现更好的转场效果，推荐使用[Navigation组件](../../ui/arkts-navigation-navigation.md)和[模态转场](../../ui/arkts-modal-transition.md)。 16 17## 导入模块 18 19``` 20import router from '@ohos.router' 21``` 22 23## router.pushUrl<sup>9+</sup> 24 25pushUrl(options: RouterOptions): Promise<void> 26 27跳转到应用内的指定页面。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ------- | ------------------------------- | ---- | --------- | 35| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 36 37**返回值：** 38 39| 类型 | 说明 | 40| ------------------- | --------- | 41| Promise<void> | 异常返回结果。 | 42 43**错误码：** 44 45以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 46 47| 错误码ID | 错误信息 | 48| --------- | ------- | 49| 100001 | if UI execution context not found. | 50| 100002 | if the uri is not exist. | 51| 100003 | if the pages are pushed too much. | 52 53**示例：** 54 55```ts 56import { BusinessError } from '@ohos.base'; 57 58class innerParams { 59 data3:number[] 60 61 constructor(tuple:number[]) { 62 this.data3 = tuple 63 } 64} 65 66class routerParams { 67 data1:string 68 data2:innerParams 69 70 constructor(str:string, tuple:number[]) { 71 this.data1 = str 72 this.data2 = new innerParams(tuple) 73 } 74} 75 76try { 77 router.pushUrl({ 78 url: 'pages/routerpage2', 79 params: new routerParams('message' ,[123,456,789]) 80 }) 81} catch (err) { 82 console.error(`pushUrl failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 83} 84``` 85 86## router.pushUrl<sup>9+</sup> 87 88pushUrl(options: RouterOptions, callback: AsyncCallback<void>): void 89 90跳转到应用内的指定页面。 91 92**系统能力：** SystemCapability.ArkUI.ArkUI.Full 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ------- | ------------------------------- | ---- | --------- | 98| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 99| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 100 101**错误码：** 102 103以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 104 105| 错误码ID | 错误信息 | 106| --------- | ------- | 107| 100001 | if UI execution context not found. | 108| 100002 | if the uri is not exist. | 109| 100003 | if the pages are pushed too much. | 110 111**示例：** 112 113```ts 114class innerParams { 115 data3:number[] 116 117 constructor(tuple:number[]) { 118 this.data3 = tuple 119 } 120} 121 122class routerParams { 123 data1:string 124 data2:innerParams 125 126 constructor(str:string, tuple:number[]) { 127 this.data1 = str 128 this.data2 = new innerParams(tuple) 129 } 130} 131 132router.pushUrl({ 133 url: 'pages/routerpage2', 134 params: new routerParams('message' ,[123,456,789]) 135}, (err) => { 136 if (err) { 137 console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); 138 return; 139 } 140 console.info('pushUrl success'); 141}) 142``` 143## router.pushUrl<sup>9+</sup> 144 145pushUrl(options: RouterOptions, mode: RouterMode): Promise<void> 146 147跳转到应用内的指定页面。 148 149**系统能力：** SystemCapability.ArkUI.ArkUI.Full 150 151**参数：** 152 153| 参数名 | 类型 | 必填 | 说明 | 154| ------- | ------------------------------- | ---- | ---------- | 155| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 156| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 157 158**返回值：** 159 160| 类型 | 说明 | 161| ------------------- | --------- | 162| Promise<void> | 异常返回结果。 | 163 164**错误码：** 165 166以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 167 168| 错误码ID | 错误信息 | 169| --------- | ------- | 170| 100001 | if UI execution context not found. | 171| 100002 | if the uri is not exist. | 172| 100003 | if the pages are pushed too much. | 173 174**示例：** 175 176```ts 177import { BusinessError } from '@ohos.base'; 178 179class innerParams { 180 data3:number[] 181 182 constructor(tuple:number[]) { 183 this.data3 = tuple 184 } 185} 186 187class routerParams { 188 data1:string 189 data2:innerParams 190 191 constructor(str:string, tuple:number[]) { 192 this.data1 = str 193 this.data2 = new innerParams(tuple) 194 } 195} 196 197try { 198 router.pushUrl({ 199 url: 'pages/routerpage2', 200 params: new routerParams('message' ,[123,456,789]) 201 }, router.RouterMode.Standard) 202} catch (err) { 203 console.error(`pushUrl failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 204} 205``` 206 207## router.pushUrl<sup>9+</sup> 208 209pushUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void 210 211跳转到应用内的指定页面。 212 213**系统能力：** SystemCapability.ArkUI.ArkUI.Full 214 215**参数：** 216 217| 参数名 | 类型 | 必填 | 说明 | 218| ------- | ------------------------------- | ---- | ---------- | 219| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 220| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 221| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 222 223**错误码：** 224 225以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 226 227| 错误码ID | 错误信息 | 228| --------- | ------- | 229| 100001 | if UI execution context not found. | 230| 100002 | if the uri is not exist. | 231| 100003 | if the pages are pushed too much. | 232 233**示例：** 234 235```ts 236class innerParams { 237 data3:number[] 238 239 constructor(tuple:number[]) { 240 this.data3 = tuple 241 } 242} 243 244class routerParams { 245 data1:string 246 data2:innerParams 247 248 constructor(str:string, tuple:number[]) { 249 this.data1 = str 250 this.data2 = new innerParams(tuple) 251 } 252} 253 254router.pushUrl({ 255 url: 'pages/routerpage2', 256 params: new routerParams('message' ,[123,456,789]) 257}, router.RouterMode.Standard, (err) => { 258 if (err) { 259 console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`); 260 return; 261 } 262 console.info('pushUrl success'); 263}) 264``` 265 266## router.replaceUrl<sup>9+</sup> 267 268replaceUrl(options: RouterOptions): Promise<void> 269 270用应用内的某个页面替换当前页面，并销毁被替换的页面。不支持设置页面转场动效，如需设置，推荐使用[Navigation组件](../../ui/arkts-navigation-navigation.md)。 271 272**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| ------- | ------------------------------- | ---- | ------------------ | 278| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 279 280**返回值：** 281 282| 类型 | 说明 | 283| ------------------- | --------- | 284| Promise<void> | 异常返回结果。 | 285 286**错误码：** 287 288以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 289 290| 错误码ID | 错误信息 | 291| --------- | ------- | 292| 100001 | if UI execution context not found, only throw in standard system. | 293| 200002 | if the uri is not exist. | 294 295**示例：** 296 297```ts 298import { BusinessError } from '@ohos.base'; 299 300class routerParams { 301 data1:string 302 303 constructor(str:string) { 304 this.data1 = str 305 } 306} 307 308try { 309 router.replaceUrl({ 310 url: 'pages/detail', 311 params: new routerParams('message') 312 }) 313} catch (err) { 314 console.error(`replaceUrl failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 315} 316``` 317 318## router.replaceUrl<sup>9+</sup> 319 320replaceUrl(options: RouterOptions, callback: AsyncCallback<void>): void 321 322用应用内的某个页面替换当前页面，并销毁被替换的页面。 323 324**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 325 326**参数：** 327 328| 参数名 | 类型 | 必填 | 说明 | 329| ------- | ------------------------------- | ---- | ------------------ | 330| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 331| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 332 333**错误码：** 334 335以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 336 337| 错误码ID | 错误信息 | 338| --------- | ------- | 339| 100001 | if UI execution context not found, only throw in standard system. | 340| 200002 | if the uri is not exist. | 341 342**示例：** 343 344```ts 345class routerParams { 346 data1:string 347 348 constructor(str:string) { 349 this.data1 = str 350 } 351} 352 353router.replaceUrl({ 354 url: 'pages/detail', 355 params: new routerParams('message') 356}, (err) => { 357 if (err) { 358 console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); 359 return; 360 } 361 console.info('replaceUrl success'); 362}) 363``` 364 365## router.replaceUrl<sup>9+</sup> 366 367replaceUrl(options: RouterOptions, mode: RouterMode): Promise<void> 368 369用应用内的某个页面替换当前页面，并销毁被替换的页面。 370 371**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 372 373**参数：** 374 375| 参数名 | 类型 | 必填 | 说明 | 376| ------- | ------------------------------- | ---- | ---------- | 377| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 378| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 379 380 381**返回值：** 382 383| 类型 | 说明 | 384| ------------------- | --------- | 385| Promise<void> | 异常返回结果。 | 386 387**错误码：** 388 389以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 390 391| 错误码ID | 错误信息 | 392| --------- | ------- | 393| 100001 | if can not get the delegate, only throw in standard system. | 394| 200002 | if the uri is not exist. | 395 396**示例：** 397 398```ts 399import { BusinessError } from '@ohos.base'; 400 401class routerParams { 402 data1:string 403 404 constructor(str:string) { 405 this.data1 = str 406 } 407} 408 409try { 410 router.replaceUrl({ 411 url: 'pages/detail', 412 params: new routerParams('message') 413 }, router.RouterMode.Standard) 414} catch (err) { 415 console.error(`replaceUrl failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 416} 417``` 418 419## router.replaceUrl<sup>9+</sup> 420 421replaceUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void 422 423用应用内的某个页面替换当前页面，并销毁被替换的页面。 424 425**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 426 427**参数：** 428 429| 参数名 | 类型 | 必填 | 说明 | 430| ------- | ------------------------------- | ---- | ---------- | 431| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 432| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 433| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 434 435**错误码：** 436 437以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 438 439| 错误码ID | 错误信息 | 440| --------- | ------- | 441| 100001 | if UI execution context not found, only throw in standard system. | 442| 200002 | if the uri is not exist. | 443 444**示例：** 445 446```ts 447class routerParams { 448 data1:string 449 450 constructor(str:string) { 451 this.data1 = str 452 } 453} 454 455router.replaceUrl({ 456 url: 'pages/detail', 457 params: new routerParams('message') 458}, router.RouterMode.Standard, (err) => { 459 if (err) { 460 console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`); 461 return; 462 } 463 console.info('replaceUrl success'); 464}); 465 466``` 467 468## router.pushNamedRoute<sup>10+</sup> 469 470pushNamedRoute(options: NamedRouterOptions): Promise<void> 471 472跳转到指定的命名路由页面。 473 474**系统能力：** SystemCapability.ArkUI.ArkUI.Full 475 476**参数：** 477 478| 参数名 | 类型 | 必填 | 说明 | 479| ------- | ------------------------------- | ---- | --------- | 480| options | [NamedRouterOptions](#namedrouteroptions10) | 是 | 跳转页面描述信息。 | 481 482**返回值：** 483 484| 类型 | 说明 | 485| ------------------- | --------- | 486| Promise<void> | 异常返回结果。 | 487 488**错误码：** 489 490以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 491 492| 错误码ID | 错误信息 | 493| --------- | ------- | 494| 100001 | if UI execution context not found. | 495| 100003 | if the pages are pushed too much. | 496| 100004 | if the named route is not exist. | 497 498**示例：** 499 500```ts 501import { BusinessError } from '@ohos.base'; 502 503class innerParams { 504 data3:number[] 505 506 constructor(tuple:number[]) { 507 this.data3 = tuple 508 } 509} 510 511class routerParams { 512 data1:string 513 data2:innerParams 514 515 constructor(str:string, tuple:number[]) { 516 this.data1 = str 517 this.data2 = new innerParams(tuple) 518 } 519} 520 521try { 522 router.pushNamedRoute({ 523 name: 'myPage', 524 params: new routerParams('message' ,[123,456,789]) 525 }) 526} catch (err) { 527 console.error(`pushNamedRoute failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 528} 529``` 530 531详细示例请参考：[UI开发-页面路由](../../ui/arkts-routing.md#命名路由) 532 533## router.pushNamedRoute<sup>10+</sup> 534 535pushNamedRoute(options: NamedRouterOptions, callback: AsyncCallback<void>): void 536 537跳转到指定的命名路由页面。 538 539**系统能力：** SystemCapability.ArkUI.ArkUI.Full 540 541**参数：** 542 543| 参数名 | 类型 | 必填 | 说明 | 544| ------- | ------------------------------- | ---- | --------- | 545| options | [NamedRouterOptions](#namedrouteroptions10) | 是 | 跳转页面描述信息。 | 546| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 547 548**错误码：** 549 550以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 551 552| 错误码ID | 错误信息 | 553| --------- | ------- | 554| 100001 | if UI execution context not found. | 555| 100003 | if the pages are pushed too much. | 556| 100004 | if the named route is not exist. | 557 558**示例：** 559 560```ts 561class innerParams { 562 data3:number[] 563 564 constructor(tuple:number[]) { 565 this.data3 = tuple 566 } 567} 568 569class routerParams { 570 data1:string 571 data2:innerParams 572 573 constructor(str:string, tuple:number[]) { 574 this.data1 = str 575 this.data2 = new innerParams(tuple) 576 } 577} 578 579router.pushNamedRoute({ 580 name: 'myPage', 581 params: new routerParams('message' ,[123,456,789]) 582}, (err) => { 583 if (err) { 584 console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); 585 return; 586 } 587 console.info('pushNamedRoute success'); 588}) 589``` 590## router.pushNamedRoute<sup>10+</sup> 591 592pushNamedRoute(options: NamedRouterOptions, mode: RouterMode): Promise<void> 593 594跳转到指定的命名路由页面。 595 596**系统能力：** SystemCapability.ArkUI.ArkUI.Full 597 598**参数：** 599 600| 参数名 | 类型 | 必填 | 说明 | 601| ------- | ------------------------------- | ---- | ---------- | 602| options | [NamedRouterOptions](#namedrouteroptions10) | 是 | 跳转页面描述信息。 | 603| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 604 605**返回值：** 606 607| 类型 | 说明 | 608| ------------------- | --------- | 609| Promise<void> | 异常返回结果。 | 610 611**错误码：** 612 613以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 614 615| 错误码ID | 错误信息 | 616| --------- | ------- | 617| 100001 | if UI execution context not found. | 618| 100003 | if the pages are pushed too much. | 619| 100004 | if the named route is not exist. | 620 621**示例：** 622 623```ts 624import { BusinessError } from '@ohos.base'; 625 626class innerParams { 627 data3:number[] 628 629 constructor(tuple:number[]) { 630 this.data3 = tuple 631 } 632} 633 634class routerParams { 635 data1:string 636 data2:innerParams 637 638 constructor(str:string, tuple:number[]) { 639 this.data1 = str 640 this.data2 = new innerParams(tuple) 641 } 642} 643 644try { 645 router.pushNamedRoute({ 646 name: 'myPage', 647 params: new routerParams('message' ,[123,456,789]) 648 }, router.RouterMode.Standard) 649} catch (err) { 650 console.error(`pushNamedRoute failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 651} 652``` 653 654## router.pushNamedRoute<sup>10+</sup> 655 656pushNamedRoute(options: NamedRouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void 657 658跳转到指定的命名路由页面。 659 660**系统能力：** SystemCapability.ArkUI.ArkUI.Full 661 662**参数：** 663 664| 参数名 | 类型 | 必填 | 说明 | 665| ------- | ------------------------------- | ---- | ---------- | 666| options | [NamedRouterOptions](#namedrouteroptions10) | 是 | 跳转页面描述信息。 | 667| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 668| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 669 670**错误码：** 671 672以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 673 674| 错误码ID | 错误信息 | 675| --------- | ------- | 676| 100001 | if UI execution context not found. | 677| 100003 | if the pages are pushed too much. | 678| 100004 | if the named route is not exist. | 679 680**示例：** 681 682```ts 683class innerParams { 684 data3:number[] 685 686 constructor(tuple:number[]) { 687 this.data3 = tuple 688 } 689} 690 691class routerParams { 692 data1:string 693 data2:innerParams 694 695 constructor(str:string, tuple:number[]) { 696 this.data1 = str 697 this.data2 = new innerParams(tuple) 698 } 699} 700 701router.pushNamedRoute({ 702 name: 'myPage', 703 params: new routerParams('message' ,[123,456,789]) 704}, router.RouterMode.Standard, (err) => { 705 if (err) { 706 console.error(`pushNamedRoute failed, code is ${err.code}, message is ${err.message}`); 707 return; 708 } 709 console.info('pushNamedRoute success'); 710}) 711``` 712 713## router.replaceNamedRoute<sup>10+</sup> 714 715replaceNamedRoute(options: NamedRouterOptions): Promise<void> 716 717用指定的命名路由页面替换当前页面，并销毁被替换的页面。 718 719**系统能力：** SystemCapability.ArkUI.ArkUI.Full 720 721**参数：** 722 723| 参数名 | 类型 | 必填 | 说明 | 724| ------- | ------------------------------- | ---- | ------------------ | 725| options | [NamedRouterOptions](#namedrouteroptions10) | 是 | 替换页面描述信息。 | 726 727**返回值：** 728 729| 类型 | 说明 | 730| ------------------- | --------- | 731| Promise<void> | 异常返回结果。 | 732 733**错误码：** 734 735以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 736 737| 错误码ID | 错误信息 | 738| --------- | ------- | 739| 100001 | if UI execution context not found, only throw in standard system. | 740| 100004 | if the named route is not exist. | 741 742**示例：** 743 744```ts 745import { BusinessError } from '@ohos.base'; 746 747class routerParams { 748 data1:string 749 750 constructor(str:string) { 751 this.data1 = str 752 } 753} 754 755try { 756 router.replaceNamedRoute({ 757 name: 'myPage', 758 params: new routerParams('message') 759 }) 760} catch (err) { 761 console.error(`replaceNamedRoute failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 762} 763``` 764 765## router.replaceNamedRoute<sup>10+</sup> 766 767replaceNamedRoute(options: NamedRouterOptions, callback: AsyncCallback<void>): void 768 769用指定的命名路由页面替换当前页面，并销毁被替换的页面。 770 771**系统能力：** SystemCapability.ArkUI.ArkUI.Full 772 773**参数：** 774 775| 参数名 | 类型 | 必填 | 说明 | 776| ------- | ------------------------------- | ---- | ------------------ | 777| options | [NamedRouterOptions](#namedrouteroptions10) | 是 | 替换页面描述信息。 | 778| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 779 780**错误码：** 781 782以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 783 784| 错误码ID | 错误信息 | 785| --------- | ------- | 786| 100001 | if UI execution context not found, only throw in standard system. | 787| 100004 | if the named route is not exist. | 788 789**示例：** 790 791```ts 792class routerParams { 793 data1:string 794 795 constructor(str:string) { 796 this.data1 = str 797 } 798} 799 800router.replaceNamedRoute({ 801 name: 'myPage', 802 params: new routerParams('message') 803}, (err) => { 804 if (err) { 805 console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); 806 return; 807 } 808 console.info('replaceNamedRoute success'); 809}) 810``` 811 812## router.replaceNamedRoute<sup>10+</sup> 813 814replaceNamedRoute(options: NamedRouterOptions, mode: RouterMode): Promise<void> 815 816用指定的命名路由页面替换当前页面，并销毁被替换的页面。 817 818**系统能力：** SystemCapability.ArkUI.ArkUI.Full 819 820**参数：** 821 822| 参数名 | 类型 | 必填 | 说明 | 823| ------- | ------------------------------- | ---- | ---------- | 824| options | [NamedRouterOptions](#namedrouteroptions10) | 是 | 替换页面描述信息。 | 825| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 826 827 828**返回值：** 829 830| 类型 | 说明 | 831| ------------------- | --------- | 832| Promise<void> | 异常返回结果。 | 833 834**错误码：** 835 836以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 837 838| 错误码ID | 错误信息 | 839| --------- | ------- | 840| 100001 | if can not get the delegate, only throw in standard system. | 841| 100004 | if the named route is not exist. | 842 843**示例：** 844 845```ts 846import { BusinessError } from '@ohos.base'; 847 848class routerParams { 849 data1:string 850 851 constructor(str:string) { 852 this.data1 = str 853 } 854} 855 856try { 857 router.replaceNamedRoute({ 858 name: 'myPage', 859 params: new routerParams('message') 860 }, router.RouterMode.Standard) 861} catch (err) { 862 console.error(`replaceNamedRoute failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 863} 864``` 865 866## router.replaceNamedRoute<sup>10+</sup> 867 868replaceNamedRoute(options: NamedRouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void 869 870用指定的命名路由页面替换当前页面，并销毁被替换的页面。 871 872**系统能力：** SystemCapability.ArkUI.ArkUI.Full 873 874**参数：** 875 876| 参数名 | 类型 | 必填 | 说明 | 877| ------- | ------------------------------- | ---- | ---------- | 878| options | [NamedRouterOptions](#namedrouteroptions10) | 是 | 替换页面描述信息。 | 879| mode | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | 880| callback | AsyncCallback<void> | 是 | 异常响应回调。 | 881 882**错误码：** 883 884以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 885 886| 错误码ID | 错误信息 | 887| --------- | ------- | 888| 100001 | if UI execution context not found, only throw in standard system. | 889| 100004 | if the named route is not exist. | 890 891**示例：** 892 893```ts 894class routerParams { 895 data1:string 896 897 constructor(str:string) { 898 this.data1 = str 899 } 900} 901 902router.replaceNamedRoute({ 903 name: 'myPage', 904 params: new routerParams('message') 905}, router.RouterMode.Standard, (err) => { 906 if (err) { 907 console.error(`replaceNamedRoute failed, code is ${err.code}, message is ${err.message}`); 908 return; 909 } 910 console.info('replaceNamedRoute success'); 911}); 912 913``` 914 915## router.back 916 917back(options?: RouterOptions ): void 918 919返回上一页面或指定的页面。 920 921**系统能力：** SystemCapability.ArkUI.ArkUI.Full 922 923**参数：** 924 925| 参数名 | 类型 | 必填 | 说明 | 926| ------- | ------------------------------- | ---- | ------------------------------------------------------------ | 927| options | [RouterOptions](#routeroptions) | 否 | 返回页面描述信息，其中参数url指路由跳转时会返回到指定url的界面，如果页面栈上没有url页面，则不响应该情况。如果url未设置，则返回上一页，页面不会重新构建，页面栈里面的page不会回收，出栈后会被回收。 | 928 929**示例：** 930 931```ts 932router.back({url:'pages/detail'}); 933``` 934 935## router.clear 936 937clear(): void 938 939清空页面栈中的所有历史页面，仅保留当前页面作为栈顶页面。 940 941**系统能力：** SystemCapability.ArkUI.ArkUI.Full 942 943**示例：** 944 945```ts 946router.clear(); 947``` 948 949## router.getLength 950 951getLength(): string 952 953获取当前在页面栈内的页面数量。 954 955**系统能力：** SystemCapability.ArkUI.ArkUI.Full 956 957**返回值：** 958 959| 类型 | 说明 | 960| ------ | ------------------ | 961| string | 页面数量，页面栈支持最大数值是32。 | 962 963**示例：** 964 965```ts 966let size = router.getLength(); 967console.log('pages stack size = ' + size); 968``` 969 970## router.getState 971 972getState(): RouterState 973 974获取当前页面的状态信息。 975 976**系统能力：** SystemCapability.ArkUI.ArkUI.Full 977 978**返回值：** 979 980| 类型 | 说明 | 981| --------------------------- | ------- | 982| [RouterState](#routerstate) | 页面状态信息。 | 983 984**示例：** 985 986```ts 987let page = router.getState(); 988console.log('current index = ' + page.index); 989console.log('current name = ' + page.name); 990console.log('current path = ' + page.path); 991``` 992 993## RouterState 994 995页面状态信息。 996 997**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 998 999| 名称 | 类型 | 必填 | 说明 | 1000| ----- | ------ | ---- | ------------------------------------------------------------ | 1001| index | number | 是 | 表示当前页面在页面栈中的索引。从栈底到栈顶，index从1开始递增。 | 1002| name | string | 否 | 表示当前页面的名称，即对应文件名。 | 1003| path | string | 是 | 表示当前页面的路径。 | 1004 1005## router.showAlertBeforeBackPage<sup>9+</sup> 1006 1007showAlertBeforeBackPage(options: EnableAlertOptions): void 1008 1009开启页面返回询问对话框。 1010 1011**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1012 1013**参数：** 1014 1015| 参数名 | 类型 | 必填 | 说明 | 1016| ------- | ---------------------------------------- | ---- | --------- | 1017| options | [EnableAlertOptions](#enablealertoptions) | 是 | 文本弹窗信息描述。 | 1018 1019**错误码：** 1020 1021以下错误码的详细介绍请参见[ohos.router(页面路由)](../errorcodes/errorcode-router.md)错误码。 1022 1023| 错误码ID | 错误信息 | 1024| --------- | ------- | 1025| 100001 | if UI execution context not found. | 1026 1027**示例：** 1028 1029```ts 1030import { BusinessError } from '@ohos.base'; 1031 1032try { 1033 router.showAlertBeforeBackPage({ 1034 message: 'Message Info' 1035 }); 1036} catch(err) { 1037 console.error(`showAlertBeforeBackPage failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`); 1038} 1039``` 1040## EnableAlertOptions 1041 1042页面返回询问对话框选项。 1043 1044**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。 1045 1046| 名称 | 类型 | 必填 | 说明 | 1047| ------- | ------ | ---- | -------- | 1048| message | string | 是 | 询问对话框内容。 | 1049 1050## router.hideAlertBeforeBackPage<sup>9+</sup> 1051 1052hideAlertBeforeBackPage(): void 1053 1054禁用页面返回询问对话框。 1055 1056**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1057 1058**示例：** 1059 1060```ts 1061router.hideAlertBeforeBackPage(); 1062``` 1063 1064## router.getParams 1065 1066getParams(): Object 1067 1068获取发起跳转的页面往当前页传入的参数。 1069 1070**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1071 1072**返回值：** 1073 1074| 类型 | 说明 | 1075| ------ | ---------------------------------- | 1076| object | 发起跳转的页面往当前页传入的参数。 | 1077 1078**示例：** 1079 1080``` 1081router.getParams(); 1082``` 1083 1084## RouterOptions 1085 1086路由跳转选项。 1087 1088**系统能力：** SystemCapability.ArkUI.ArkUI.Lite。 1089 1090| 名称 | 类型 | 必填 | 说明 | 1091| ------ | ------ | ---- | ------------------------------------------------------------ | 1092| url | string | 是 | 表示目标页面的url，可以用以下两种格式：<br/>- 页面绝对路径，由配置文件中pages列表提供，例如：<br/> - pages/index/index<br/> - pages/detail/detail<br/>- 特殊值，如果url的值是"/"，则跳转到首页。 | 1093| params | object | 否 | 表示路由跳转时要同时传递到目标页面的数据，切换到其他页面时，当前接收的数据失效。跳转到目标页面后，使用router.getParams()获取传递的参数，此外，在类web范式中，参数也可以在页面中直接使用，如this.keyValue(keyValue为跳转时params参数中的key值)，如果目标页面中已有该字段，则其值会被传入的字段值覆盖。<br/>**说明：** <br/>params参数不能传递方法和系统接口返回的对象（例如，媒体接口定义和返回的PixelMap对象）。建议开发者提取系统接口返回的对象中需要被传递的基础类型属性，自行构造object类型对象进行传递。 | 1094 1095 1096 > **说明：** 1097 > 页面路由栈支持的最大Page数量为32。 1098 1099## RouterMode<sup>9+</sup> 1100 1101路由跳转模式。 1102 1103**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 1104 1105| 名称 | 说明 | 1106| -------- | ------------------------------------------------------------ | 1107| Standard | 多实例模式，也是默认情况下的跳转模式。 <br/>目标页面会被添加到页面栈顶，无论栈中是否存在相同url的页面。<br/>**说明：** 不使用路由跳转模式时，则按照默认的多实例模式进行跳转。 | 1108| Single | 单实例模式。<br/>如果目标页面的url已经存在于页面栈中，则该url页面移动到栈顶。<br />如果目标页面的url在页面栈中不存在同url页面，则按照默认的多实例模式进行跳转。 | 1109 1110## NamedRouterOptions<sup>10+</sup> 1111 1112命名路由跳转选项。 1113 1114**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1115 1116| 名称 | 类型 | 必填 | 说明 | 1117| ------ | ------ | ---- | ------------------------------------------------------------ | 1118| name | string | 是 | 表示目标命名路由页面的name。 | 1119| params | object | 否 | 表示路由跳转时要同时传递到目标页面的数据。跳转到目标页面后，使用router.getParams()获取传递的参数，此外，在类web范式中，参数也可以在页面中直接使用，如this.keyValue(keyValue为跳转时params参数中的key值)，如果目标页面中已有该字段，则其值会被传入的字段值覆盖。 | 1120 1121## 完整示例 1122 1123### 基于JS扩展的类Web开发范式 1124 1125以下代码仅适用于javascript文件，不适用于ArkTS文件 1126```js 1127// 在当前页面中 1128export default { 1129 pushPage() { 1130 router.push({ 1131 url: 'pages/detail/detail', 1132 params: { 1133 data1: 'message' 1134 } 1135 }); 1136 } 1137} 1138``` 1139```js 1140// 在detail页面中 1141export default { 1142 onInit() { 1143 console.info('showData1:' + router.getParams()['data1']); 1144 } 1145} 1146``` 1147 1148### 基于TS扩展的声明式开发范式 1149 1150```ts 1151// 通过router.pushUrl跳转至目标页携带params参数 1152import router from '@ohos.router' 1153import { BusinessError } from '@ohos.base' 1154 1155// 定义传递参数的类 1156class innerParams { 1157 array:number[] 1158 1159 constructor(tuple:number[]) { 1160 this.array = tuple 1161 } 1162} 1163 1164class routerParams { 1165 text:string 1166 data:innerParams 1167 1168 constructor(str:string, tuple:number[]) { 1169 this.text = str 1170 this.data = new innerParams(tuple) 1171 } 1172} 1173 1174@Entry 1175@Component 1176struct Index { 1177 async routePage() { 1178 let options:router.RouterOptions = { 1179 url: 'pages/second', 1180 params: new routerParams('这是第一页的值' ,[12, 45, 78]) 1181 } 1182 try { 1183 await router.pushUrl(options) 1184 } catch (err) { 1185 console.info(` fail callback, code: ${(err as BusinessError).code}, msg: ${(err as BusinessError).message}`) 1186 } 1187 } 1188 1189 build() { 1190 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 1191 Text('这是第一页') 1192 .fontSize(50) 1193 .fontWeight(FontWeight.Bold) 1194 Button() { 1195 Text('next page') 1196 .fontSize(25) 1197 .fontWeight(FontWeight.Bold) 1198 }.type(ButtonType.Capsule) 1199 .margin({ top: 20 }) 1200 .backgroundColor('#ccc') 1201 .onClick(() => { 1202 this.routePage() 1203 }) 1204 } 1205 .width('100%') 1206 .height('100%') 1207 } 1208} 1209``` 1210 1211```ts 1212// 在second页面中接收传递过来的参数 1213import router from '@ohos.router' 1214 1215class innerParams { 1216 array:number[] 1217 1218 constructor(tuple:number[]) { 1219 this.array = tuple 1220 } 1221} 1222 1223class routerParams { 1224 text:string 1225 data:innerParams 1226 1227 constructor(str:string, tuple:number[]) { 1228 this.text = str 1229 this.data = new innerParams(tuple) 1230 } 1231} 1232 1233@Entry 1234@Component 1235struct Second { 1236 private content: string = "这是第二页" 1237 @State text: string = (router.getParams() as routerParams).text 1238 @State data: object = (router.getParams() as routerParams).data 1239 @State secondData: string = '' 1240 1241 build() { 1242 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 1243 Text(`${this.content}`) 1244 .fontSize(50) 1245 .fontWeight(FontWeight.Bold) 1246 Text(this.text) 1247 .fontSize(30) 1248 .onClick(() => { 1249 this.secondData = (this.data['array'][1]).toString() 1250 }) 1251 .margin({ top: 20 }) 1252 Text(`第一页传来的数值:${this.secondData}`) 1253 .fontSize(20) 1254 .margin({ top: 20 }) 1255 .backgroundColor('red') 1256 } 1257 .width('100%') 1258 .height('100%') 1259 } 1260} 1261``` 1262 1263## router.push<sup>(deprecated)</sup> 1264 1265push(options: RouterOptions): void 1266 1267跳转到应用内的指定页面。 1268 1269从API version9开始不再维护，建议使用[pushUrl<sup>9+</sup>](#routerpushurl9) 1270 1271**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1272 1273**参数：** 1274 1275| 参数名 | 类型 | 必填 | 说明 | 1276| ------- | ------------------------------- | ---- | --------- | 1277| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | 1278 1279 1280**示例：** 1281 1282```ts 1283class innerParams { 1284 data3:number[] 1285 1286 constructor(tuple:number[]) { 1287 this.data3 = tuple 1288 } 1289} 1290 1291class routerParams { 1292 data1:string 1293 data2:innerParams 1294 1295 constructor(str:string, tuple:number[]) { 1296 this.data1 = str 1297 this.data2 = new innerParams(tuple) 1298 } 1299} 1300 1301router.push({ 1302 url: 'pages/routerpage2', 1303 params: new routerParams('message' ,[123,456,789]) 1304}); 1305``` 1306 1307## router.replace<sup>(deprecated)</sup> 1308 1309replace(options: RouterOptions): void 1310 1311用应用内的某个页面替换当前页面，并销毁被替换的页面。 1312 1313从API version9开始不再维护，建议使用[replaceUrl<sup>9+</sup>](#routerreplaceurl9) 1314 1315**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 1316 1317**参数：** 1318 1319| 参数名 | 类型 | 必填 | 说明 | 1320| ------- | ------------------------------- | ---- | ------------------ | 1321| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | 1322 1323**示例：** 1324 1325```ts 1326class routerParams { 1327 data1:string 1328 1329 constructor(str:string) { 1330 this.data1 = str 1331 } 1332} 1333 1334router.replace({ 1335 url: 'pages/detail', 1336 params: new routerParams('message') 1337}); 1338``` 1339 1340## router.enableAlertBeforeBackPage<sup>(deprecated)</sup> 1341 1342enableAlertBeforeBackPage(options: EnableAlertOptions): void 1343 1344开启页面返回询问对话框。 1345 1346从API version9开始不再维护，建议使用[showAlertBeforeBackPage<sup>9+</sup>](#routershowalertbeforebackpage9) 1347 1348**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1349 1350**参数：** 1351 1352| 参数名 | 类型 | 必填 | 说明 | 1353| ------- | ---------------------------------------- | ---- | --------- | 1354| options | [EnableAlertOptions](#enablealertoptions) | 是 | 文本弹窗信息描述。 | 1355 1356**示例：** 1357 1358```ts 1359router.enableAlertBeforeBackPage({ 1360 message: 'Message Info' 1361}); 1362``` 1363 1364## router.disableAlertBeforeBackPage<sup>(deprecated)</sup> 1365 1366disableAlertBeforeBackPage(): void 1367 1368禁用页面返回询问对话框。 1369 1370从API version9开始不再维护，建议使用[hideAlertBeforeBackPage<sup>9+</sup>](#routerhidealertbeforebackpage9) 1371 1372**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1373 1374**示例：** 1375 1376```ts 1377router.disableAlertBeforeBackPage(); 1378```