0
# @tarojs/router
1
2
@tarojs/router is a comprehensive H5 routing system for the Taro cross-platform framework, providing compatibility with mini-program routing specifications. It supports both single-page (SPA) and multi-page (MPA) application modes, includes navigation APIs, history management, and UI components for creating web applications that follow mini-program conventions.
3
4
## Package Information
5
6
- **Package Name**: @tarojs/router
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tarojs/router`
10
- **Node Version**: >= 18
11
12
## Core Imports
13
14
```typescript
15
import { createRouter, createMultiRouter } from "@tarojs/router";
16
```
17
18
For navigation APIs:
19
20
```typescript
21
import { navigateTo, navigateBack, redirectTo, switchTab, reLaunch } from "@tarojs/router";
22
```
23
24
For history management:
25
26
```typescript
27
import { setHistoryMode, setHistory, createMpaHistory, prependBasename } from "@tarojs/router";
28
```
29
30
For standard history creation:
31
32
```typescript
33
import { createBrowserHistory, createHashHistory } from "@tarojs/router";
34
```
35
36
## Basic Usage
37
38
### Single-Page Application Router
39
40
```typescript
41
import { createRouter, setHistoryMode } from "@tarojs/router";
42
43
// Set up history mode (hash, browser, or multi)
44
setHistoryMode("hash", "/");
45
46
// Create SPA router
47
const router = createRouter(history, app, {
48
routes: [
49
{ path: "/home", load: () => import("./pages/home") },
50
{ path: "/profile", load: () => import("./pages/profile") }
51
],
52
router: {
53
mode: "hash",
54
basename: "/",
55
pathname: "/home"
56
},
57
pages: ["/home", "/profile"]
58
}, "react");
59
```
60
61
### Navigation
62
63
```typescript
64
import { navigateTo, navigateBack } from "@tarojs/router";
65
66
// Navigate to a new page
67
await navigateTo({
68
url: "/profile?id=123",
69
success: (res) => console.log("Navigation successful"),
70
fail: (err) => console.error("Navigation failed", err)
71
});
72
73
// Navigate back
74
await navigateBack({
75
delta: 1 // Number of pages to go back
76
});
77
```
78
79
## Architecture
80
81
@tarojs/router is built around several key components:
82
83
- **Router Engines**: SPA and MPA router implementations with page lifecycle management
84
- **Navigation API**: Mini-program compatible navigation functions (navigateTo, redirectTo, etc.)
85
- **History Management**: Browser and hash history with custom MPA history implementation
86
- **Application Mounting**: Functions to mount the app with or without tabbar support
87
- **Utility Functions**: Route alias management, navigation bar control, and mobile detection
88
89
## Capabilities
90
91
### Router Creation
92
93
Core router creation functions for SPA and MPA applications with full lifecycle support and page stack management.
94
95
```typescript { .api }
96
function createRouter(
97
history: History,
98
app: AppInstance,
99
config: SpaRouterConfig,
100
framework?: string
101
): () => void;
102
103
function createMultiRouter(
104
history: History,
105
app: AppInstance,
106
config: MpaRouterConfig,
107
framework?: string
108
): Promise<void>;
109
```
110
111
[Router Creation](./router-creation.md)
112
113
### Navigation APIs
114
115
Mini-program compatible navigation system with promise-based callbacks and page stack management.
116
117
```typescript { .api }
118
function navigateTo(option: Taro.navigateTo.Option): Promise<TaroGeneral.CallbackResult>;
119
function redirectTo(option: Taro.redirectTo.Option): Promise<TaroGeneral.CallbackResult>;
120
function navigateBack(option?: Taro.navigateBack.Option): Promise<TaroGeneral.CallbackResult>;
121
function switchTab(option: Taro.switchTab.Option): Promise<TaroGeneral.CallbackResult>;
122
function reLaunch(option: Taro.reLaunch.Option): Promise<TaroGeneral.CallbackResult>;
123
```
124
125
[Navigation APIs](./navigation-apis.md)
126
127
### History Management
128
129
Browser history abstraction with support for hash, browser, and multi-page modes with custom routing behavior.
130
131
```typescript { .api }
132
function setHistoryMode(mode?: IH5RouterConfig['mode'], base?: string): void;
133
function setHistory(h: History, base?: string): void;
134
function createMpaHistory(options?: HashHistoryOptions | BrowserHistoryOptions): MpaHistory;
135
function prependBasename(url?: string): string;
136
```
137
138
[History Management](./history-management.md)
139
140
### Application Mounting
141
142
Application mounting functions for setting up the H5 app with or without tabbar support.
143
144
```typescript { .api }
145
function handleAppMount(config: SpaRouterConfig | MpaRouterConfig, history: History, appId?: string): void;
146
function handleAppMountWithTabbar(config: SpaRouterConfig | MpaRouterConfig, history: History, appId?: string): void;
147
```
148
149
[Application Mounting](./application-mounting.md)
150
151
### Utility Functions
152
153
Navigation bar control, mobile detection, and route alias management utilities.
154
155
```typescript { .api }
156
function setTitle(title: string): void;
157
function setNavigationBarStyle(option: { backgroundColor: string; frontColor: string }): void;
158
function setNavigationBarLoading(loading: boolean): void;
159
function getCurrentPages(): Taro.Page[];
160
```
161
162
[Utility Functions](./utility-functions.md)
163
164
## Core Types
165
166
```typescript { .api }
167
interface SpaRouterConfig extends AppConfig {
168
routes: Route[];
169
router: Router;
170
PullDownRefresh?: any;
171
}
172
173
interface MpaRouterConfig extends AppConfig {
174
route: Route;
175
pageName: string;
176
router: Router;
177
PullDownRefresh?: any;
178
}
179
180
interface Route extends PageConfig {
181
path?: string;
182
load?: () => Promise<any>;
183
}
184
185
interface Router {
186
mode: IH5RouterConfig['mode'];
187
basename: string;
188
customRoutes?: Record<string, string | string[]>;
189
pathname: string;
190
forcePath?: string;
191
enhanceAnimation?: boolean;
192
}
193
```