0
# History Management
1

2
Browser history abstraction with support for hash, browser, and multi-page modes, providing custom routing behavior and basename management.
3

4
## Capabilities
5

6
### setHistoryMode
7

8
Set the history mode and create the appropriate history instance with optional basename configuration.
9

10
```typescript { .api }
11
/**
12
 * Set the history mode and create appropriate history instance
13
 * @param mode - 'browser', 'hash', or 'multi' (defaults to 'hash')
14
 * @param base - Base path for all routes (defaults to '/')
15
 */
16
function setHistoryMode(mode?: IH5RouterConfig['mode'], base?: string): void;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { setHistoryMode } from "@tarojs/router";
23

24
// Hash mode (default) - URLs like /#/page
25
setHistoryMode("hash", "/");
26

27
// Browser mode - URLs like /page (requires server configuration)
28
setHistoryMode("browser", "/app");
29

30
// Multi-page mode - Traditional page navigation
31
setHistoryMode("multi");
32
```
33

34
### setHistory
35

36
Directly set the global history instance and basename for custom history implementations.
37

38
```typescript { .api }
39
/**
40
 * Set the global history instance and basename
41
 * @param h - History instance to use globally
42
 * @param base - Base path for all routes (defaults to '/')
43
 */
44
function setHistory(h: History, base?: string): void;
45
```
46

47
**Usage Example:**
48

49
```typescript
50
import { setHistory, createBrowserHistory } from "@tarojs/router";
51

52
const customHistory = createBrowserHistory({
53
  basename: "/my-app",
54
  window: window
55
});
56

57
setHistory(customHistory, "/my-app");
58
```
59

60
### createMpaHistory
61

62
Create a custom multi-page application history implementation that handles page navigation via window.location.
63

64
```typescript { .api }
65
/**
66
 * Create a multi-page application history implementation
67
 * @param options - Hash or browser history options (optional)
68
 * @returns Custom MPA history instance
69
 */
70
function createMpaHistory(options?: HashHistoryOptions | BrowserHistoryOptions): MpaHistory;
71
```
72

73
**Usage Example:**
74

75
```typescript
76
import { createMpaHistory } from "@tarojs/router";
77

78
const mpaHistory = createMpaHistory();
79

80
// MPA history handles navigation via window.location
81
// - push() uses window.location.assign()
82
// - replace() uses window.location.replace()
83
// - Adds .html extension for page routes
84
```
85

86
### prependBasename
87

88
Utility function to prepend the configured basename to a URL path.
89

90
```typescript { .api }
91
/**
92
 * Prepend basename to a URL path
93
 * @param url - URL to prepend basename to (defaults to empty string)
94
 * @returns URL with prepended basename
95
 */
96
function prependBasename(url?: string): string;
97
```
98

99
**Usage Example:**
100

101
```typescript
102
import { prependBasename } from "@tarojs/router";
103

104
// Assuming basename is '/app'
105
const fullPath = prependBasename("/profile"); // Returns '/app/profile'
106
const rootPath = prependBasename(); // Returns '/app/'
107
```
108

109
### History Factory Functions
110

111
Re-exported history creation functions from the 'history' library for browser and hash modes.
112

113
```typescript { .api }
114
/**
115
 * Create browser history instance (HTML5 pushState API)
116
 * @param options - Browser history configuration
117
 * @returns Browser history instance
118
 */
119
function createBrowserHistory(options?: BrowserHistoryOptions): History;
120

121
/**
122
 * Create hash history instance (URL hash fragment)
123
 * @param options - Hash history configuration  
124
 * @returns Hash history instance
125
 */
126
function createHashHistory(options?: HashHistoryOptions): History;
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { createBrowserHistory, createHashHistory } from "@tarojs/router";
133

134
// Browser history with custom options
135
const browserHistory = createBrowserHistory({
136
  basename: "/my-app",
137
  window: window
138
});
139

140
// Hash history with custom window object
141
const hashHistory = createHashHistory({
142
  window: window
143
});
144
```
145

146
## MpaHistory Implementation
147

148
The MpaHistory class provides a custom history implementation for multi-page applications.
149

150
```typescript { .api }
151
class MpaHistory implements History {
152
  /** Current browser action type */
153
  readonly action: Action;
154
  
155
  /** Current location object */
156
  readonly location: Location;
157
  
158
  /** Navigate to a new page (uses window.location.assign) */
159
  push(to: Partial<Path>, state?: Record<string, unknown>): void;
160
  
161
  /** Replace current page (uses window.location.replace) */
162
  replace(to: Partial<Path>, state?: Record<string, unknown>): void;
163
  
164
  /** Navigate by delta (-1 = back, 1 = forward) */
165
  go(delta: number): void;
166
  
167
  /** Navigate back one page */
168
  back(): void;
169
  
170
  /** Navigate forward one page */
171
  forward(): void;
172
  
173
  /** Listen to navigation events */
174
  listen(listener: Listener): () => void;
175
  
176
  /** Block navigation (throws error - not implemented) */
177
  block(blocker: Blocker): () => void;
178
  
179
  /** Create href from path object (throws error - not implemented) */
180
  createHref(to: To): string;
181
}
182
```
183

184
## History Options
185

186
```typescript { .api }
187
interface BrowserHistoryOptions {
188
  /** Window object to use (defaults to global window) */
189
  window?: Window;
190
  /** Base URL for all locations */
191
  basename?: string;
192
}
193

194
interface HashHistoryOptions {
195
  /** Window object to use (defaults to global window) */
196
  window?: Window;
197
  /** Hash type ('slash' or 'noslash') */
198
  hashType?: 'slash' | 'noslash';
199
}
200
```
201

202
## State Management
203

204
The history system includes custom state event handling for MPA mode:
205

206
- **pushState Events**: Dispatched when new pages are added to history
207
- **replaceState Events**: Dispatched when pages are replaced in history  
208
- **popstate Events**: Dispatched for back/forward navigation
209
- **State Preservation**: Maintains page state across navigation in SPA mode
210
- **Timestamp Tracking**: Adds timestamps to navigation state for debugging