openharmony 鸿蒙 arkts-apis-uicontext-router

2026-08-25 浏览 (1)

Class (Router)

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

说明：

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

  • 本Class首批接口从API version 10开始支持。

  • 以下API需先使用UIContext中的getRouter()方法获取到Router对象，再通过该对象调用对应方法。

pushUrl

pushUrl(options: router.RouterOptions): Promise<void>

跳转到应用内的指定页面，使用Promise异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

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

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.
100002Uri error. The URI of the page to redirect is incorrect or does not exist.
100003Page stack error. Too many pages are pushed.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

// 定义传递参数的类
class innerParams {
  array: number[];

  constructor(tuple: number[]) {
    this.array = tuple;
  }
}

class RouterParams {
  data: innerParams;

  constructor(tuple: number[]) {
    this.data = new innerParams(tuple);
  }
}

@Entry
@Component
struct Index {
  async routePage() {
    let options: router.RouterOptions = {
      url: 'pages/second',
      params: new RouterParams([12, 45, 78])
    }
    this.getUIContext()
      .getRouter()
      .pushUrl(options)
      .then(() => {
        console.info('pushUrl success');
      })
      .catch((err: ESObject) => {
        console.error(`pushUrl failed, code is ${(err as BusinessError).code}, message is ${(err as BusinessError).message}`);
      })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text('First Page')
      Button('Next page')
        .type(ButtonType.Capsule)
        .margin({ top: 20 })
        .onClick(() => {
          this.routePage()
        })
    }
    .width('100%')
    .height('100%')
  }
}

// 在second页面中接收传递过来的参数
class innerParams {
  array: number[];

  constructor(tuple: number[]) {
    this.array = tuple;
  }
}

class RouterParams {
  data: innerParams;

  constructor(tuple: number[]) {
    this.data = new innerParams(tuple);
  }
}

@Entry
@Component
struct Second {
  @State data: object = (this.getUIContext().getRouter().getParams() as RouterParams).data;
  @State secondData: string = '';

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text('Second Page')
      Button('Back')
        .fontSize(30)
        .onClick(() => {
          try {
            this.getUIContext().getRouter().showAlertBeforeBackPage({ message: 'Are you sure to return?' })
          } catch (error) {
            // TODO: Implement error handling.
          }
          this.getUIContext().getRouter().back()
        })
        .margin({ top: 20 })
      Button(`The value on the first page：${this.secondData}`)
        .margin({ top: 20 })
        .onClick(()=> {
          this.secondData = (this.data['array'][1]).toString();
        })
    }
    .width('100%')
    .height('100%')
  }
}

pushUrl

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

跳转到应用内的指定页面。使用callback异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.RouterOptions是跳转页面描述信息。
callbackAsyncCallback<void>是router跳转结果回调函数。
当路由跳转成功时，error为undefined。当路由跳转失败时，error为系统返回的错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.
100002Uri error. The URI of the page to redirect is incorrect or does not exist.
100003Page stack error. Too many pages are pushed.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().pushUrl({
      url: 'pages/routerpage2',
      params: {
        data1: 'message',
        data2: {
          data3: [123, 456, 789]
        }
      }
    }, (err: Error) => {
      if (err) {
        let message = (err as BusinessError).message;
        let code = (err as BusinessError).code;
        console.error(`pushUrl failed, code is ${code}, message is ${message}`);
        return;
      }
      console.info('pushUrl success');
    })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

pushUrl

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

跳转到应用内的指定页面，使用Promise异步回调。与pushUrl相比，新增了mode参数，即支持设置跳转页面使用的模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

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

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.
100002Uri error. The URI of the page to redirect is incorrect or does not exist.
100003Page stack error. Too many pages are pushed.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

class RouterTmp {
  Standard: router.RouterMode = router.RouterMode.Standard;
}

let rtm: RouterTmp = new RouterTmp();

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().pushUrl({
        url: 'pages/routerpage2',
        params: {
          data1: 'message',
          data2: {
            data3: [123, 456, 789]
          }
        }
      }, rtm.Standard)
      .then(() => {
        console.info('succeeded');
      })
      .catch((error: BusinessError) => {
        console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`);
      })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

pushUrl

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

跳转到应用内的指定页面。使用callback异步回调。与pushUrl相比，新增了mode参数，即支持设置跳转页面使用的模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.RouterOptions是跳转页面描述信息。
moderouter.RouterMode是跳转页面使用的模式。
callbackAsyncCallback<void>是router跳转结果回调函数。
当路由跳转成功时，error为undefined。当路由跳转失败时，error为系统返回的错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.
100002Uri error. The URI of the page to redirect is incorrect or does not exist.
100003Page stack error. Too many pages are pushed.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

class RouterTmp {
  Standard: router.RouterMode = router.RouterMode.Standard;
}

let rtm: RouterTmp = new RouterTmp();

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().pushUrl({
      url: 'pages/routerpage2',
      params: {
        data1: 'message',
        data2: {
          data3: [123, 456, 789]
        }
      }
    }, rtm.Standard, (err) => {
      if (err) {
        let message = (err as BusinessError).message;
        let code = (err as BusinessError).code;
        console.error(`pushUrl failed, code is ${code}, message is ${message}`);
        return;
      }
      console.info('pushUrl success');
    })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

replaceUrl

replaceUrl(options: router.RouterOptions): Promise<void>

用应用内的某个页面替换当前页面，并销毁被替换的页面，使用Promise异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

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

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001The UI execution context is not found. This error code is thrown only in the standard system.
200002Uri error. The URI of the page to be used for replacement is incorrect or does not exist.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().replaceUrl({
        url: 'pages/detail',
        params: {
          data1: 'message'
        }
      })
      .then(() => {
        console.info('succeeded');
      })
      .catch((error: BusinessError) => {
        console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`);
      })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

replaceUrl

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

用应用内的某个页面替换当前页面，并销毁被替换的页面。使用callback异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.RouterOptions是替换页面描述信息。
callbackAsyncCallback<void>是router跳转结果回调函数。
当路由跳转成功时，error为undefined。当路由跳转失败时，error为系统返回的错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001The UI execution context is not found. This error code is thrown only in the standard system.
200002Uri error. The URI of the page to be used for replacement is incorrect or does not exist.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().replaceUrl({
      url: 'pages/detail',
      params: {
        data1: 'message'
      }
    }, (err: Error) => {
      if (err) {
        let message = (err as BusinessError).message;
        let code = (err as BusinessError).code;
        console.error(`replaceUrl failed, code is ${code}, message is ${message}`);
        return;
      }
      console.info('replaceUrl success');
    })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

replaceUrl

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

用应用内的某个页面替换当前页面，并销毁被替换的页面，使用Promise异步回调。与replaceUrl相比，新增了mode参数，即支持设置跳转页面使用的模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

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

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Failed to get the delegate. This error code is thrown only in the standard system.
200002Uri error. The URI of the page to be used for replacement is incorrect or does not exist.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

class RouterTmp {
  Standard: router.RouterMode = router.RouterMode.Standard;
}

let rtm: RouterTmp = new RouterTmp();

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().replaceUrl({
        url: 'pages/detail',
        params: {
          data1: 'message'
        }
      }, rtm.Standard)
      .then(() => {
        console.info('succeeded');
      })
      .catch((error: BusinessError) => {
        console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`);
      })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

replaceUrl

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

用应用内的某个页面替换当前页面，并销毁被替换的页面。使用callback异步回调。与replaceUrl相比，新增了mode参数，即支持设置跳转页面使用的模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.RouterOptions是替换页面描述信息。
moderouter.RouterMode是跳转页面使用的模式。
callbackAsyncCallback<void>是router跳转结果回调函数。
当路由跳转成功时，error为undefined。当路由跳转失败时，error为系统返回的错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001The UI execution context is not found. This error code is thrown only in the standard system.
200002Uri error. The URI of the page to be used for replacement is incorrect or does not exist.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

class RouterTmp {
  Standard: router.RouterMode = router.RouterMode.Standard;
}

let rtm: RouterTmp = new RouterTmp();

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().replaceUrl({
      url: 'pages/detail',
      params: {
        data1: 'message'
      }
    }, rtm.Standard, (err: Error) => {
      if (err) {
        let message = (err as BusinessError).message;
        let code = (err as BusinessError).code;
        console.error(`replaceUrl failed, code is ${code}, message is ${message}`);
        return;
      }
      console.info('replaceUrl success');
    });
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

pushNamedRoute

pushNamedRoute(options: router.NamedRouterOptions): Promise<void>

跳转到指定的命名路由页面，使用Promise异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.NamedRouterOptions是跳转页面描述信息。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.
100003Page stack error. Too many pages are pushed.
100004Named route error. The named route does not exist.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().pushNamedRoute({
        name: 'myPage',
        params: {
          data1: 'message',
          data2: {
            data3: [123, 456, 789]
          }
        }
      })
      .then(() => {
        console.info('succeeded');
      })
      .catch((error: BusinessError) => {
        console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`);
      })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

pushNamedRoute

pushNamedRoute(options: router.NamedRouterOptions, callback: AsyncCallback<void>): void

跳转到指定的命名路由页面。使用callback异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.NamedRouterOptions是跳转页面描述信息。
callbackAsyncCallback<void>是router跳转结果回调函数。
当路由跳转成功时，error为undefined。当路由跳转失败时，error为系统返回的错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.
100003Page stack error. Too many pages are pushed.
100004Named route error. The named route does not exist.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().pushNamedRoute({
      name: 'myPage',
      params: {
        data1: 'message',
        data2: {
          data3: [123, 456, 789]
        }
      }
    }, (err: Error) => {
      if (err) {
        let message = (err as BusinessError).message;
        let code = (err as BusinessError).code;
        console.error(`pushNamedRoute failed, code is ${code}, message is ${message}`);
        return;
      }
      console.info('pushNamedRoute success');
    })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

pushNamedRoute

pushNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode): Promise<void>

跳转到指定的命名路由页面，使用Promise异步回调。与pushNamedRoute相比，新增了mode参数，即支持设置跳转页面使用的模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.NamedRouterOptions是跳转页面描述信息。
moderouter.RouterMode是跳转页面使用的模式。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.
100003Page stack error. Too many pages are pushed.
100004Named route error. The named route does not exist.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

class RouterTmp{
  Standard:router.RouterMode = router.RouterMode.Standard;
}
let rtm:RouterTmp = new RouterTmp();

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().pushNamedRoute({
        name: 'myPage',
        params: {
          data1: 'message',
          data2: {
            data3: [123, 456, 789]
          }
        }
      }, rtm.Standard)
      .then(() => {
        console.info('succeeded');
      })
      .catch((error: BusinessError) => {
        console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`);
      })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

pushNamedRoute

pushNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void

跳转到指定的命名路由页面。使用callback异步回调。与pushNamedRoute相比，新增了mode参数，即支持设置跳转页面使用的模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.NamedRouterOptions是跳转页面描述信息。
moderouter.RouterMode是跳转页面使用的模式。
callbackAsyncCallback<void>是router跳转结果回调函数。
当路由跳转成功时，error为undefined。当路由跳转失败时，error为系统返回的错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.
100003Page stack error. Too many pages are pushed.
100004Named route error. The named route does not exist.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

class RouterTmp {
  Standard: router.RouterMode = router.RouterMode.Standard;
}

let rtm: RouterTmp = new RouterTmp();

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().pushNamedRoute({
      name: 'myPage',
      params: {
        data1: 'message',
        data2: {
          data3: [123, 456, 789]
        }
      }
    }, rtm.Standard, (err: Error) => {
      if (err) {
        let message = (err as BusinessError).message;
        let code = (err as BusinessError).code;
        console.error(`pushNamedRoute failed, code is ${code}, message is ${message}`);
        return;
      }
      console.info('pushNamedRoute success');
    })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

replaceNamedRoute

replaceNamedRoute(options: router.NamedRouterOptions): Promise<void>

用指定的命名路由页面替换当前页面，并销毁被替换的页面，使用Promise异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.NamedRouterOptions是替换页面描述信息。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401if the number of parameters is less than 1 or the type of the url parameter is not string.
100001The UI execution context is not found. This error code is thrown only in the standard system.
100004Named route error. The named route does not exist.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().replaceNamedRoute({
        name: 'myPage',
        params: {
          data1: 'message'
        }
      })
      .then(() => {
        console.info('succeeded');
      })
      .catch((error: BusinessError) => {
        console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`);
      })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

replaceNamedRoute

replaceNamedRoute(options: router.NamedRouterOptions, callback: AsyncCallback<void>): void

用指定的命名路由页面替换当前页面，并销毁被替换的页面。使用callback异步回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.NamedRouterOptions是替换页面描述信息。
callbackAsyncCallback<void>是router跳转结果回调函数。
当路由跳转成功时，error为undefined。当路由跳转失败时，error为系统返回的错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001The UI execution context is not found. This error code is thrown only in the standard system.
100004Named route error. The named route does not exist.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().replaceNamedRoute({
      name: 'myPage',
      params: {
        data1: 'message'
      }
    }, (err: Error) => {
      if (err) {
        let message = (err as BusinessError).message;
        let code = (err as BusinessError).code;
        console.error(`replaceNamedRoute failed, code is ${code}, message is ${message}`);
        return;
      }
      console.info('replaceNamedRoute success');
    })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

replaceNamedRoute

replaceNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode): Promise<void>

用指定的命名路由页面替换当前页面，并销毁被替换的页面，使用Promise异步回调。与replaceNamedRoute相比，新增了mode参数，即支持设置跳转页面使用的模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.NamedRouterOptions是替换页面描述信息。
moderouter.RouterMode是跳转页面使用的模式。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Failed to get the delegate. This error code is thrown only in the standard system.
100004Named route error. The named route does not exist.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

class RouterTmp {
  Standard: router.RouterMode = router.RouterMode.Standard;
}

let rtm: RouterTmp = new RouterTmp();

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().replaceNamedRoute({
        name: 'myPage',
        params: {
          data1: 'message'
        }
      }, rtm.Standard)
      .then(() => {
        console.info('succeeded');
      })
      .catch((error: BusinessError) => {
        console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`);
      })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

replaceNamedRoute

replaceNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void

用指定的命名路由页面替换当前页面，并销毁被替换的页面。使用callback异步回调。与replaceNamedRoute相比，新增了mode参数，即支持设置跳转页面使用的模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.NamedRouterOptions是替换页面描述信息。
moderouter.RouterMode是跳转页面使用的模式。
callbackAsyncCallback<void>是router跳转结果回调函数。
当路由跳转成功时，error为undefined。当路由跳转失败时，error为系统返回的错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码、页面路由错误码和接口调用异常错误码。

错误码ID错误信息
401if the number of parameters is less than 1 or the type of the url parameter is not string.
100001The UI execution context is not found. This error code is thrown only in the standard system.
100004Named route error. The named route does not exist.

示例：

import { router } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

class RouterTmp {
  Standard: router.RouterMode = router.RouterMode.Standard;
}

let rtm: RouterTmp = new RouterTmp();

@Entry
@Component
struct Index {
  async routePage() {
    this.getUIContext().getRouter().replaceNamedRoute({
      name: 'myPage',
      params: {
        data1: 'message'
      }
    }, rtm.Standard, (err: Error) => {
      if (err) {
        let message = (err as BusinessError).message;
        let code = (err as BusinessError).code;
        console.error(`replaceNamedRoute failed, code is ${code}, message is ${message}`);
        return;
      }
      console.info('replaceNamedRoute success');
    })
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('next page')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        this.routePage();
      })
    }
    .width('100%')
    .height('100%')
  }
}

back

back(options?: router.RouterOptions ): void

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
optionsrouter.RouterOptions否返回页面描述信息，其中参数url指路由跳转时返回到指定url的页面，如果页面栈中没有对应url的页面，则不响应该操作；如果栈中存在对应url的页面，则返回至index最大的同名页面。
如果url未设置，则返回上一页，页面不会重新构建，页面栈里面的page不会回收，出栈后会被回收。

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();
let router: Router = uiContext.getRouter();
router.back({url:'pages/detail'});

back12+

back(index: number, params?: Object): void

返回指定的页面。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
indexnumber是跳转目标页面的索引值。
取值范围：[0, +∞)
paramsObject否页面返回时携带的参数。

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();

let router: Router = uiContext.getRouter();
router.back(1);

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();
let router: Router = uiContext.getRouter();
router.back(1, {info:'来自Home页'}); // 携带参数返回

clear

clear(): void

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();

let router: Router = uiContext.getRouter();
router.clear();

getLength(deprecated)

getLength(): string

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

说明：

从API version 10开始支持，从 API version 23开始废弃，建议使用getStackSize替代。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

返回值：

类型说明
string页面数量，页面栈支持最大数值是32。

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();

let router: Router = uiContext.getRouter();
let size = router.getLength();        
console.info('pages stack size = ' + size);

getStackSize23+

getStackSize(): number

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

原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。

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

模型约束： 此接口仅可在Stage模型下使用。

返回值：

类型说明
number页面数量，页面栈支持最大数值是32。

示例：

@Entry
@Component
struct Index {

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button() {
        Text('stack size')
          .fontSize(25)
          .fontWeight(FontWeight.Bold)
      }.type(ButtonType.Capsule)
      .margin({ top: 20 })
      .backgroundColor('#ccc')
      .onClick(() => {
        console.info(`get stack size: ${this.getUIContext().getRouter().getStackSize()}`)
      })
    }
    .width('100%')
    .height('100%')
  }
}

getState

getState(): router.RouterState

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

返回值：

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

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();

let router: Router = uiContext.getRouter();
let page = router.getState();
if (page != undefined) {
  console.info('current index = ' + page.index);
  console.info('current name = ' + page.name);
  console.info('current path = ' + page.path);
}

getStateByIndex12+

getStateByIndex(index: number): router.RouterState|undefined

通过索引值获取对应页面的状态信息。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
indexnumber是表示要获取的页面索引。
取值范围：[1, +∞)

返回值：

类型说明
router.RouterState |undefined返回页面状态信息。索引不存在时返回undefined。

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();

let router: Router = uiContext.getRouter();
let options: router.RouterState|undefined = router.getStateByIndex(1);
if (options != undefined) {
  console.info('index = ' + options.index);
  console.info('name = ' + options.name);
  console.info('path = ' + options.path);
  console.info('params = ' + options.params);
}

getStateByUrl12+

getStateByUrl(url: string): Array<router.RouterState>

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

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名类型必填说明
urlstring是表示要获取对应页面信息的url。

返回值：

类型说明
Array<router.RouterState>页面状态信息。

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();
let router: Router = uiContext.getRouter();
let options:Array<router.RouterState> = router.getStateByUrl('pages/index');
for (let i: number = 0; i < options.length; i++) {
  console.info('index = ' + options[i].index);
  console.info('name = ' + options[i].name);
  console.info('path = ' + options[i].path);
  console.info('params = ' + options[i].params);
}

showAlertBeforeBackPage

showAlertBeforeBackPage(options: router.EnableAlertOptions): void

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

参数：

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

错误码：

以下错误码的详细介绍请参见通用错误码和接口调用异常错误码。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.
100001Internal error.

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let uiContext: UIContext = this.getUIContext();
let router: Router = uiContext.getRouter();
try {
  router.showAlertBeforeBackPage({            
    message: 'Message Info'        
  });
} catch(error) {
  let message = (error as BusinessError).message;
  let code = (error as BusinessError).code;
  console.error(`showAlertBeforeBackPage failed, code is ${code}, message is ${message}`);
}

hideAlertBeforeBackPage

hideAlertBeforeBackPage(): void

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();

let router: Router = uiContext.getRouter();
router.hideAlertBeforeBackPage();

getParams

getParams(): Object

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

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

返回值：

类型说明
Object发起跳转的页面往当前页传入的参数。

示例：

完整示例请参考PushUrl中的示例。

import { Router , UIContext } from '@kit.ArkUI';
let uiContext: UIContext = this.getUIContext();
let router: Router = uiContext.getRouter();
router.getParams();

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 arkts-apis-uicontext-contextmenucontroller

openharmony 鸿蒙 errorcode-canvas

openharmony 鸿蒙 capi-oh-nativexcomponent-native-xcomponent-oh-nativexcomponent

openharmony 鸿蒙 errorcode-bindSheet

openharmony 鸿蒙 js-apis-arkui-uiExtension-sys

openharmony 鸿蒙 capi-arkui-accessibility-arkui-accessibilityeventinfo

openharmony 鸿蒙 capi-arkui-rendernodeutils

openharmony 鸿蒙 capi-native-node-h-nodeattributetype-layoutcomponent

openharmony 鸿蒙 js-apis-arkui-node

openharmony 鸿蒙 capi-native-node-h

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/tcERxYuk