0
# Utility Functions
1

2
Navigation bar control, mobile detection, route alias management, and other utility functions for enhanced routing functionality.
3

4
## Capabilities
5

6
### Navigation Bar Control
7

8
Functions to control navigation bar appearance and behavior through the event system.
9

10
```typescript { .api }
11
/**
12
 * Set navigation bar title via event system
13
 * @param title - Title text to display in navigation bar
14
 */
15
function setTitle(title: string): void;
16

17
/**
18
 * Set navigation bar style colors
19
 * @param option - Background and front color configuration
20
 */
21
function setNavigationBarStyle(option: { 
22
  backgroundColor: string; 
23
  frontColor: string; 
24
}): void;
25

26
/**
27
 * Show or hide navigation bar loading indicator
28
 * @param loading - Whether to show loading indicator
29
 */
30
function setNavigationBarLoading(loading: boolean): void;
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import { 
37
  setTitle, 
38
  setNavigationBarStyle, 
39
  setNavigationBarLoading 
40
} from "@tarojs/router";
41

42
// Update navigation bar title
43
setTitle("Profile Settings");
44

45
// Change navigation bar colors
46
setNavigationBarStyle({
47
  backgroundColor: "#007AFF",
48
  frontColor: "#ffffff"
49
});
50

51
// Show loading indicator
52
setNavigationBarLoading(true);
53

54
// Hide loading indicator after operation completes
55
setTimeout(() => {
56
  setNavigationBarLoading(false);
57
}, 2000);
58
```
59

60
### Mobile Platform Detection
61

62
Utility functions to detect specific mobile browser environments.
63

64
```typescript { .api }
65
/**
66
 * Detect if running in WeChat browser
67
 * @returns True if in WeChat/MicroMessenger browser
68
 */
69
function isWeixin(): boolean;
70

71
/**
72
 * Detect if running in DingTalk browser
73
 * @returns True if in DingTalk browser
74
 */
75
function isDingTalk(): boolean;
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import { isWeixin, isDingTalk } from "@tarojs/router";
82

83
if (isWeixin()) {
84
  console.log("Running in WeChat browser");
85
  // Enable WeChat-specific features
86
}
87

88
if (isDingTalk()) {
89
  console.log("Running in DingTalk browser");
90
  // Enable DingTalk-specific features
91
}
92
```
93

94
### Multi-Page Title Management
95

96
Specialized title management for multi-page applications with DingTalk integration.
97

98
```typescript { .api }
99
/**
100
 * Set page title for multi-page applications (with DingTalk support)
101
 * @param title - Page title to set
102
 */
103
function setMpaTitle(title: string): void;
104
```
105

106
**Usage Example:**
107

108
```typescript
109
import { setMpaTitle } from "@tarojs/router";
110

111
// Set title for multi-page app
112
setMpaTitle("Dashboard - My App");
113

114
// DingTalk integration is automatic when:
115
// - Running in DingTalk browser
116
// - SUPPORT_DINGTALK_NAVIGATE is not 'disabled'
117
// - Will load DingTalk JSAPI and use native title setting
118
```
119

120
### Route Alias Management
121

122
Global route alias management system for custom routing patterns.
123

124
```typescript { .api }
125
/**
126
 * Global route alias instance for managing custom route mappings
127
 */
128
const routesAlias: RoutesAlias;
129

130
interface RoutesAlias {
131
  /** Set custom route mappings */
132
  set(customRoutes: Record<string, string | string[]>): void;
133
  /** Get route configuration for URL */
134
  getConfig(url?: string): string[] | undefined;
135
  /** Get original route for alias */
136
  getOrigin(url?: string): string;
137
  /** Get alias for route */
138
  getAlias(url?: string): string;
139
  /** Get all routes for URL */
140
  getAll(url?: string): string[];
141
}
142
```
143

144
**Usage Examples:**
145

146
```typescript
147
import { routesAlias } from "@tarojs/router";
148

149
// Set up custom route aliases
150
routesAlias.set({
151
  "/home": "/pages/index",
152
  "/user": ["/pages/profile", "/pages/user-detail"],
153
  "/shop": "/pages/store"
154
});
155

156
// Get original route from alias
157
const originalRoute = routesAlias.getOrigin("/home"); // Returns "/pages/index"
158

159
// Get alias from original route  
160
const aliasRoute = routesAlias.getAlias("/pages/index"); // Returns "/home"
161

162
// Get all possible routes for a URL
163
const allRoutes = routesAlias.getAll("/user"); // Returns ["/pages/profile", "/pages/user-detail"]
164

165
// Get route configuration
166
const config = routesAlias.getConfig("/home"); // Returns ["/home", "/pages/index"]
167
```
168

169
## Event System Integration
170

171
Navigation bar control functions work through Taro's event system:
172

173
```typescript { .api }
174
// Event names triggered by utility functions
175
"__taroH5SetNavigationBarTitle"    // Triggered by setTitle()
176
"__taroH5setNavigationBarColor"    // Triggered by setNavigationBarStyle()  
177
"__taroH5setNavigationBarLoading"  // Triggered by setNavigationBarLoading()
178
```
179

180
These events are handled internally by the navigation bar component to update the UI in real-time.
181

182
## DingTalk Integration
183

184
The `setMpaTitle` function includes automatic DingTalk integration:
185

186
1. **Detection**: Automatically detects DingTalk browser environment
187
2. **API Loading**: Dynamically loads DingTalk JSAPI platform and navigation APIs
188
3. **Native Title**: Uses DingTalk's native title setting API for better integration
189
4. **Fallback**: Falls back to standard `document.title` for other browsers
190
5. **Performance**: Only loads DingTalk APIs once per session
191

192
## Route Processing Features
193

194
The route alias system supports:
195

196
- **One-to-One Mapping**: Single route aliases (`"/home": "/pages/index"`)
197
- **One-to-Many Mapping**: Multiple target routes for one alias (`"/user": ["/profile", "/detail"]`)
198
- **Bidirectional Lookup**: Get original from alias or alias from original
199
- **Leading Slash Normalization**: Ensures all routes start with `/`
200
- **Configuration Retrieval**: Get full mapping configuration for any URL
201

202
## Type Definitions
203

204
```typescript { .api }
205
interface Taro.Page {
206
  /** Page route without query parameters */
207
  route: string;
208
  /** Full page path with query parameters */
209
  path?: string;
210
  /** Page initialization options/parameters */
211
  options?: any;
212
  /** Page lifecycle methods */
213
  onShow?: () => void;
214
  onHide?: () => void;
215
  onUnload?: () => void;
216
}
217
```