页面路由

2024-01-23 13:12 更新

本模块提供通过不同的url访问不同的页面,包括跳转到应用内的指定页面、用应用内的某个页面替换当前页面、返回上一页面或指定的页面等。

说明
  • 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

  • 页面路由需要在页面渲染完成之后才能调用,在onInit和onReady生命周期中页面还处于渲染阶段,禁止调用页面路由方法。

导入模块

  1. import router from '@ohos.router'

router.pushUrl9+

pushUrl(options: RouterOptions): Promise<void>

跳转到应用内的指定页面。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名

类型

必填

说明

options

RouterOptions

跳转页面描述信息。

返回值:

类型

说明

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.

示例:

  1. router.pushUrl({
  2. url: 'pages/routerpage2',
  3. params: {
  4. data1: 'message',
  5. data2: {
  6. data3: [123, 456, 789]
  7. }
  8. }
  9. })
  10. .then(() => {
  11. // success
  12. })
  13. .catch(err => {
  14. console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
  15. })

router.pushUrl9+

pushUrl(options: RouterOptions, callback: AsyncCallback<void>): void

跳转到应用内的指定页面。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名

类型

必填

说明

options

RouterOptions

跳转页面描述信息。

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.

示例:

  1. router.pushUrl({
  2. url: 'pages/routerpage2',
  3. params: {
  4. data1: 'message',
  5. data2: {
  6. data3: [123, 456, 789]
  7. }
  8. }
  9. }, (err) => {
  10. if (err) {
  11. console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
  12. return;
  13. }
  14. console.info('pushUrl success');
  15. });

router.pushUrl9+

pushUrl(options: RouterOptions, mode: RouterMode): Promise<void>

跳转到应用内的指定页面。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名

类型

必填

说明

options

RouterOptions

跳转页面描述信息。

mode

RouterMode

跳转页面使用的模式。

返回值:

类型

说明

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.

示例:

  1. router.pushUrl({
  2. url: 'pages/routerpage2',
  3. params: {
  4. data1: 'message',
  5. data2: {
  6. data3: [123, 456, 789]
  7. }
  8. }
  9. }, router.RouterMode.Standard)
  10. .then(() => {
  11. // success
  12. })
  13. .catch(err => {
  14. console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
  15. })

router.pushUrl9+

pushUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void

跳转到应用内的指定页面。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名

类型

必填

说明

options

RouterOptions

跳转页面描述信息。

mode

RouterMode

跳转页面使用的模式。

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.

示例:

  1. router.pushUrl({
  2. url: 'pages/routerpage2',
  3. params: {
  4. data1: 'message',
  5. data2: {
  6. data3: [123, 456, 789]
  7. }
  8. }
  9. }, router.RouterMode.Standard, (err) => {
  10. if (err) {
  11. console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
  12. return;
  13. }
  14. console.info('pushUrl success');
  15. });

router.replaceUrl9+

replaceUrl(options: RouterOptions): Promise<void>

用应用内的某个页面替换当前页面,并销毁被替换的页面。不支持设置页面转场动效,如需设置,推荐使用Navigation组件。

系统能力: SystemCapability.ArkUI.ArkUI.Lite

参数:

参数名

类型

必填

说明

options

RouterOptions

替换页面描述信息。

返回值:

类型

说明

Promise<void>

异常返回结果。

错误码:

以下错误码的详细介绍请参见ohos.router(页面路由)错误码。

错误码ID

错误信息

100001

if UI execution context not found, only throw in standard system.

200002

if the uri is not exist.

示例:

  1. router.replaceUrl({
  2. url: 'pages/detail',
  3. params: {
  4. data1: 'message'
  5. }
  6. })
  7. .then(() => {
  8. // success
  9. })
  10. .catch(err => {
  11. console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
  12. })

router.replaceUrl9+

replaceUrl(options: RouterOptions, callback: AsyncCallback<void>): void

用应用内的某个页面替换当前页面,并销毁被替换的页面。

系统能力: SystemCapability.ArkUI.ArkUI.Lite

参数:

参数名

类型

必填

说明

options

RouterOptions

替换页面描述信息。

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.

示例:

  1. router.replaceUrl({
  2. url: 'pages/detail',
  3. params: {
  4. data1: 'message'
  5. }
  6. }, (err) => {
  7. if (err) {
  8. console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
  9. return;
  10. }
  11. console.info('replaceUrl success');
  12. });

router.replaceUrl9+

replaceUrl(options: RouterOptions, mode: RouterMode): Promise<void>

用应用内的某个页面替换当前页面,并销毁被替换的页面。

系统能力: SystemCapability.ArkUI.ArkUI.Lite

参数:

参数名

类型

必填

说明

options

RouterOptions

替换页面描述信息。

mode

RouterMode

跳转页面使用的模式。

返回值:

类型

说明

Promise<void>

异常返回结果。

错误码:

以下错误码的详细介绍请参见ohos.router(页面路由)错误码。

错误码ID

错误信息

100001

if can not get the delegate, only throw in standard system.

200002

if the uri is not exist.

示例:

  1. router.replaceUrl({
  2. url: 'pages/detail',
  3. params: {
  4. data1: 'message'
  5. }
  6. }, router.RouterMode.Standard)
  7. .then(() => {
  8. // success
  9. })
  10. .catch(err => {
  11. console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
  12. })

router.replaceUrl9+

replaceUrl(options: RouterOptions, mode: RouterMode, callback: AsyncCallback<void>): void

用应用内的某个页面替换当前页面,并销毁被替换的页面。

系统能力: SystemCapability.ArkUI.ArkUI.Lite

参数:

参数名

类型

必填

说明

options

RouterOptions

替换页面描述信息。

mode

RouterMode

跳转页面使用的模式。

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.

示例:

  1. router.replaceUrl({
  2. url: 'pages/detail',
  3. params: {
  4. data1: 'message'
  5. }
  6. }, router.RouterMode.Standard, (err) => {
  7. if (err) {
  8. console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
  9. return;
  10. }
  11. console.info('replaceUrl success');
  12. });

router.back

back(options?: RouterOptions ): void

返回上一页面或指定的页面。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名

类型

必填

说明

options

RouterOptions

返回页面描述信息,其中参数url指路由跳转时会返回到指定url的界面,如果页面栈上没有url页面,则不响应该情况。如果url未设置,则返回上一页,页面不会重新构建,页面栈里面的page不会回收,出栈后会被回收。

示例:

  1. router.back({url:'pages/detail'});

router.clear

clear(): void

清空页面栈中的所有历史页面,仅保留当前页面作为栈顶页面。

系统能力: SystemCapability.ArkUI.ArkUI.Full

示例:

  1. router.clear();

router.getLength

getLength(): string

获取当前在页面栈内的页面数量。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

类型

说明

string

页面数量,页面栈支持最大数值是32。

示例:

  1. let size = router.getLength();
  2. console.log('pages stack size = ' + size);

router.getState

getState(): RouterState

获取当前页面的状态信息。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

类型

说明

RouterState

页面状态信息。

示例:

  1. let page = router.getState();
  2. console.log('current index = ' + page.index);
  3. console.log('current name = ' + page.name);
  4. 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

EnableAlertOptions

文本弹窗信息描述。

错误码:

以下错误码的详细介绍请参见ohos.router(页面路由)错误码。

错误码ID

错误信息

100001

if UI execution context not found.

示例:

  1. import { BusinessError } from '@ohos.base';
  2. try {
  3. router.showAlertBeforeBackPage({
  4. message: 'Message Info'
  5. });
  6. } catch(err) {
  7. console.error(`Invoke showAlertBeforeBackPage failed, code is ${err.code}, message is ${err.message}`);
  8. }

EnableAlertOptions

页面返回询问对话框选项。

系统能力: 以下各项对应的系统能力均为SystemCapability.ArkUI.ArkUI.Full。

名称

类型

必填

说明

message

string

询问对话框内容。

router.hideAlertBeforeBackPage9+

hideAlertBeforeBackPage(): void

禁用页面返回询问对话框。

系统能力: SystemCapability.ArkUI.ArkUI.Full

示例:

  1. router.hideAlertBeforeBackPage();

router.getParams

getParams(): Object

获取发起跳转的页面往当前页传入的参数。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

类型

说明

object

发起跳转的页面往当前页传入的参数。

示例:

  1. 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开发范式

  1. // 在当前页面中
  2. export default {
  3. pushPage() {
  4. router.push({
  5. url: 'pages/detail/detail',
  6. params: {
  7. data1: 'message'
  8. }
  9. });
  10. }
  11. }
  1. // 在detail页面中
  2. export default {
  3. onInit() {
  4. console.info('showData1:' + router.getParams()['data1']);
  5. }
  6. }

基于TS扩展的声明式开发范式

  1. // 通过router.pushUrl跳转至目标页携带params参数
  2. import router from '@ohos.router'
  3. @Entry
  4. @Component
  5. struct Index {
  6. async routePage() {
  7. let options = {
  8. url: 'pages/second',
  9. params: {
  10. text: '这是第一页的值',
  11. data: {
  12. array: [12, 45, 78]
  13. }
  14. }
  15. }
  16. try {
  17. await router.pushUrl(options)
  18. } catch (err) {
  19. console.info(` fail callback, code: ${err.code}, msg: ${err.msg}`)
  20. }
  21. }
  22. build() {
  23. Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
  24. Text('这是第一页')
  25. .fontSize(50)
  26. .fontWeight(FontWeight.Bold)
  27. Button() {
  28. Text('next page')
  29. .fontSize(25)
  30. .fontWeight(FontWeight.Bold)
  31. }.type(ButtonType.Capsule)
  32. .margin({ top: 20 })
  33. .backgroundColor('#ccc')
  34. .onClick(() => {
  35. this.routePage()
  36. })
  37. }
  38. .width('100%')
  39. .height('100%')
  40. }
  41. }
  1. // 在second页面中接收传递过来的参数
  2. import router from '@ohos.router'
  3. @Entry
  4. @Component
  5. struct Second {
  6. private content: string = "这是第二页"
  7. @State text: string = router.getParams()['text']
  8. @State data: object = router.getParams()['data']
  9. @State secondData: string = ''
  10. build() {
  11. Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
  12. Text(`${this.content}`)
  13. .fontSize(50)
  14. .fontWeight(FontWeight.Bold)
  15. Text(this.text)
  16. .fontSize(30)
  17. .onClick(() => {
  18. this.secondData = (this.data['array'][1]).toString()
  19. })
  20. .margin({ top: 20 })
  21. Text(`第一页传来的数值:${this.secondData}`)
  22. .fontSize(20)
  23. .margin({ top: 20 })
  24. .backgroundColor('red')
  25. }
  26. .width('100%')
  27. .height('100%')
  28. }
  29. }

router.push(deprecated)

push(options: RouterOptions): void

跳转到应用内的指定页面。

从API version9开始不再维护,建议使用pushUrl9+

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名

类型

必填

说明

options

RouterOptions

跳转页面描述信息。

示例:

  1. router.push({
  2. url: 'pages/routerpage2',
  3. params: {
  4. data1: 'message',
  5. data2: {
  6. data3: [123, 456, 789]
  7. }
  8. }
  9. });

router.replace(deprecated)

replace(options: RouterOptions): void

用应用内的某个页面替换当前页面,并销毁被替换的页面。

从API version9开始不再维护,建议使用replaceUrl9+

系统能力: SystemCapability.ArkUI.ArkUI.Lite

参数:

参数名

类型

必填

说明

options

RouterOptions

替换页面描述信息。

示例:

  1. router.replace({
  2. url: 'pages/detail',
  3. params: {
  4. data1: 'message'
  5. }
  6. });

router.enableAlertBeforeBackPage(deprecated)

enableAlertBeforeBackPage(options: EnableAlertOptions): void

开启页面返回询问对话框。

从API version9开始不再维护,建议使用showAlertBeforeBackPage9+

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名

类型

必填

说明

options

EnableAlertOptions

文本弹窗信息描述。

示例:

  1. router.enableAlertBeforeBackPage({
  2. message: 'Message Info'
  3. });

router.disableAlertBeforeBackPage(deprecated)

disableAlertBeforeBackPage(): void

禁用页面返回询问对话框。

从API version9开始不再维护,建议使用hideAlertBeforeBackPage9+

系统能力: SystemCapability.ArkUI.ArkUI.Full

示例:

  1. router.disableAlertBeforeBackPage();
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号