diff --git a/zh-cn/application-dev/reference/apis/js-apis-router.md b/zh-cn/application-dev/reference/apis/js-apis-router.md index 51f8738c2fdf55c470c2d5e4d4159e459974912b..1dc12db497acbd47e933bfcdec3848ce5fff94d1 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-router.md +++ b/zh-cn/application-dev/reference/apis/js-apis-router.md @@ -2,9 +2,10 @@ 本模块提供通过不同的url访问不同的页面，包括跳转到应用内的指定页面、用应用内的某个页面替换当前页面、返回上一页面或指定的页面等。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明** +> **说明** > > - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> > - 页面路由需要在页面渲染完成之后才能调用，在onInit和onReady生命周期中页面还处于渲染阶段，禁止调用页面路由方法。 ## 导入模块 @@ -13,59 +14,60 @@ import router from '@ohos.router' ``` -## 权限列表 - -无 - ## router.push -push(options: RouterOptions, mode?: RouterMode): void +push(options: RouterOptions): void 跳转到应用内的指定页面。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | -| mode9+ | [RouterMode](#routermode9) | 否 | 跳转页面使用的模式。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------- | ---- | ------------------ | +| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | **示例：** ```js - // 在当前页面中 - export default { - pushPage() { - router.push({ - url: 'pages/routerpage2/routerpage2', - params: { - data1: 'message', - data2: { - data3: [123, 456, 789] - }, - }, - }); - } - } +router.push({ + url: 'pages/routerpage2', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] + }, + }, +}); ``` +## router.push9+ + +push(options: RouterOptions, mode: RouterMode): void + +跳转到应用内的指定页面。 + +**系统能力：** SystemCapability.ArkUI.ArkUI.Full + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ----------------- | ------------------------------- | ---- | -------------------- | +| options | [RouterOptions](#routeroptions) | 是 | 跳转页面描述信息。 | +| mode9+ | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | + + +**示例：** ```js - // 在routerpage2页面中 - export default { - data: { - data1: 'default', - data2: { - data3: [1, 2, 3] - } +router.push({ + url: 'pages/routerpage2/routerpage2', + params: { + data1: 'message', + data2: { + data3: [123, 456, 789] }, - onInit() { - console.info('showData1:' + this.data1); - console.info('showData3:' + this.data2.data3); - } - } + }, +},router.RouterMode.Standard); ``` - ## router.replace replace(options: RouterOptions, mode?: RouterMode): void @@ -75,37 +77,44 @@ replace(options: RouterOptions, mode?: RouterMode): void **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | -| mode9+ | [RouterMode](#routermode9) | 否 | 跳转页面使用的模式。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------- | ---- | ------------------ | +| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | **示例：** ```js - // 在当前页面中 - export default { - replacePage() { - router.replace({ - url: 'pages/detail/detail', - params: { - data1: 'message', - }, - }, router.RouterMode.Standard); - } - } +router.replace({ + url: 'pages/detail', + params: { + data1: 'message', + }, +}); ``` + ## router.replace9+ + +replace(options: RouterOptions, mode: RouterMode): void + +用应用内的某个页面替换当前页面，并销毁被替换的页面。 + +**系统能力：** SystemCapability.ArkUI.ArkUI.Full + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ----------------- | ------------------------------- | ---- | -------------------- | +| options | [RouterOptions](#routeroptions) | 是 | 替换页面描述信息。 | +| mode9+ | [RouterMode](#routermode9) | 是 | 跳转页面使用的模式。 | + +**示例：** + ```js - // 在detail页面中 - export default { - data: { - data1: 'default' - }, - onInit() { - console.info('showData1:' + this.data1) - } - } +router.replace({ + url: 'pages/detail/detail', + params: { + data1: 'message', + }, +}, router.RouterMode.Standard); ``` ## router.back @@ -117,58 +126,14 @@ back(options?: RouterOptions ): void **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| options | [RouterOptions](#routeroptions) | 是 | 返回页面描述信息，其中参数url指路由跳转时会返回到指定url的界面，如果页面栈上没有url页面，则不响应该情况。如果url未设置，则返回上一页。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------- | ---- | ------------------------------------------------------------ | +| options | [RouterOptions](#routeroptions) | 否 | 返回页面描述信息，其中参数url指路由跳转时会返回到指定url的界面，如果页面栈上没有url页面，则不响应该情况。如果url未设置，则返回上一页。 | **示例：** - ```js - // index页面 - export default { - indexPushPage() { - router.push({ - url: 'pages/detail/detail', - }); - } - } - ``` - - ```js - // detail页面 - export default { - detailPushPage() { - router.push({ - url: 'pages/mall/mall', - }); - } - } - ``` ```js - // mall页面通过back，将返回detail页面 - export default { - mallBackPage() { - router.back(); - } - } - ``` - - ```js - // detail页面通过back，将返回index页面 - export default { - defaultBack() { - router.back(); - } - } - ``` - - ```js - // 通过back，返回到detail页面 - export default { - backToDetail() { - router.back({uri:'pages/detail/detail'}); - } - } +router.back({uri:'pages/detail'}); ``` ## router.clear @@ -180,12 +145,9 @@ clear(): void **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** + ```js - export default { - clearPage() { - router.clear(); - } - }js +router.clear(); ``` ## router.getLength @@ -197,18 +159,14 @@ getLength(): string **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** -| 类型 | 说明 | -| -------- | -------- | +| 类型 | 说明 | +| ------ | ---------------------------------- | | string | 页面数量，页面栈支持最大数值是32。 | **示例：** ```js - export default { - getLength() { - var size = router.getLength(); - console.log('pages stack size = ' + size); - } - } +var size = router.getLength(); +console.log('pages stack size = ' + size); ``` ## router.getState @@ -224,28 +182,26 @@ getState(): RouterState | 类型 | 说明 | | --------------------------- | -------------- | | [RouterState](#routerstate) | 页面状态信息。 | +**示例：** + +```js +var page = router.getState(); +console.log('current index = ' + page.index); +console.log('current name = ' + page.name); +console.log('current path = ' + page.path); +``` + ## RouterState -页面状态信息。 -**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。 +页面状态信息。 -| 名称 | 类型 | 说明 | -| -------- | -------- | -------- | -| index | number | 表示当前页面在页面栈中的索引。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> 从栈底到栈顶，index从1开始递增。 | -| name | string | 表示当前页面的名称，即对应文件名。 | -| path | string | 表示当前页面的路径。 | +**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 -**示例：** - ```js - export default { - getState() { - var page = router.getState(); - console.log('current index = ' + page.index); - console.log('current name = ' + page.name); - console.log('current path = ' + page.path); - } - } - ``` +| 名称 | 类型 | 说明 | +| ----- | ------ | ------------------------------------------------------------ | +| index | number | 表示当前页面在页面栈中的索引。从栈底到栈顶，index从1开始递增。 | +| name | string | 表示当前页面的名称，即对应文件名。 | +| path | string | 表示当前页面的路径。 | ## router.enableAlertBeforeBackPage @@ -256,26 +212,16 @@ enableAlertBeforeBackPage(options: EnableAlertOptions): void **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| options | [EnableAlertOptions](#enablealertoptions) | 是 | 文本弹窗信息描述。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------------- | ---- | ------------------ | +| options | [EnableAlertOptions](#enablealertoptions) | 是 | 文本弹窗信息描述。 | **示例：** - ```js - export default { - enableAlertBeforeBackPage() { - router.enableAlertBeforeBackPage({ - message: 'Message Info', - success: function() { - console.log('success'); - }, - fail: function() { - console.log('fail'); - }, - }); - } - } + ```js + router.enableAlertBeforeBackPage({ + message: 'Message Info' + }); ``` ## EnableAlertOptions @@ -283,9 +229,9 @@ enableAlertBeforeBackPage(options: EnableAlertOptions): void **系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。 -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| message | string | 是 | 询问对话框内容。 | +| 名称 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ---------------- | +| message | string | 是 | 询问对话框内容。 | ## router.disableAlertBeforeBackPage @@ -297,11 +243,7 @@ disableAlertBeforeBackPage(): void **示例：** ```js - export default { - disableAlertBeforeBackPage() { - router.disableAlertBeforeBackPage(); - } - } +router.disableAlertBeforeBackPage(); ``` ## router.getParams @@ -320,133 +262,140 @@ getParams(): Object **示例：** -- 类Web范示例 - ```js - // 在当前页面中 - export default { - pushPage() { - router.push({ - url: 'pages/detail/detail', - params: { - data1: 'message', - }, - }); - } - } - ``` - ```js - // 在detail页面中 - export default { - onInit() { - console.info('showData1:' + router.getParams().data1); - } - } - ``` - -- 声明式示例 - - ```ts - //通过router.push跳转至目标页携带params参数 - import router from '@ohos.router' - - @Entry - @Component - struct Index { - async routePage() { - let options = { - url: 'pages/second', - params: { - text: '这是第一页的值', - data: { - array: [12, 45, 78] - }, - } - } - try { - await router.push(options) - } catch (err) { - console.info(` fail callback, code: ${err.code}, msg: ${err.msg}`) - } - } - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Text('这是第一页') - .fontSize(50) - .fontWeight(FontWeight.Bold) - Button() { - Text('next page') - .fontSize(25) - .fontWeight(FontWeight.Bold) - }.type(ButtonType.Capsule) - .margin({ top: 20 }) - .backgroundColor('#ccc') - .onClick(() => { - this.routePage() - }) - } - .width('100%') - .height('100%') - } - } - ``` - - ```ts - //在second页面中接收传递过来的参数 - import router from '@ohos.router' - - @Entry - @Component - struct Second { - private content: string = "这是第二页" - @State text: string = router.getParams()['text'] - @State data: any = router.getParams()['data'] - @State secondData : string = '' - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Text(`${this.content}`) - .fontSize(50) - .fontWeight(FontWeight.Bold) - Text(this.text) - .fontSize(30) - .onClick(()=>{ - this.secondData = (this.data.array[1]).toString() - }) - .margin({top:20}) - Text('第一页传来的数值' + ' ' + this.secondData) - .fontSize(20) - .margin({top:20}) - .backgroundColor('red') - } - .width('100%') - .height('100%') - } - } - ``` +``` +router.getParams(); +``` ## RouterOptions 路由跳转选项。 -**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Lite。 +**系统能力：** SystemCapability.ArkUI.ArkUI.FULL。 -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| url | string | 是 | 表示目标页面的uri，可以用以下两种格式：
- 页面绝对路径，由配置文件中pages列表提供，例如：
  - pages/index/index
  - pages/detail/detail
- 特殊值，如果uri的值是"/"，则跳转到首页。 | -| params | Object | 否 | 跳转时要同时传递到目标页面的数据，跳转到目标页面后，参数可以在页面中直接使用，如this.data1(data1为跳转时params参数中的key值)。如果目标页面中已有该字段，则其值会被传入的字段值覆盖。 | +| 名称 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| url | string | 是 | 表示目标页面的uri，可以用以下两种格式：
- 页面绝对路径，由配置文件中pages列表提供，例如：
  - pages/index/index
  - pages/detail/detail
- 特殊值，如果uri的值是"/"，则跳转到首页。 | +| params | Object | 否 | 跳转时要同时传递到目标页面的数据，跳转到目标页面后，参数可以在页面中直接使用，如this.data1(data1为跳转时params参数中的key值)。如果目标页面中已有该字段，则其值会被传入的字段值覆盖。 | - > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** + > **说明：** > 页面路由栈支持的最大Page数量为32。 ## RouterMode9+ 路由跳转模式。 -**系统能力：** 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Lite。 +**系统能力：** SystemCapability.ArkUI.ArkUI.FULL。 + +| 名称 | 描述 | +| -------- | ------------------------------------------------------------ | +| Standard | 标准模式。 | +| Single | 单实例模式。
如果目标页面的url在页面栈中已经存在同url页面，离栈顶最近的页面会被移动到栈顶，移动后的页面为新建页。
如目标页面的url在页面栈中不存在同url页面，按标准模式跳转。 | + +## 完整示例 + +### 基于JS扩展的类Web开发范式 + +```js +// 在当前页面中 +export default { + pushPage() { + router.push({ + url: 'pages/detail/detail', + params: { + data1: 'message', + }, + }); + } +} +``` +```js +// 在detail页面中 +export default { + onInit() { + console.info('showData1:' + router.getParams().data1); + } +} +``` + +### 基于TS扩展的声明式开发范式 -| 名称 | 描述 | -| -------- | -------- | -| Standard | 标准模式。 | -| Single | 单实例模式。
如果目标页面的url在页面栈中已经存在同url页面，离栈顶最近的页面会被移动到栈顶，移动后的页面为新建页。
如目标页面的url在页面栈中不存在同url页面，按标准模式跳转。 | +```ts +//通过router.push跳转至目标页携带params参数 +import router from '@ohos.router' + +@Entry +@Component +struct Index { + async routePage() { + let options = { + url: 'pages/second', + params: { + text: '这是第一页的值', + data: { + array: [12, 45, 78] + }, + } + } + try { + await router.push(options) + } catch (err) { + console.info(` fail callback, code: ${err.code}, msg: ${err.msg}`) + } + } + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Text('这是第一页') + .fontSize(50) + .fontWeight(FontWeight.Bold) + Button() { + Text('next page') + .fontSize(25) + .fontWeight(FontWeight.Bold) + }.type(ButtonType.Capsule) + .margin({ top: 20 }) + .backgroundColor('#ccc') + .onClick(() => { + this.routePage() + }) + } + .width('100%') + .height('100%') + } +} +``` + +```ts +//在second页面中接收传递过来的参数 +import router from '@ohos.router' + +@Entry +@Component +struct Second { + private content: string = "这是第二页" + @State text: string = router.getParams()['text'] + @State data: any = router.getParams()['data'] + @State secondData : string = '' + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Text(`${this.content}`) + .fontSize(50) + .fontWeight(FontWeight.Bold) + Text(this.text) + .fontSize(30) + .onClick(()=>{ + this.secondData = (this.data.array[1]).toString() + }) + .margin({top:20}) + Text('第一页传来的数值' + ' ' + this.secondData) + .fontSize(20) + .margin({top:20}) + .backgroundColor('red') + } + .width('100%') + .height('100%') + } +} +``` \ No newline at end of file