@ohos.router (Page Routing)
The Router module provides APIs to access pages through URLs. You can use the APIs to navigate to a specified page in an application, replace the current page with another one in an application, and return to the previous page or a specified page.
NOTE
The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Page routing APIs can be invoked only after page rendering is complete. Do not call these APIs in onInit and onReady when the page is still in the rendering phase.
Modules to Import
import router from '@ohos.router'
router.pushUrl9+
pushUrl(options: RouterOptions): Promise<void>
Navigates to a specified page in the application.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Page routing parameters. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if UI execution context not found. |
100002 | if the uri is not exist. |
100003 | if the pages are pushed too much. |
Example
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
Navigates to a specified page in the application.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Page routing parameters. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if UI execution context not found. |
100002 | if the uri is not exist. |
100003 | if the pages are pushed too much. |
Example
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>
Navigates to a specified page in the application.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Page routing parameters. |
mode | RouterMode | Yes | Routing mode. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if UI execution context not found. |
100002 | if the uri is not exist. |
100003 | if the pages are pushed too much. |
Example
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
Navigates to a specified page in the application.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Page routing parameters. |
mode | RouterMode | Yes | Routing mode. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if UI execution context not found. |
100002 | if the uri is not exist. |
100003 | if the pages are pushed too much. |
Example
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>
Replaces the current page with another one in the application and destroys the current page.
System capability: SystemCapability.ArkUI.ArkUI.Lite
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Description of the new page. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if UI execution context not found, only throw in standard system. |
200002 | if the uri is not exist. |
Example
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
Replaces the current page with another one in the application and destroys the current page.
System capability: SystemCapability.ArkUI.ArkUI.Lite
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Description of the new page. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if UI execution context not found, only throw in standard system. |
200002 | if the uri is not exist. |
Example
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>
Replaces the current page with another one in the application and destroys the current page.
System capability: SystemCapability.ArkUI.ArkUI.Lite
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Description of the new page. |
mode | RouterMode | Yes | Routing mode. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if can not get the delegate, only throw in standard system. |
200002 | if the uri is not exist. |
Example
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
Replaces the current page with another one in the application and destroys the current page.
System capability: SystemCapability.ArkUI.ArkUI.Lite
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Description of the new page. |
mode | RouterMode | Yes | Routing mode. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if UI execution context not found, only throw in standard system. |
200002 | if the uri is not exist. |
Example
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
Returns to the previous page or a specified page.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | No | Description of the page. The url parameter indicates the URL of the page to return to. If the specified page does not exist in the page stack, the application does not respond. If no URL is set, the application returns to the previous page, and the page is not rebuilt. The page in the page stack is not reclaimed. It will be reclaimed after being popped up. |
Example
router.back({url:'pages/detail'});
router.clear
clear(): void
Clears all historical pages in the stack and retains only the current page at the top of the stack.
System capability: SystemCapability.ArkUI.ArkUI.Full
Example
router.clear();
router.getLength
getLength(): string
Obtains the number of pages in the current stack.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
Type | Description |
---|---|
string | Number of pages in the stack. The maximum value is 32. |
Example
let size = router.getLength();
console.log('pages stack size = ' + size);
router.getState
getState(): RouterState
Obtains state information about the current page.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
Type | Description |
---|---|
RouterState | Page routing state. |
Example
let page = router.getState();
console.log('current index = ' + page.index);
console.log('current name = ' + page.name);
console.log('current path = ' + page.path);
RouterState
Describes the page routing state.
System capability: SystemCapability.ArkUI.ArkUI.Full
Name | Type | Mandatory | Description |
---|---|---|---|
index | number | Yes | Index of the current page in the stack. The index starts from 1 from the bottom to the top of the stack. |
name | string | No | Name of the current page, that is, the file name. |
path | string | Yes | Path of the current page. |
router.showAlertBeforeBackPage9+
showAlertBeforeBackPage(options: EnableAlertOptions): void
Enables the display of a confirm dialog box before returning to the previous page.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | EnableAlertOptions | Yes | Description of the dialog box. |
Error codes
For details about the error codes, see Router Error Codes.
ID | Error Message |
---|---|
100001 | if UI execution context not found. |
Example
try {
router.showAlertBeforeBackPage({
message: 'Message Info'
});
} catch(error) {
console.error(`showAlertBeforeBackPage failed, code is ${error.code}, message is ${error.message}`);
}
EnableAlertOptions
Describes the confirm dialog box.
System capability: SystemCapability.ArkUI.ArkUI.Full
Name | Type | Mandatory | Description |
---|---|---|---|
message | string | Yes | Content displayed in the confirm dialog box. |
router.hideAlertBeforeBackPage9+
hideAlertBeforeBackPage(): void
Disables the display of a confirm dialog box before returning to the previous page.
System capability: SystemCapability.ArkUI.ArkUI.Full
Example
router.hideAlertBeforeBackPage();
router.getParams
getParams(): Object
Obtains the parameters passed from the page that initiates redirection to the current page.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
Type | Description |
---|---|
object | Parameters passed from the page that initiates redirection to the current page. |
Example
router.getParams();
RouterOptions
Describes the page routing options.
System capability: SystemCapability.ArkUI.ArkUI.Lite
Name | Type | Mandatory | Description |
---|---|---|---|
url | string | Yes | URL of the target page, in either of the following formats: - Absolute path of the page. The value is available in the pages list in the config.json file, for example: - pages/index/index - pages/detail/detail - Particular path. If the URL is a slash (/), the home page is displayed. |
params | object | No | Data that needs to be passed to the target page during redirection. The target page can use router.getParams() to obtain the passed parameters, for example, this.keyValue (keyValue is the value of a key in params). In the web-like paradigm, these parameters can be directly used on the target page. If the field specified by key already exists on the target page, the passed value of the key will be displayed. |
NOTE
The page routing stack supports a maximum of 32 pages.
RouterMode9+
Enumerates the routing modes.
System capability: SystemCapability.ArkUI.ArkUI.Full
Name | Description |
---|---|
Standard | Multi-instance mode. It is the default routing mode. The target page is added to the top of the page stack, regardless of whether a page with the same URL exists in the stack. NOTE If the routing mode is not used, the page is redirected to in multi-instance mode. |
Single | Singleton mode. If the URL of the target page already exists in the page stack, the page closest to the top of the stack is moved to the top and becomes a new page. If the URL of the target page does not exist in the page stack, the page is redirected to in multi-instance mode. |
Examples
JavaScript-based Web-like Development Paradigm
// Current page
export default {
pushPage() {
router.push({
url: 'pages/detail/detail',
params: {
data1: 'message'
}
});
}
}
// detail page
export default {
onInit() {
console.info('showData1:' + router.getParams()['data1']);
}
}
TypeScript-based Declarative Development Paradigm
// Navigate to the target page through router.pushUrl with the params parameter carried.
import router from '@ohos.router'
@Entry
@Component
struct Index {
async routePage() {
let options = {
url: 'pages/second',
params: {
text: 'This is the value on the first page.',
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('This is the first page.')
.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%')
}
}
// Receive the transferred parameters on the second page.
import router from '@ohos.router'
@Entry
@Component
struct Second {
private content: string = "This is the second page."
@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 is the data passed from the first page: ${this.secondData}`)
.fontSize(20)
.margin({ top: 20 })
.backgroundColor('red')
}
.width('100%')
.height('100%')
}
}
router.push(deprecated)
push(options: RouterOptions): void
Navigates to a specified page in the application.
This API is deprecated since API version 9. You are advised to use pushUrl9+ instead.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Page routing parameters. |
Example
router.push({
url: 'pages/routerpage2',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
});
router.replace(deprecated)
replace(options: RouterOptions): void
Replaces the current page with another one in the application and destroys the current page.
This API is deprecated since API version 9. You are advised to use replaceUrl9+ instead.
System capability: SystemCapability.ArkUI.ArkUI.Lite
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | RouterOptions | Yes | Description of the new page. |
Example
router.replace({
url: 'pages/detail',
params: {
data1: 'message'
}
});
router.enableAlertBeforeBackPage(deprecated)
enableAlertBeforeBackPage(options: EnableAlertOptions): void
Enables the display of a confirm dialog box before returning to the previous page.
This API is deprecated since API version 9. You are advised to use showAlertBeforeBackPage9+ instead.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | EnableAlertOptions | Yes | Description of the dialog box. |
Example
router.enableAlertBeforeBackPage({
message: 'Message Info'
});
router.disableAlertBeforeBackPage(deprecated)
disableAlertBeforeBackPage(): void
Disables the display of a confirm dialog box before returning to the previous page.
This API is deprecated since API version 9. You are advised to use hideAlertBeforeBackPage9+ instead.
System capability: SystemCapability.ArkUI.ArkUI.Full
Example
router.disableAlertBeforeBackPage();