Causes and Solutions
Cause 1: The route is not correctly configured.
The system route table is not configured, or the navDestination attribute is not set for the Navigation component. The target page is not registered in the route table or not defined in the builder method of navDestination.
Solution
Check and configure the route table to ensure that all target pages are correctly defined in the route table (for example, router configuration).
Set the navDestination attribute explicitly in the Navigation component and include the target page in the builder method.
Cause 2: The module type is incorrect.
In the module.json5 file, the type is set to feature (which should be har or shared), causing the redirection failure.
Solution
Change the value of type to har or shared in the module.json5 file. For example:
"module": {
// "name": "your_module",
// "type": "har", // or shared, avoid using feature,
// ...
}, Cause 3: The NavBar is hidden, causing the page stack exception.
If hideNavBar is set to true, the NavBar is hidden. If the page stack is empty, a white screen is displayed.
Solution
Set the hideNavBar attribute of the Navigation component to false to ensure that the NavBar is visible.
Navigation() {
// page content
// ...
}
.hideNavBar(false) // Ensure not hidden Cause 4: The name for redirection is invalid or empty.
The name parameter passed to pushPathByName is empty, incorrect, or does not exist in the routing table.
Solution
Check whether the name value in the redirection code is the same as the name registered in the routing table.
Use a valid name, for example:
// Correct example: The name must match the routing table
this.pageStack.pushPathByName('PageDetail', 'param'); Cause 5: The debugging environment is incompatible.
When the Previewer is used for debugging, redirection to the system routing table is not supported, which may cause a white screen.
Solution
Use the Emulator or a real device to debug complex page redirection.
Cause 6: The navigation stack is incorrectly created on the subpage.
The subpage creates a NavPathStack instance such as new NavPathStack(), which conflicts with the parent Navigation routing stack. As a result, the page cannot be rendered.
Solution
The subpage should use the NavPathStack instance passed by the parent page to avoid re-creation. Sample code:
// Subpage code, avoid creating it yourself
@Component
struct ChildPage {
// Error: Should not use new NavPathStack()
// pageStack: NavPathStack = new NavPathStack();
// Correct: Inject the parent stack through @Consume or parameters
@Consume('pageStack') pageStack: NavPathStack;
build() {
// ...
}
} Limitations and alternative solutions of pushPathByName
Limitations
pushPathByName is a synchronous method. When navigating to a non-existent page, it does not throw an exception and directly displays a blank page.
Recommended alternative solution
Use pushDestinationByName, which is an asynchronous method, to capture and redirect errors.
// Asynchronous jump using pushDestructionByName
this.pageStack.pushDestinationByName('TargetPage', 'param')
.then(() => {
hilog.info(0x000, 'testTag', 'pushDestinationByName success');
})
.catch((error: BusinessError) => {
// Jump failed, redirected to custom page (such as Stay tuned page)
this.pageStack.pushPathByName('ErrorPage', 'param');
hilog.error(0x000, 'testTag', `pushDestinationByName failed, code=${error.code}, message=${error.message}`);
}) Advantage: Errors are handled by callback, avoiding white screen.