1# @system.router (页面路由) 2 3通过不同的uri访问不同的页面。 4 5> **说明：** 6> 7> - 从API Version 8 开始，该接口不再维护，推荐使用新接口[`@ohos.router`](js-apis-router.md)。 8> 9> 10> - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 11 12 13## 导入模块 14 15 16```js 17import router from '@system.router'; 18``` 19 20## router.push 21 22push(options: RouterOptions): void 23 24跳转到应用内的指定页面。 25 26**系统能力：** SystemCapability.ArkUI.ArkUI.Full 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| ------- | ------------------------------- | ---- | -------------------------- | 32| options | [RouterOptions](#routeroptions) | 是 | 页面路由参数，详细请参考RouterOptions。 | 33 34**示例：** 35 36```js 37// 在当前页面中 38export default { 39 pushPage() { 40 router.push({ 41 uri: 'pages/routerpage2/routerpage2', 42 params: { 43 data1: 'message', 44 data2: { 45 data3: [123, 456, 789] 46 } 47 } 48 }); 49 } 50} 51``` 52 53 54```js 55// 在routerpage2页面中 56export default { 57 data: { 58 data1: 'default', 59 data2: { 60 data3: [1, 2, 3] 61 } 62 }, 63 onInit() { 64 console.info('showData1:' + this.data1); 65 console.info('showData3:' + this.data2.data3); 66 } 67} 68``` 69 70>  **说明：** 71> 页面路由栈支持的最大Page数量为32。 72 73 74## router.replace 75 76replace(options: RouterOptions): void 77 78用应用内的某个页面替换当前页面，并销毁被替换的页面。 79 80**系统能力：** SystemCapability.ArkUI.ArkUI.Lite 81 82**参数：** 83 84| 参数名 | 类型 | 必填 | 说明 | 85| ------- | ------------------------------- | ---- | -------------------------- | 86| options | [RouterOptions](#routeroptions) | 是 | 页面路由参数，详细请参考RouterOptions。 | 87 88**示例：** 89 90```js 91// 在当前页面中 92export default { 93 replacePage() { 94 router.replace({ 95 uri: 'pages/detail/detail', 96 params: { 97 data1: 'message' 98 } 99 }); 100 } 101} 102``` 103 104 105```js 106// 在detail页面中 107export default { 108 data: { 109 data1: 'default' 110 }, 111 onInit() { 112 console.info('showData1:' + this.data1) 113 } 114} 115``` 116 117## router.back 118 119back(options?: BackRouterOptions): void 120 121返回上一页面或指定的页面。 122 123**系统能力：** SystemCapability.ArkUI.ArkUI.Full 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| ------- | --------------------------------------- | ---- | ----------------------- | 129| options | [BackRouterOptions](#backrouteroptions) | 否 | 详细请参考BackRouterOptions。 | 130 131**示例：** 132 133```js 134// index页面 135export default { 136 indexPushPage() { 137 router.push({ 138 uri: 'pages/detail/detail' 139 }); 140 } 141} 142``` 143 144 145```js 146// detail页面 147export default { 148 detailPushPage() { 149 router.push({ 150 uri: 'pages/mall/mall' 151 }); 152 } 153} 154``` 155 156 157```js 158// mall页面通过back，将返回detail页面 159export default { 160 mallBackPage() { 161 router.back(); 162 } 163} 164``` 165 166 167```js 168// detail页面通过back，将返回index页面 169export default { 170 defaultBack() { 171 router.back(); 172 } 173} 174``` 175 176 177```js 178// 通过back，返回到detail页面 179export default { 180 backToDetail() { 181 router.back({uri:'pages/detail/detail'}); 182 } 183} 184``` 185 186>  **说明：** 187> 示例中的uri字段是页面路由，由配置文件中的pages列表指定。 188 189## router.getParams<sup>7+</sup> 190 191getParams(): ParamsInterface 192 193获取当前页面的参数信息。 194 195**系统能力：** SystemCapability.ArkUI.ArkUI.Full 196 197**返回值：** 198 199| 类型 | 说明 | 200| ----------------------------------- | --------------------- | 201| [ParamsInterface](#paramsinterface) | 详细请参见ParamsInterface。 | 202 203## router.clear 204 205clear(): void 206 207清空页面栈中的所有历史页面，仅保留当前页面作为栈顶页面。 208 209**系统能力：** SystemCapability.ArkUI.ArkUI.Full 210 211**示例：** 212 213```js 214export default { 215 clearPage() { 216 router.clear(); 217 } 218} 219``` 220 221## router.getLength 222 223getLength(): string 224 225获取当前在页面栈内的页面数量。 226 227**系统能力：** SystemCapability.ArkUI.ArkUI.Full 228 229**返回值：** 230 231| 类型 | 说明 | 232| ------ | ------------------ | 233| string | 页面数量，页面栈支持最大数值是32。 | 234 235**示例：** 236 237```js 238export default { 239 getLength() { 240 let size = router.getLength(); 241 console.log('pages stack size = ' + size); 242 } 243} 244``` 245 246## router.getState 247 248getState(): RouterState 249 250获取当前页面的状态信息。 251 252**系统能力：** SystemCapability.ArkUI.ArkUI.Full 253 254**返回值：** 255 256| 参数类型 | 说明 | 257| --------------------------- | ----------------- | 258| [RouterState](#routerstate) | 详细请参见RouterState。 | 259 260**示例：** 261 262```js 263export default { 264 getState() { 265 let page = router.getState(); 266 console.log('current index = ' + page.index); 267 console.log('current name = ' + page.name); 268 console.log('current path = ' + page.path); 269 } 270} 271``` 272 273## router.enableAlertBeforeBackPage<sup>6+</sup> 274 275enableAlertBeforeBackPage(options: EnableAlertBeforeBackPageOptions): void 276 277开启页面返回询问对话框。 278 279**系统能力：** SystemCapability.ArkUI.ArkUI.Full 280 281**参数：** 282 283| 参数名 | 类型 | 必填 | 说明 | 284| ------- | ---------------------------------------- | ---- | -------------------------------------- | 285| options | [EnableAlertBeforeBackPageOptions](#enablealertbeforebackpageoptions6) | 是 | 详细请参见EnableAlertBeforeBackPageOptions。 | 286 287**示例：** 288 289```js 290export default { 291 enableAlertBeforeBackPage() { 292 router.enableAlertBeforeBackPage({ 293 message: 'Message Info', 294 success: function() { 295 console.log('success'); 296 }, 297 cancel: function() { 298 console.log('cancel'); 299 } 300 }); 301 } 302} 303``` 304 305## router.disableAlertBeforeBackPage<sup>6+</sup> 306 307disableAlertBeforeBackPage(options?: DisableAlertBeforeBackPageOptions): void 308 309禁用页面返回询问对话框。 310 311**系统能力：** SystemCapability.ArkUI.ArkUI.Full 312 313**参数：** 314 315| 参数名 | 类型 | 必填 | 说明 | 316| ------- | ---------------------------------------- | ---- | --------------------------------------- | 317| options | [DisableAlertBeforeBackPageOptions](#disablealertbeforebackpageoptions6) | 否 | 详细请参见DisableAlertBeforeBackPageOptions。 | 318 319**示例：** 320 321```js 322export default { 323 disableAlertBeforeBackPage() { 324 router.disableAlertBeforeBackPage({ 325 success: function() { 326 console.log('success'); 327 }, 328 cancel: function() { 329 console.log('cancel'); 330 } 331 }); 332 } 333} 334``` 335 336## RouterOptions 337 338定义路由器的选项。 339 340**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Lite 341 342| 名称 | 类型 | 必填 | 说明 | 343| ------ | -------- | ---- | ------------------------------------------------------------ | 344| uri<sup>7+</sup> | string | 是 | 目标页面的uri，可以是以下的两种格式：<br/>1. 页面的绝对路径，由config.json文件中的页面列表提供。例如：<br/>- pages/index/index<br/> -pages/detail/detail<br/>2. 特定路径。如果URI为斜杠（/），则显示主页。 | 345| params<sup>7+</sup> | object | 否 | 表示路由跳转时要同时传递到目标页面的数据。跳转到目标页面后，使用router.getParams()获取传递的参数，此外，在类web范式中，参数也可以在页面中直接使用，如this.keyValue(keyValue为跳转时params参数中的key值)，如果目标页面中已有该字段，则其值会被传入的字段值覆盖。 | 346 347 348## BackRouterOptions 349 350定义路由器返回的选项。 351 352**系统能力：** 以下各项对应的系统能力有所不同，详见下表。 353 354| 名称 | 类型 | 必填 | 说明 | 355| ------ | -------- | ---- | ------------------------------------------------------------ | 356| uri<sup>7+</sup> | string | 否 | 返回到指定uri的界面，如果页面栈上没有uri页面，则不响应该情况。如果uri未设置，则返回上一页。 <br>**系统能力：** SystemCapability.ArkUI.ArkUI.Full | 357| params<sup>7+</sup> | object | 否 | 跳转时要同时传递到目标页面的数据。 <br>**系统能力：** SystemCapability.ArkUI.ArkUI.Lite | 358 359## RouterState 360 361定义路由器的状态。 362 363**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full 364 365| 名称 | 类型 | 必填 | 说明 | 366| ----- | ------ | ---- | ---------------------------------- | 367| index | number | 是 | 表示当前页面在页面栈中的索引。从栈底到栈顶，index从1开始递增。 | 368| name | string | 是 | 表示当前页面的名称，即对应文件名。 | 369| path | string | 是 | 表示当前页面的路径。 | 370 371## EnableAlertBeforeBackPageOptions<sup>6+</sup> 372 373定义EnableAlertBeforeBackPage选项。 374 375**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full 376 377| 名称 | 类型 | 必填 | 说明 | 378| -------- | ------------------------ | ---- | -------------------------------------------------- | 379| message | string | 是 | 询问对话框内容。 | 380| success | (errMsg: string) => void | 否 | 用户选择对话框确认按钮时触发，errMsg表示返回信息。 | 381| cancel | (errMsg: string) => void | 否 | 用户选择对话框取消按钮时触发，errMsg表示返回信息。 | 382| complete | () => void | 否 | 当对话框关闭时触发该回调。 | 383 384## DisableAlertBeforeBackPageOptions<sup>6+</sup> 385 386定义DisableAlertBeforeBackPage参数选项。 387 388**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full 389 390| 名称 | 类型 | 必填 | 说明 | 391| -------- | ------------------------ | ---- | -------------------------------------------------- | 392| success | (errMsg: string) => void | 否 | 关闭询问对话框能力成功时触发，errMsg表示返回信息。 | 393| cancel | (errMsg: string) => void | 否 | 关闭询问对话框能力失败时触发，errMsg表示返回信息。 | 394| complete | () => void | 否 | 当对话框关闭时触发该回调。 | 395 396## ParamsInterface 397 398| 名称 | 参数类型 | 说明 | 399| ------------- | -------- | -------------- | 400| [key: string] | object | 路由参数列表。 | 401
