跳至主要內容

页面路由

Mr.Liu大约 8 分钟前端HarmonyOS

 

页面路由

页面路由

导入模块

import router from '@ohos.router'

页面路由错误码

100001 内部错误

错误信息

Internal error.

错误描述

当出现了开发者解决不了的内部异常错误，系统会产生此错误码，并描述具体是哪种内部错误。

可能原因

未成功获取渲染引擎，解析参数失败等。

处理步骤

NA

100002 路由页面跳转时输入的uri错误

错误信息

Uri error. The uri of router is not exist.

错误描述

当跳转页面输入的uri错误或者不存在，系统会产生此错误码。

可能原因

输入的路由uri错误或者不存在。

处理步骤

请检查输入的路由uri是否正确。

100003 路由压入的page过多

错误信息

Page stack error. The pages are pushed too much.

错误描述

当跳转页面压入页面数超过32，系统会产生此错误码。

可能原因

压入pages过多。

处理步骤

请清除多余或无效的页面。

200002 路由页面替换时输入的uri错误

错误信息

Uri error. The uri of router is not exist.

错误描述

当替换页面输入的uri错误或不存在，系统会产生此错误码。

可能原因

输入的路由uri错误或不存在。

处理步骤

请检查输入的路由uri是否正确。

router.pushUrl

跳转到应用内的指定页面

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

默认使用

参数名类型必填说明
optionsRouterOptions是跳转页面描述信息。
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}`);
  })

默认异常响应回调

参数名类型必填说明
optionsRouterOptions是跳转页面描述信息。
callbackAsyncCallback<void>是异常响应回调。
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');
});

跳转页面模式

参数名类型必填说明
optionsRouterOptions是跳转页面描述信息。
modeRouterMode是跳转页面使用的模式。
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}`);
  })

跳转页面模式异常响应回调

参数名类型必填说明
optionsRouterOptions是跳转页面描述信息。
modeRouterMode是跳转页面使用的模式。
callbackAsyncCallback<void>是异常响应回调。
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.replaceUrl

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

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

默认使用

参数名类型必填说明
optionsRouterOptions是跳转页面描述信息。
router.replaceUrl({
  url: 'pages/detail',
  params: {
    data1: 'message'
  }
})
  .then(() => {
    // success
  })
  .catch(err => {
    console.error(`replaceUrl failed, code is ${err.code}, message is ${err.message}`);
  })

默认异常响应回调

参数名类型必填说明
optionsRouterOptions是跳转页面描述信息。
callbackAsyncCallback<void>是异常响应回调。
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');
});

跳转页面模式

参数名类型必填说明
optionsRouterOptions是跳转页面描述信息。
modeRouterMode是跳转页面使用的模式。
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}`);
  })

跳转页面模式异常响应回调

参数名类型必填说明
optionsRouterOptions是跳转页面描述信息。
modeRouterMode是跳转页面使用的模式。
callbackAsyncCallback<void>是异常响应回调。
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

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

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

参数名类型必填说明
optionsRouterOptions否返回页面描述信息，其中参数url指路由跳转时会返回到指定url的界面，如果页面栈上没有url页面，则不响应该情况。如果url未设置，则返回上一页，页面不会重新构建，页面栈里面的page不会回收，出栈后会被回收。
  • 返回上一个页面。
router.back();
  • 返回到指定页面
router.back({url:'pages/detail'});
  • 返回到指定页面传参
router.back({
  url: 'pages/Index',
  params: {
    src: 'Second页面传来的数据',
  }
})

router.clear

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

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

router.clear();

router.getLength

获取当前在页面栈内的页面数量,页面栈支持最大数值是32

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

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

router.getState

获取当前页面的状态信息

系统能力： 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。

参数名类型必填说明
indexnumber是表示当前页面在页面栈中的索引。从栈底到栈顶，index从1开始递增。
namestring否表示当前页面的名称，即对应文件名。
pathstring是表示当前页面的路径。

router.showAlertBeforeBackPage

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

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

参数名类型必填说明
optionsEnableAlertOptions是文本弹窗信息描述。
router.showAlertBeforeBackPage({
message: 'Message Info'
})
.then(() => {
  // success
})
.catch(err => {
  console.error(`showAlertBeforeBackPage failed, code is ${error.code}, message is ${error.message}`);
})

页面返回可以根据业务需要增加一个询问对话框。

即在调用router.back()方法之前，可以先调用router.enableBackPageAlert()方法开启页面返回询问对话框功能。

注意

  • router.enableBackPageAlert()方法开启页面返回询问对话框功能，只针对当前页面生效。例如在调用router.pushUrl()或者router.replaceUrl()方法，跳转后的页面均为新建页面，因此在页面返回之前均需要先调用router.enableBackPageAlert()方法之后，页面返回询问对话框功能才会生效。
  • 如需关闭页面返回询问对话框功能，可以通过调用router.disableAlertBeforeBackPage()方法关闭该功能即可
router.enableBackPageAlert({
  message: 'Message Info'
});

router.back();

EnableAlertOptions

页面返回询问对话框选项

参数名类型必填说明
messagestring是询问对话框内容。

router.hideAlertBeforeBackPage

禁用页面返回询问对话框

router.hideAlertBeforeBackPage();

router.getParams

getParams(): Object

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

类型说明
object发起跳转的页面往当前页传入的参数。
router.getParams();

在Second页面中，调用router.back()方法返回上一个页面或者返回指定页面时，根据需要继续增加自定义参数，例如在返回时增加一个自定义参数src。

router.back({
  url: 'pages/Index',
  params: {
    src: 'Second页面传来的数据',
  }
})

Second页面返回到Index页面。在Index页面通过调用router.getParams()方法，获取Second页面传递过来的自定义参数

说明

  • 调用router.back()方法，不会新建页面，返回的是原来的页面，在原来页面中@State声明的变量不会重复声明，以及也不会触发页面的aboutToAppear()生命周期回调，因此无法直接在变量声明以及页面的aboutToAppear()生命周期回调中接收和解析router.back()传递过来的自定义参数。

可以放在业务需要的位置进行参数解析。示例代码在Index页面中的onPageShow()生命周期回调中进行参数的解析。

import router from '@ohos.router';
@Entry
@Component
struct Index {
  @State src: string = '';
  onPageShow() {
    this.src = (router.getParams() as Record<string, string>)['src'];
  }
  // 页面刷新展示
  ...
}

RouterOptions

路由跳转选项。

参数名类型必填说明
urlstring是表示目标页面的url，可以用以下两种格式：页面绝对路径，由配置文件中pages列表提供，例如：pages/index/index,pages/detail/detail 特殊值,如果url的值是"/"，则跳转到首页。
paramsobject否表示路由跳转时要同时传递到目标页面的数据，切换到其他页面时，当前接收的数据失效。跳转到目标页面后，使用router.getParams()获取传递的参数，此外，在类web范式中，参数也可以在页面中直接使用，如this.keyValue(keyValue为跳转时params参数中的key值)，如果目标页面中已有该字段，则其值会被传入的字段值覆盖。说明：params参数不能传递方法和系统接口返回的对象（例如，媒体接口定义和返回的PixelMap对象）。建议开发者提取系统接口返回的对象中需要被传递的基础类型属性，自行构造object类型对象进行传递。

RouterMode

路由跳转模式

名称说明
Standard标准模式。目标页面会被添加到页面路由栈顶，无论栈中是否存在相同url的页面。说明：不使用路由跳转模式时，按标准模式跳转。
Single单实例模式。如果目标页面的url在页面栈中已经存在同url页面，离栈顶最近的页面会被移动到栈顶，移动后的页面为新建页。如目标页面的url在页面栈中不存在同url页面，按标准模式跳转。

实例

基于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%')
  }
}
上次编辑于:
贡献者: test
真正坚持到最后的人，往往靠的不是短暂的激情，而是恰到好处的喜欢和投入。
Copyright © 2025 Mr.Liu