0
# Taro H5
1
2
Taro H5 is the Web/H5 implementation layer of the Taro cross-platform development framework, providing browser-compatible APIs that mirror WeChat Mini Program APIs. It serves as the runtime layer that enables Taro applications to run in web browsers by implementing Mini Program APIs using web standards like DOM, fetch, and localStorage.
3
4
## Package Information
5
6
- **Package Name**: @tarojs/taro-h5
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tarojs/taro-h5`
10
11
## Core Imports
12
13
```typescript
14
import Taro from "@tarojs/taro-h5";
15
```
16
17
For specific API imports:
18
19
```typescript
20
import { request, getStorageSync, showToast } from "@tarojs/taro-h5";
21
```
22
23
For CommonJS:
24
25
```javascript
26
const Taro = require("@tarojs/taro-h5");
27
const { request, getStorageSync, showToast } = require("@tarojs/taro-h5");
28
```
29
30
## Basic Usage
31
32
```typescript
33
import Taro from "@tarojs/taro-h5";
34
35
// Storage operations
36
Taro.setStorageSync('user', { name: 'Alice', age: 25 });
37
const user = Taro.getStorageSync('user');
38
39
// Network requests
40
const response = await Taro.request({
41
url: 'https://api.example.com/data',
42
method: 'GET',
43
header: { 'Content-Type': 'application/json' }
44
});
45
46
// UI interactions
47
await Taro.showToast({
48
title: 'Success!',
49
icon: 'success',
50
duration: 2000
51
});
52
53
// Location services
54
const location = await Taro.getLocation({
55
type: 'wgs84'
56
});
57
58
// System information
59
const systemInfo = Taro.getSystemInfoSync();
60
console.log(`Platform: ${systemInfo.platform}, Width: ${systemInfo.windowWidth}`);
61
```
62
63
## Architecture
64
65
Taro H5 is organized around several key architectural components:
66
67
- **Core Taro Object**: Central API hub providing utilities like pixel transformation, environment detection, and app information
68
- **Web API Adapters**: Browser-compatible implementations of Mini Program APIs using standard web technologies
69
- **Storage Layer**: localStorage-based persistence matching Mini Program storage APIs
70
- **Network Layer**: fetch-based HTTP client with interceptor support
71
- **UI Components**: Browser-based implementations of Mini Program UI interactions
72
- **Device Abstractions**: Web-compatible device capability APIs where possible
73
- **Routing Integration**: @tarojs/router integration for navigation APIs
74
- **Cross-Platform Stubs**: Graceful handling of platform-specific APIs not available in browsers
75
76
## Capabilities
77
78
### Core Framework APIs
79
80
Essential framework utilities including the main Taro object, app lifecycle management, and system utilities.
81
82
```typescript { .api }
83
// Main Taro object with core utilities
84
interface TaroCore {
85
// Pixel transformation
86
pxTransform(size: number): string;
87
initPxTransform(config: PxTransformConfig): void;
88
89
// App information
90
getAppInfo(): AppInfo;
91
canIUseWebp(): boolean;
92
93
// Environment and lifecycle
94
getEnv(): string;
95
getCurrentInstance(): ComponentInstance;
96
getApp<T>(): T;
97
getCurrentPages(): PageInstance[];
98
}
99
100
interface PxTransformConfig {
101
designWidth?: number;
102
deviceRatio?: Record<number, number>;
103
baseFontSize?: number;
104
unitPrecision?: number;
105
targetUnit?: string;
106
}
107
108
interface AppInfo {
109
platform: string;
110
taroVersion: string;
111
designWidth: number;
112
}
113
```
114
115
[Core Framework](./core-framework.md)
116
117
### Storage APIs
118
119
Complete localStorage-based storage system compatible with Mini Program storage APIs, supporting both synchronous and asynchronous operations.
120
121
```typescript { .api }
122
// Synchronous storage operations
123
function setStorageSync(key: string, data: any): void;
124
function getStorageSync(key: string): any;
125
function removeStorageSync(key: string): void;
126
function clearStorageSync(): void;
127
function getStorageInfoSync(): StorageInfo;
128
129
// Asynchronous storage operations
130
function setStorage(options: SetStorageOption): Promise<void>;
131
function getStorage<T>(options: GetStorageOption): Promise<T>;
132
function removeStorage(options: RemoveStorageOption): Promise<void>;
133
function clearStorage(options?: CallbackOptions): Promise<void>;
134
function getStorageInfo(options?: CallbackOptions): Promise<StorageInfo>;
135
136
interface StorageInfo {
137
keys: string[];
138
currentSize: number;
139
limitSize: number;
140
}
141
```
142
143
[Storage](./storage.md)
144
145
### Network APIs
146
147
Comprehensive networking capabilities including HTTP requests with interceptor support, designed for web environments.
148
149
```typescript { .api }
150
function request(options: RequestOption): Promise<RequestResult>;
151
function addInterceptor(interceptor: Interceptor): void;
152
function cleanInterceptors(): void;
153
154
interface RequestOption {
155
url: string;
156
data?: any;
157
header?: Record<string, string>;
158
method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
159
dataType?: string;
160
responseType?: 'text' | 'json' | 'arraybuffer';
161
timeout?: number;
162
enableHttp2?: boolean;
163
enableQuic?: boolean;
164
enableCache?: boolean;
165
}
166
167
interface RequestResult {
168
data: any;
169
statusCode: number;
170
header: Record<string, string>;
171
cookies?: string[];
172
}
173
```
174
175
[Network](./network.md)
176
177
### System Information APIs
178
179
Browser-based system and device information APIs providing comprehensive environment details.
180
181
```typescript { .api }
182
function getSystemInfoSync(): SystemInfo;
183
function getSystemInfoAsync(options?: CallbackOptions): Promise<SystemInfo>;
184
function getSystemInfo(options?: CallbackOptions): Promise<SystemInfo>;
185
function getWindowInfo(): WindowInfo;
186
function getDeviceInfo(): DeviceInfo;
187
function getAppBaseInfo(): AppBaseInfo;
188
189
interface SystemInfo {
190
brand: string;
191
model: string;
192
system: string;
193
language: string;
194
version: string;
195
platform: string;
196
fontSizeSetting: number;
197
SDKVersion: string;
198
pixelRatio: number;
199
windowWidth: number;
200
windowHeight: number;
201
screenWidth: number;
202
screenHeight: number;
203
safeArea: SafeAreaResult;
204
}
205
```
206
207
[System Information](./system-info.md)
208
209
### UI Interaction APIs
210
211
Browser-based user interface interaction APIs including toast messages, modals, loading indicators, and action sheets.
212
213
```typescript { .api }
214
function showToast(options: ToastOption): Promise<void>;
215
function hideToast(options?: CallbackOptions): Promise<void>;
216
function showLoading(options: LoadingOption): Promise<void>;
217
function hideLoading(options?: CallbackOptions): Promise<void>;
218
function showModal(options: ModalOption): Promise<ModalResult>;
219
function showActionSheet(options: ActionSheetOption): Promise<ActionSheetResult>;
220
221
interface ToastOption {
222
title: string;
223
icon?: 'success' | 'error' | 'loading' | 'none';
224
image?: string;
225
duration?: number;
226
mask?: boolean;
227
}
228
229
interface ModalOption {
230
title?: string;
231
content?: string;
232
showCancel?: boolean;
233
cancelText?: string;
234
cancelColor?: string;
235
confirmText?: string;
236
confirmColor?: string;
237
}
238
```
239
240
[UI Interactions](./ui-interactions.md)
241
242
### Location Services
243
244
Geolocation API integration providing location access and monitoring capabilities for web environments.
245
246
```typescript { .api }
247
function getLocation(options: LocationOption): Promise<LocationResult>;
248
function chooseLocation(options: ChooseLocationOption): Promise<LocationResult>;
249
function openLocation(options: OpenLocationOption): Promise<void>;
250
function onLocationChange(callback: LocationChangeCallback): void;
251
function offLocationChange(callback: LocationChangeCallback): void;
252
function startLocationUpdate(options?: LocationUpdateOption): Promise<void>;
253
function stopLocationUpdate(): Promise<void>;
254
255
interface LocationOption {
256
type?: 'wgs84' | 'gcj02';
257
altitude?: boolean;
258
isHighAccuracy?: boolean;
259
highAccuracyExpireTime?: number;
260
}
261
262
interface LocationResult {
263
latitude: number;
264
longitude: number;
265
speed: number;
266
accuracy: number;
267
altitude: number;
268
verticalAccuracy: number;
269
horizontalAccuracy: number;
270
}
271
```
272
273
[Location Services](./location.md)
274
275
### Route Navigation APIs
276
277
Page navigation and routing capabilities integrated with @tarojs/router for single-page application navigation.
278
279
```typescript { .api }
280
function navigateTo(options: NavigateOption): Promise<void>;
281
function redirectTo(options: RedirectOption): Promise<void>;
282
function navigateBack(options?: NavigateBackOption): Promise<void>;
283
function switchTab(options: SwitchTabOption): Promise<void>;
284
function reLaunch(options: ReLaunchOption): Promise<void>;
285
286
interface NavigateOption {
287
url: string;
288
events?: Record<string, Function>;
289
}
290
291
interface NavigateBackOption {
292
delta?: number;
293
}
294
```
295
296
[Route Navigation](./navigation.md)
297
298
### DOM Query APIs
299
300
Web-compatible DOM querying and observation APIs for component interaction and layout management.
301
302
```typescript { .api }
303
function createSelectorQuery(): SelectorQuery;
304
function createIntersectionObserver(
305
component?: any,
306
options?: IntersectionObserverInit
307
): IntersectionObserver;
308
function createMediaQueryObserver(): MediaQueryObserver;
309
310
interface SelectorQuery {
311
select(selector: string): NodesRef;
312
selectAll(selector: string): NodesRef;
313
selectViewport(): NodesRef;
314
exec(callback?: (res: any[]) => void): void;
315
}
316
```
317
318
[DOM Query](./dom-query.md)
319
320
### Device APIs
321
322
Limited device capability APIs focusing on web-compatible features like clipboard access.
323
324
```typescript { .api }
325
function setClipboardData(options: ClipboardDataOption): Promise<void>;
326
function getClipboardData(options?: CallbackOptions): Promise<ClipboardDataResult>;
327
328
interface ClipboardDataOption {
329
data: string;
330
}
331
332
interface ClipboardDataResult {
333
data: string;
334
}
335
```
336
337
[Device APIs](./device.md)
338
339
### Media APIs
340
341
Comprehensive media handling capabilities including image selection, preview, and photo album integration.
342
343
```typescript { .api }
344
function chooseImage(options: ChooseImageOption): Promise<ChooseImageResult>;
345
function previewImage(options: PreviewImageOption): Promise<void>;
346
function getImageInfo(options: GetImageInfoOption): Promise<ImageInfoResult>;
347
function saveImageToPhotosAlbum(options: SaveImageOption): Promise<void>;
348
349
interface ChooseImageOption {
350
count?: number;
351
sizeType?: ('original' | 'compressed')[];
352
sourceType?: ('album' | 'camera' | 'user')[];
353
}
354
355
interface ImageInfoResult {
356
width: number;
357
height: number;
358
path: string;
359
}
360
```
361
362
[Media APIs](./media.md)
363
364
### Canvas APIs
365
366
HTML5 Canvas integration providing 2D graphics capabilities and image manipulation with Mini Program compatibility.
367
368
```typescript { .api }
369
function createCanvasContext(canvasId: string, componentInstance?: any): CanvasContext;
370
function canvasToTempFilePath(options: CanvasToTempFilePathOption): Promise<CanvasToTempFilePathResult>;
371
function canvasGetImageData(options: CanvasGetImageDataOption): Promise<CanvasGetImageDataResult>;
372
function canvasPutImageData(options: CanvasPutImageDataOption): Promise<void>;
373
374
interface CanvasContext {
375
fillRect(x: number, y: number, width: number, height: number): void;
376
strokeRect(x: number, y: number, width: number, height: number): void;
377
beginPath(): void;
378
arc(x: number, y: number, radius: number, startAngle: number, endAngle: number): void;
379
setFillStyle(color: string): void;
380
fillText(text: string, x: number, y: number): void;
381
drawImage(imageResource: string, x: number, y: number): void;
382
draw(reserve?: boolean, callback?: () => void): void;
383
}
384
```
385
386
[Canvas APIs](./canvas.md)
387
388
## Implementation Status
389
390
### ✅ Fully Implemented (Web-Compatible)
391
- **Core Framework APIs**: Complete Taro object with utilities
392
- **Storage APIs**: Full localStorage integration
393
- **Network APIs**: Complete fetch-based implementation with download/upload/WebSocket support
394
- **System Information**: Comprehensive browser environment detection
395
- **UI Interactions**: Toast, modal, loading, action sheet
396
- **Location Services**: Geolocation API integration
397
- **Route Navigation**: @tarojs/router integration
398
- **DOM Query**: Web-compatible selector and observer APIs
399
- **Basic Device APIs**: Clipboard access
400
- **Media APIs**: Image selection, preview, information retrieval, and album saving
401
- **Canvas APIs**: Basic 2D graphics and image operations
402
403
### ⚠️ Partially Implemented
404
- **Advanced Device APIs**: Most hardware features not available in browsers
405
- **Advanced Media APIs**: Video/audio processing and platform-specific media features
406
407
### ❌ Not Implemented (Platform Limitations)
408
- **Mini Program Specific**: WeChat, Alipay, Baidu platform APIs
409
- **Native Features**: File system, advanced hardware access, payments
410
- **Platform Services**: Cloud functions, analytics, advertising
411
- **Advanced Media**: Camera, microphone, Bluetooth, NFC
412
413
The H5 implementation prioritizes web standards compatibility while providing graceful stubs for platform-specific functionality that cannot be implemented in browser environments.
414
415
## Types
416
417
```typescript { .api }
418
interface CallbackOptions {
419
success?: (res: any) => void;
420
fail?: (err: any) => void;
421
complete?: (res: any) => void;
422
}
423
424
interface ComponentInstance {
425
page?: any;
426
router?: {
427
params: Record<string, string>;
428
path: string;
429
};
430
scope?: any;
431
[key: string]: any;
432
}
433
434
interface PageInstance {
435
route: string;
436
options: Record<string, string>;
437
[key: string]: any;
438
}
439
440
interface SafeAreaResult {
441
left: number;
442
right: number;
443
top: number;
444
bottom: number;
445
width: number;
446
height: number;
447
}
448
449
// Environment types
450
declare const ENV_TYPE: {
451
WEAPP: 'WEAPP';
452
WEB: 'WEB';
453
RN: 'RN';
454
SWAN: 'SWAN';
455
ALIPAY: 'ALIPAY';
456
TT: 'TT';
457
QQ: 'QQ';
458
JD: 'JD';
459
};
460
461
type TaroGeneral = {
462
TDeviceRatio: Record<number, number>;
463
};
464
```