页面路由
本模块提供通过不同的url访问不同的页面,包括跳转到应用内的指定页面、用应用内的某个页面替换当前页面、返回上一页面或指定的页面等。
本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
页面路由需要在页面渲染完成之后才能调用,在onInit和onReady生命周期中页面还处于渲染阶段,禁止调用页面路由方法。
router.pushUrl9+
pushUrl(options: RouterOptions): Promise<void>
跳转到应用内的指定页面。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 跳转页面描述信息。 |
返回值:
类型 | 说明 |
---|---|
Promise<void> | 异常返回结果。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if UI execution context not found. |
100002 | if the uri is not exist. |
100003 | if the pages are pushed too much. |
示例:
- router.pushUrl({
- url: 'pages/routerpage2',
- params: {
- data1: 'message',
- data2: {
- data3: [123, 456, 789]
- }
- }
- })
- .then(() => {
- // success
- })
- .catch(err => {
- console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
- })
router.pushUrl9+
pushUrl(options: RouterOptions, callback: AsyncCallback<void>): void
跳转到应用内的指定页面。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 跳转页面描述信息。 | |
callback | AsyncCallback<void> | 是 | 异常响应回调。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if UI execution context not found. |
100002 | if the uri is not exist. |
100003 | if the pages are pushed too much. |
示例:
- router.pushUrl({
- url: 'pages/routerpage2',
- params: {
- data1: 'message',
- data2: {
- data3: [123, 456, 789]
- }
- }
- }, (err) => {
- if (err) {
- console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
- return;
- }
- console.info('pushUrl success');
- });
router.pushUrl9+
pushUrl(options: RouterOptions, mode: RouterMode): Promise<void>
跳转到应用内的指定页面。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 跳转页面描述信息。 | |
mode | 是 | 跳转页面使用的模式。 |
返回值:
类型 | 说明 |
---|---|
Promise<void> | 异常返回结果。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if UI execution context not found. |
100002 | if the uri is not exist. |
100003 | if the pages are pushed too much. |
示例:
- router.pushUrl({
- url: 'pages/routerpage2',
- params: {
- data1: 'message',
- data2: {
- data3: [123, 456, 789]
- }
- }
- }, router.RouterMode.Standard)
- .then(() => {
- // success
- })
- .catch(err => {
- console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
- })
router.pushUrl9+
pushUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void
跳转到应用内的指定页面。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 跳转页面描述信息。 | |
mode | 是 | 跳转页面使用的模式。 | |
callback | AsyncCallback<void> | 是 | 异常响应回调。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if UI execution context not found. |
100002 | if the uri is not exist. |
100003 | if the pages are pushed too much. |
示例:
- router.pushUrl({
- url: 'pages/routerpage2',
- params: {
- data1: 'message',
- data2: {
- data3: [123, 456, 789]
- }
- }
- }, router.RouterMode.Standard, (err) => {
- if (err) {
- console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
- return;
- }
- console.info('pushUrl success');
- });
router.replaceUrl9+
replaceUrl(options: RouterOptions): Promise<void>
用应用内的某个页面替换当前页面,并销毁被替换的页面。不支持设置页面转场动效,如需设置,推荐使用Navigation组件。
系统能力: SystemCapability.ArkUI.ArkUI.Lite
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 替换页面描述信息。 |
返回值:
类型 | 说明 |
---|---|
Promise<void> | 异常返回结果。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if UI execution context not found, only throw in standard system. |
200002 | if the uri is not exist. |
示例:
- router.replaceUrl({
- url: 'pages/detail',
- params: {
- data1: 'message'
- }
- })
- .then(() => {
- // success
- })
- .catch(err => {
- console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
- })
router.replaceUrl9+
replaceUrl(options: RouterOptions, callback: AsyncCallback<void>): void
用应用内的某个页面替换当前页面,并销毁被替换的页面。
系统能力: SystemCapability.ArkUI.ArkUI.Lite
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 替换页面描述信息。 | |
callback | AsyncCallback<void> | 是 | 异常响应回调。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if UI execution context not found, only throw in standard system. |
200002 | if the uri is not exist. |
示例:
- router.replaceUrl({
- url: 'pages/detail',
- params: {
- data1: 'message'
- }
- }, (err) => {
- if (err) {
- console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
- return;
- }
- console.info('replaceUrl success');
- });
router.replaceUrl9+
replaceUrl(options: RouterOptions, mode: RouterMode): Promise<void>
用应用内的某个页面替换当前页面,并销毁被替换的页面。
系统能力: SystemCapability.ArkUI.ArkUI.Lite
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 替换页面描述信息。 | |
mode | 是 | 跳转页面使用的模式。 |
返回值:
类型 | 说明 |
---|---|
Promise<void> | 异常返回结果。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if can not get the delegate, only throw in standard system. |
200002 | if the uri is not exist. |
示例:
- router.replaceUrl({
- url: 'pages/detail',
- params: {
- data1: 'message'
- }
- }, router.RouterMode.Standard)
- .then(() => {
- // success
- })
- .catch(err => {
- console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
- })
router.replaceUrl9+
replaceUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void
用应用内的某个页面替换当前页面,并销毁被替换的页面。
系统能力: SystemCapability.ArkUI.ArkUI.Lite
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 替换页面描述信息。 | |
mode | 是 | 跳转页面使用的模式。 | |
callback | AsyncCallback<void> | 是 | 异常响应回调。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if UI execution context not found, only throw in standard system. |
200002 | if the uri is not exist. |
示例:
- router.replaceUrl({
- url: 'pages/detail',
- params: {
- data1: 'message'
- }
- }, router.RouterMode.Standard, (err) => {
- if (err) {
- console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
- return;
- }
- console.info('replaceUrl success');
- });
router.back
back(options?: RouterOptions ): void
返回上一页面或指定的页面。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 否 | 返回页面描述信息,其中参数url指路由跳转时会返回到指定url的界面,如果页面栈上没有url页面,则不响应该情况。如果url未设置,则返回上一页,页面不会重新构建,页面栈里面的page不会回收,出栈后会被回收。 |
示例:
- router.back({url:'pages/detail'});
router.clear
clear(): void
清空页面栈中的所有历史页面,仅保留当前页面作为栈顶页面。
系统能力: SystemCapability.ArkUI.ArkUI.Full
示例:
- router.clear();
router.getLength
getLength(): string
获取当前在页面栈内的页面数量。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
string | 页面数量,页面栈支持最大数值是32。 |
示例:
- let size = router.getLength();
- console.log('pages stack size = ' + size);
router.getState
getState(): RouterState
获取当前页面的状态信息。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
页面状态信息。 |
示例:
- let 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 | 是 | 表示当前页面在页面栈中的索引。从栈底到栈顶,index从1开始递增。 |
name | string | 否 | 表示当前页面的名称,即对应文件名。 |
path | string | 是 | 表示当前页面的路径。 |
router.showAlertBeforeBackPage9+
showAlertBeforeBackPage(options: EnableAlertOptions): void
开启页面返回询问对话框。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 文本弹窗信息描述。 |
错误码:
以下错误码的详细介绍请参见ohos.router(页面路由)错误码。
错误码ID | 错误信息 |
---|---|
100001 | if UI execution context not found. |
示例:
- import { BusinessError } from '@ohos.base';
- try {
- router.showAlertBeforeBackPage({
- message: 'Message Info'
- });
- } catch(err) {
- console.error(`Invoke showAlertBeforeBackPage failed, code is ${err.code}, message is ${err.message}`);
- }
EnableAlertOptions
页面返回询问对话框选项。
系统能力: 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
message | string | 是 | 询问对话框内容。 |
router.hideAlertBeforeBackPage9+
hideAlertBeforeBackPage(): void
禁用页面返回询问对话框。
系统能力: SystemCapability.ArkUI.ArkUI.Full
示例:
- router.hideAlertBeforeBackPage();
router.getParams
getParams(): Object
获取发起跳转的页面往当前页传入的参数。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
类型 | 说明 |
---|---|
object | 发起跳转的页面往当前页传入的参数。 |
示例:
- router.getParams();
RouterOptions
路由跳转选项。
系统能力: SystemCapability.ArkUI.ArkUI.Lite。
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
url | string | 是 | 表示目标页面的url,可以用以下两种格式: - 页面绝对路径,由配置文件中pages列表提供,例如: - pages/index/index - pages/detail/detail - 特殊值,如果url的值是"/",则跳转到首页。 |
params | object | 否 | 表示路由跳转时要同时传递到目标页面的数据,切换到其他页面时,当前接收的数据失效。跳转到目标页面后,使用router.getParams()获取传递的参数,此外,在类web范式中,参数也可以在页面中直接使用,如this.keyValue(keyValue为跳转时params参数中的key值),如果目标页面中已有该字段,则其值会被传入的字段值覆盖。 说明: params参数不能传递方法和系统接口返回的对象(例如,媒体接口定义和返回的PixelMap对象)。建议开发者提取系统接口返回的对象中需要被传递的基础类型属性,自行构造object类型对象进行传递。 |
页面路由栈支持的最大Page数量为32。
RouterMode9+
路由跳转模式。
系统能力: SystemCapability.ArkUI.ArkUI.Full。
名称 | 说明 |
---|---|
Standard | 多实例模式,也是默认情况下的跳转模式。 目标页面会被添加到页面栈顶,无论栈中是否存在相同url的页面。 说明: 不使用路由跳转模式时,则按照默认的多实例模式进行跳转。 |
Single | 单实例模式。 如果目标页面的url已经存在于页面栈中,则该url页面移动到栈顶。 如果目标页面的url在页面栈中不存在同url页面,则按照默认的多实例模式进行跳转。 |
基于JS扩展的类Web开发范式
- // 在当前页面中
- export default {
- pushPage() {
- router.push({
- url: 'pages/detail/detail',
- params: {
- data1: 'message'
- }
- });
- }
- }
- // 在detail页面中
- export default {
- onInit() {
- console.info('showData1:' + router.getParams()['data1']);
- }
- }
基于TS扩展的声明式开发范式
- // 通过router.pushUrl跳转至目标页携带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.pushUrl(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%')
- }
- }
- // 在second页面中接收传递过来的参数
- import router from '@ohos.router'
- @Entry
- @Component
- struct Second {
- private content: string = "这是第二页"
- @State text: string = router.getParams()['text']
- @State data: object = 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.push(deprecated)
push(options: RouterOptions): void
跳转到应用内的指定页面。
从API version9开始不再维护,建议使用pushUrl9+
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 跳转页面描述信息。 |
示例:
- router.push({
- url: 'pages/routerpage2',
- params: {
- data1: 'message',
- data2: {
- data3: [123, 456, 789]
- }
- }
- });
router.replace(deprecated)
replace(options: RouterOptions): void
用应用内的某个页面替换当前页面,并销毁被替换的页面。
从API version9开始不再维护,建议使用replaceUrl9+
系统能力: SystemCapability.ArkUI.ArkUI.Lite
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 替换页面描述信息。 |
示例:
- router.replace({
- url: 'pages/detail',
- params: {
- data1: 'message'
- }
- });
router.enableAlertBeforeBackPage(deprecated)
enableAlertBeforeBackPage(options: EnableAlertOptions): void
开启页面返回询问对话框。
从API version9开始不再维护,建议使用showAlertBeforeBackPage9+
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
options | 是 | 文本弹窗信息描述。 |
示例:
- router.enableAlertBeforeBackPage({
- message: 'Message Info'
- });
router.disableAlertBeforeBackPage(deprecated)
disableAlertBeforeBackPage(): void
禁用页面返回询问对话框。
从API version9开始不再维护,建议使用hideAlertBeforeBackPage9+
系统能力: SystemCapability.ArkUI.ArkUI.Full
示例:
- router.disableAlertBeforeBackPage();
更多建议: