@ohos.router (页面路由)

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

说明

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

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

导入模块

import router from '@ohos.router'

router.push

push(options: RouterOptions): void

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

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

参数：

参数名	类型	必填	说明
options	RouterOptions	是	跳转页面描述信息。

示例：

router.push({
  url: "pages/routerpage2",
  params: {
    data1: "message",
    data2: {
      data3: [123, 456, 789],
    },
  },
});

router.push⁹⁺

push(options: RouterOptions, mode: RouterMode): void

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

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

参数：

参数名	类型	必填	说明
options	RouterOptions	是	跳转页面描述信息。
mode	RouterMode	是	跳转页面使用的模式。

示例：

router.push(
  {
    url: "pages/routerpage2/routerpage2",
    params: {
      data1: "message",
      data2: {
        data3: [123, 456, 789],
      },
    },
  },
  router.RouterMode.Standard
);

router.replace

replace(options: RouterOptions): void

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

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

参数：

参数名	类型	必填	说明
options	RouterOptions	是	替换页面描述信息。

示例：

router.replace({
  url: "pages/detail",
  params: {
    data1: "message",
  },
});

router.replace⁹⁺

replace(options: RouterOptions, mode: RouterMode): void

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

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

参数：

参数名	类型	必填	说明
options	RouterOptions	是	替换页面描述信息。
mode	RouterMode	是	跳转页面使用的模式。

示例：

router.replace(
  {
    url: "pages/detail/detail",
    params: {
      data1: "message",
    },
  },
  router.RouterMode.Standard
);

router.back

back(options?: RouterOptions ): void

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

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

参数：

参数名	类型	必填	说明
options	RouterOptions	否	返回页面描述信息，其中参数 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。

示例：

var size = router.getLength();
console.log("pages stack size = " + size);

router.getState

getState(): RouterState

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

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

返回值：

类型	说明
RouterState	页面状态信息。

示例：

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	表示当前页面在页面栈中的索引。从栈底到栈顶，index 从 1 开始递增。
name	string	表示当前页面的名称，即对应文件名。
path	string	表示当前页面的路径。

router.enableAlertBeforeBackPage

enableAlertBeforeBackPage(options: EnableAlertOptions): void

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

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

参数：

参数名	类型	必填	说明
options	EnableAlertOptions	是	文本弹窗信息描述。

示例：

router.enableAlertBeforeBackPage({
  message: "Message Info",
});

EnableAlertOptions

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

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

名称	类型	必填	说明
message	string	是	询问对话框内容。

router.disableAlertBeforeBackPage

disableAlertBeforeBackPage(): void

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

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

示例：

router.disableAlertBeforeBackPage();

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	否	跳转时要同时传递到目标页面的数据，跳转到目标页面后，参数可以在页面中直接使用，如 this.data1(data1 为跳转时 params 参数中的 key 值)。如果目标页面中已有该字段，则其值会被传入的字段值覆盖。

说明： 页面路由栈支持的最大 Page 数量为 32。

RouterMode⁹⁺

路由跳转模式。

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

名称	描述
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%')
  }
}

//在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%')
  }
}