Navigation Components
Navigation components are used to implement page navigation and routing functionality in uni-app applications.
navigator
The navigator
component is used for page navigation, similar to the HTML <a>
tag but with more powerful functionality.
Basic Usage
<template>
<view>
<!-- Basic navigation -->
<navigator url="/pages/detail/detail">Go to Detail Page</navigator>
<!-- Navigation with parameters -->
<navigator url="/pages/detail/detail?id=123&name=test">
Go to Detail with Parameters
</navigator>
<!-- Tab navigation -->
<navigator url="/pages/home/home" open-type="switchTab">
Switch to Home Tab
</navigator>
<!-- Redirect navigation -->
<navigator url="/pages/login/login" open-type="redirect">
Redirect to Login
</navigator>
</view>
</template>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Properties
Property | Type | Default | Description |
---|---|---|---|
url | String | Target page path | |
open-type | String | navigate | Navigation type |
delta | Number | 1 | Number of pages to go back (when open-type="navigateBack") |
app-id | String | Target mini-program appId (mini-program only) | |
path | String | Target mini-program page path (mini-program only) | |
extra-data | Object | Extra data passed to target mini-program (mini-program only) | |
version | String | release | Target mini-program version (mini-program only) |
hover-class | String | navigator-hover | Style class when pressed |
hover-stop-propagation | Boolean | false | Whether to stop hover event propagation |
hover-start-time | Number | 50 | Time delay before hover state starts (ms) |
hover-stay-time | Number | 600 | Time to keep hover state after release (ms) |
target | String | self | Navigation target (mini-program only) |
open-type Values
Value | Description | Platform Support |
---|---|---|
navigate | Navigate to new page | All |
redirect | Redirect to new page | All |
switchTab | Switch to tab page | All |
reLaunch | Close all pages and navigate to new page | All |
navigateBack | Go back to previous page | All |
navigateToMiniProgram | Navigate to other mini-program | Mini-program |
exit | Exit mini-program | Mini-program |
Events
Event | Description | Parameters |
---|---|---|
@success | Triggered when navigation succeeds | event |
@fail | Triggered when navigation fails | event |
@complete | Triggered when navigation completes | event |
Advanced Examples
<template>
<view class="container">
<!-- Navigation with custom hover effect -->
<navigator
url="/pages/profile/profile"
hover-class="custom-hover"
hover-start-time="100"
hover-stay-time="300"
>
<view class="nav-item">
<image src="/static/icons/profile.png" class="nav-icon"></image>
<text class="nav-text">Profile</text>
</view>
</navigator>
<!-- Navigate to mini-program -->
<navigator
app-id="wx1234567890"
path="pages/index/index"
open-type="navigateToMiniProgram"
:extra-data="extraData"
version="release"
@success="onNavigateSuccess"
@fail="onNavigateFail"
>
Open Other Mini-Program
</navigator>
<!-- Go back with custom delta -->
<navigator open-type="navigateBack" :delta="2">
Go Back 2 Pages
</navigator>
</view>
</template>
<script>
export default {
data() {
return {
extraData: {
userId: '123',
source: 'myapp'
}
}
},
methods: {
onNavigateSuccess(e) {
console.log('Navigation success:', e);
},
onNavigateFail(e) {
console.log('Navigation failed:', e);
}
}
}
</script>
<style>
.nav-item {
display: flex;
align-items: center;
padding: 20rpx;
border: 1px solid #e0e0e0;
border-radius: 8rpx;
}
.nav-icon {
width: 40rpx;
height: 40rpx;
margin-right: 20rpx;
}
.nav-text {
font-size: 32rpx;
color: #333;
}
.custom-hover {
background-color: #f0f0f0;
opacity: 0.8;
}
</style>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
Programmatic Navigation
In addition to using the navigator
component, you can also use uni-app's navigation APIs for programmatic navigation.
uni.navigateTo()
Navigate to a new page while keeping the current page in the page stack.
// Basic navigation
uni.navigateTo({
url: '/pages/detail/detail'
});
// Navigation with parameters
uni.navigateTo({
url: '/pages/detail/detail?id=123&name=test',
success: (res) => {
console.log('Navigation success');
},
fail: (err) => {
console.log('Navigation failed:', err);
}
});
// Navigation with animation (App only)
uni.navigateTo({
url: '/pages/detail/detail',
animationType: 'slide-in-right',
animationDuration: 300
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
uni.redirectTo()
Close the current page and navigate to a new page.
uni.redirectTo({
url: '/pages/login/login'
});
2
3
uni.reLaunch()
Close all pages and navigate to a new page.
uni.reLaunch({
url: '/pages/home/home'
});
2
3
uni.switchTab()
Switch to a tab page and close all other non-tab pages.
uni.switchTab({
url: '/pages/home/home'
});
2
3
uni.navigateBack()
Go back to the previous page.
// Go back one page
uni.navigateBack();
// Go back multiple pages
uni.navigateBack({
delta: 2
});
2
3
4
5
6
7
Navigation Best Practices
1. Choose the Right Navigation Method
// Use navigateTo for detail pages
uni.navigateTo({
url: '/pages/detail/detail?id=123'
});
// Use redirectTo for login/logout scenarios
uni.redirectTo({
url: '/pages/login/login'
});
// Use switchTab for tab navigation
uni.switchTab({
url: '/pages/home/home'
});
// Use reLaunch for complete app restart
uni.reLaunch({
url: '/pages/welcome/welcome'
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2. Parameter Passing
// Method 1: URL parameters
uni.navigateTo({
url: '/pages/detail/detail?id=123&type=product'
});
// In target page
export default {
onLoad(options) {
console.log('Received parameters:', options);
// options: { id: '123', type: 'product' }
}
}
// Method 2: Using eventChannel (recommended for complex data)
uni.navigateTo({
url: '/pages/detail/detail',
success: (res) => {
res.eventChannel.emit('acceptDataFromOpenerPage', {
data: complexData
});
}
});
// In target page
export default {
onLoad() {
const eventChannel = this.getOpenerEventChannel();
eventChannel.on('acceptDataFromOpenerPage', (data) => {
console.log('Received complex data:', data);
});
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
3. Navigation Guards
// Global navigation guard
// App.vue
export default {
onLaunch() {
// Override uni.navigateTo to add global logic
const originalNavigateTo = uni.navigateTo;
uni.navigateTo = (options) => {
// Check authentication
if (this.needsAuth(options.url) && !this.isLoggedIn()) {
uni.redirectTo({
url: '/pages/login/login'
});
return;
}
// Call original method
return originalNavigateTo(options);
};
},
methods: {
needsAuth(url) {
const authPages = ['/pages/profile/', '/pages/order/'];
return authPages.some(page => url.includes(page));
},
isLoggedIn() {
return !!uni.getStorageSync('token');
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
Platform Differences
Mini-Program Specific Features
<template>
<!-- Navigate to other mini-programs -->
<navigator
app-id="wxd678efh567hg6787"
path="pages/index/index"
open-type="navigateToMiniProgram"
version="release"
:extra-data="{ from: 'myapp' }"
>
Open Other Mini-Program
</navigator>
<!-- Exit mini-program -->
<navigator open-type="exit">
Exit Mini-Program
</navigator>
</template>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
App Specific Features
// App-specific navigation with animations
// #ifdef APP-PLUS
uni.navigateTo({
url: '/pages/detail/detail',
animationType: 'slide-in-right',
animationDuration: 300
});
// #endif
// Native navigation bar customization
// #ifdef APP-PLUS
plus.webview.currentWebview().setStyle({
titleNView: {
backgroundColor: '#007AFF',
titleText: 'Custom Title',
titleColor: '#FFFFFF'
}
});
// #endif
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
H5 Specific Features
// H5 browser history management
// #ifdef H5
// Use browser's back button
window.addEventListener('popstate', (e) => {
console.log('Browser back button pressed');
});
// Modify browser URL without navigation
history.pushState(null, null, '/new-url');
// #endif
2
3
4
5
6
7
8
9
10
Common Issues and Solutions
1. Navigation Not Working
// Problem: Navigation doesn't work
// Solution: Check if the target page exists in pages.json
// pages.json
{
"pages": [
{
"path": "pages/index/index"
},
{
"path": "pages/detail/detail" // Make sure this exists
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
2. Parameters Not Received
// Problem: Parameters not received in target page
// Solution: Use onLoad instead of created/mounted
export default {
// Wrong
created() {
console.log(this.$route.query); // May be undefined
},
// Correct
onLoad(options) {
console.log(options); // Parameters are available here
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
3. Tab Navigation Issues
// Problem: switchTab doesn't work
// Solution: Make sure the target page is configured as a tab page
// pages.json
{
"tabBar": {
"list": [
{
"pagePath": "pages/home/home", // Must match exactly
"text": "Home"
}
]
}
}
// Use switchTab for tab pages
uni.switchTab({
url: '/pages/home/home' // Must start with '/'
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Summary
Navigation components and APIs are essential for creating smooth user experiences in uni-app applications. Key points to remember:
- Use the appropriate navigation method for different scenarios
- Handle parameters correctly using onLoad
- Consider platform-specific features and limitations
- Implement proper error handling and user feedback
- Test navigation flows on all target platforms
For more information about navigation, refer to the uni-app official documentation.