0
# System Information APIs
1

2
Browser-based system and device information APIs providing comprehensive environment details including device characteristics, window dimensions, and platform information.
3

4
## Capabilities
5

6
### System Information
7

8
Comprehensive system and device information retrieval with both synchronous and asynchronous access patterns.
9

10
```typescript { .api }
11
/**
12
 * Get complete system information synchronously
13
 * @returns Comprehensive system information object
14
 */
15
function getSystemInfoSync(): SystemInfo;
16

17
/**
18
 * Get complete system information asynchronously
19
 * @param options - Optional callback configuration
20
 * @returns Promise resolving to system information
21
 */
22
function getSystemInfoAsync(options?: CallbackOptions): Promise<SystemInfo>;
23

24
/**
25
 * Get complete system information (legacy async method)
26
 * @param options - Optional callback configuration  
27
 * @returns Promise resolving to system information
28
 */
29
function getSystemInfo(options?: CallbackOptions): Promise<SystemInfo>;
30

31
interface SystemInfo {
32
  /** Device brand identifier */
33
  brand: string;
34
  /** Device model name */
35
  model: string;
36
  /** Operating system with version */
37
  system: string;
38
  /** System language setting */
39
  language: string;
40
  /** Taro framework version */
41
  version: string;
42
  /** Platform identifier (always 'web' for H5) */
43
  platform: string;
44
  /** Font size setting multiplier */
45
  fontSizeSetting: number;
46
  /** Taro SDK version */
47
  SDKVersion: string;
48
  /** Device pixel ratio */
49
  pixelRatio: number;
50
  /** Window width in pixels */
51
  windowWidth: number;
52
  /** Window height in pixels */
53
  windowHeight: number;
54
  /** Screen width in pixels */
55
  screenWidth: number;
56
  /** Screen height in pixels */
57
  screenHeight: number;
58
  /** Safe area coordinates */
59
  safeArea: SafeAreaResult;
60
  /** Status bar height in pixels */
61
  statusBarHeight: number;
62
  /** Screen top safe area inset */
63
  safeAreaInsets?: SafeAreaInsets;
64
  /** Device orientation */
65
  deviceOrientation?: 'portrait' | 'landscape';
66
  /** Additional platform-specific properties */
67
  [key: string]: any;
68
}
69

70
interface SafeAreaResult {
71
  /** Left safe area boundary */
72
  left: number;
73
  /** Right safe area boundary */
74
  right: number;
75
  /** Top safe area boundary */
76
  top: number;
77
  /** Bottom safe area boundary */
78
  bottom: number;
79
  /** Safe area width */
80
  width: number;
81
  /** Safe area height */
82
  height: number;
83
}
84

85
interface SafeAreaInsets {
86
  /** Top inset in pixels */
87
  top: number;
88
  /** Right inset in pixels */
89
  right: number;
90
  /** Bottom inset in pixels */
91
  bottom: number;
92
  /** Left inset in pixels */
93
  left: number;
94
}
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import { getSystemInfoSync, getSystemInfo } from "@tarojs/taro-h5";
101

102
// Synchronous system info
103
const systemInfo = getSystemInfoSync();
104
console.log(`Platform: ${systemInfo.platform}`);
105
console.log(`Screen: ${systemInfo.screenWidth}x${systemInfo.screenHeight}`);
106
console.log(`Window: ${systemInfo.windowWidth}x${systemInfo.windowHeight}`);
107
console.log(`Pixel Ratio: ${systemInfo.pixelRatio}`);
108
console.log(`Language: ${systemInfo.language}`);
109
console.log(`System: ${systemInfo.system}`);
110

111
// Responsive design based on screen size
112
if (systemInfo.windowWidth < 768) {
113
  console.log('Mobile layout');
114
} else if (systemInfo.windowWidth < 1024) {
115
  console.log('Tablet layout');
116
} else {
117
  console.log('Desktop layout');
118
}
119

120
// Asynchronous system info
121
const asyncSystemInfo = await getSystemInfo();
122
console.log('Async system info:', asyncSystemInfo);
123

124
// With callbacks
125
getSystemInfo({
126
  success: (info) => {
127
    console.log('System info loaded:', info.platform);
128
  },
129
  fail: (error) => {
130
    console.error('Failed to get system info:', error);
131
  }
132
});
133
```
134

135
### Window Information
136

137
Specific window and viewport information for layout calculations.
138

139
```typescript { .api }
140
/**
141
 * Get window-specific information
142
 * @returns Window dimensions and properties
143
 */
144
function getWindowInfo(): WindowInfo;
145

146
interface WindowInfo {
147
  /** Device pixel ratio */
148
  pixelRatio: number;
149
  /** Screen width in pixels */
150
  screenWidth: number;
151
  /** Screen height in pixels */
152
  screenHeight: number;
153
  /** Window width in pixels */
154
  windowWidth: number;
155
  /** Window height in pixels */
156
  windowHeight: number;
157
  /** Status bar height in pixels */
158
  statusBarHeight: number;
159
  /** Safe area coordinates */
160
  safeArea: SafeAreaResult;
161
  /** Screen top position */
162
  screenTop: number;
163
}
164
```
165

166
### Device Information
167

168
Hardware and device-specific information.
169

170
```typescript { .api }
171
/**
172
 * Get device-specific information
173
 * @returns Device characteristics and capabilities
174
 */
175
function getDeviceInfo(): DeviceInfo;
176

177
interface DeviceInfo {
178
  /** Device brand (detected from user agent) */
179
  brand: string;
180
  /** Device model (detected from user agent) */
181
  model: string;
182
  /** Operating system name and version */
183
  system: string;
184
  /** Device platform identifier */
185
  platform: string;
186
  /** CPU architecture (when available) */
187
  CPUType?: string;
188
  /** Memory information (when available) */
189
  memorySize?: number;
190
  /** Device identifier (browser-generated) */
191
  deviceId?: string;
192
  /** Device orientation capability */
193
  deviceOrientation: string;
194
  /** Device type classification */
195
  deviceType: 'phone' | 'tablet' | 'desktop' | 'unknown';
196
  /** Benchmark performance score (estimated) */
197
  benchmarkLevel?: number;
198
}
199
```
200

201
### Application Information
202

203
Application-specific metadata and configuration details.
204

205
```typescript { .api }
206
/**
207
 * Get application base information
208
 * @returns Application metadata and version details
209
 */
210
function getAppBaseInfo(): AppBaseInfo;
211

212
interface AppBaseInfo {
213
  /** Taro SDK version */
214
  SDKVersion: string;
215
  /** Application version (from package.json) */
216
  version: string;
217
  /** Enable debug mode flag */
218
  enableDebug: boolean;
219
  /** Host application name */
220
  host: string;
221
  /** Application language setting */
222
  language: string;
223
  /** Theme setting ('light' or 'dark') */
224
  theme: 'light' | 'dark' | 'auto';
225
  /** Application identifier */
226
  appId?: string;
227
  /** Launch scene identifier */
228
  scene?: number;
229
}
230
```
231

232
### Authorization Settings
233

234
Application permission and authorization information.
235

236
```typescript { .api }
237
/**  
238
 * Get application authorization settings
239
 * @returns Current permission states for various capabilities
240
 */
241
function getAppAuthorizeSetting(): AppAuthorizeSetting;
242

243
interface AppAuthorizeSetting {
244
  /** Location access permission */
245
  'scope.userLocation': boolean;
246
  /** Camera access permission */
247
  'scope.camera': boolean;
248
  /** Microphone access permission */
249
  'scope.record': boolean;
250
  /** Photo album access permission */
251
  'scope.writePhotosAlbum': boolean;
252
  /** Address book access permission */
253
  'scope.addressBook': boolean;
254
  /** Invoice access permission */
255
  'scope.invoiceTitle': boolean;
256
  /** Notification permission */
257
  'scope.notification': boolean;
258
  /** Clipboard access permission */
259
  'scope.clipboard': boolean;
260
  /** Additional permissions */
261
  [key: string]: boolean;
262
}
263
```
264

265
**Usage Examples:**
266

267
```typescript
268
import { 
269
  getWindowInfo, 
270
  getDeviceInfo, 
271
  getAppBaseInfo, 
272
  getAppAuthorizeSetting 
273
} from "@tarojs/taro-h5";
274

275
// Window information for responsive design
276
const windowInfo = getWindowInfo();
277
const isLandscape = windowInfo.windowWidth > windowInfo.windowHeight;
278
const isMobile = windowInfo.windowWidth < 768;
279

280
console.log(`Orientation: ${isLandscape ? 'landscape' : 'portrait'}`);
281
console.log(`Device type: ${isMobile ? 'mobile' : 'desktop'}`);
282

283
// Safe area handling for notched devices
284
const safeAreaPadding = {
285
  top: windowInfo.safeArea.top,
286
  bottom: windowInfo.screenHeight - windowInfo.safeArea.bottom,
287
  left: windowInfo.safeArea.left,
288
  right: windowInfo.screenWidth - windowInfo.safeArea.right
289
};
290

291
// Device information for feature detection
292
const deviceInfo = getDeviceInfo();
293
console.log(`Device: ${deviceInfo.brand} ${deviceInfo.model}`);
294
console.log(`System: ${deviceInfo.system}`);
295
console.log(`Type: ${deviceInfo.deviceType}`);
296

297
// Adaptive features based on device capabilities
298
if (deviceInfo.deviceType === 'phone' && deviceInfo.memorySize && deviceInfo.memorySize < 4) {
299
  console.log('Low-memory device, enabling performance optimizations');
300
}
301

302
// Application information
303
const appInfo = getAppBaseInfo();
304
console.log(`App Version: ${appInfo.version}`);
305
console.log(`SDK Version: ${appInfo.SDKVersion}`);
306
console.log(`Theme: ${appInfo.theme}`);
307
console.log(`Language: ${appInfo.language}`);
308

309
// Permission checking
310
const authSettings = getAppAuthorizeSetting();
311
if (authSettings['scope.userLocation']) {
312
  console.log('Location permission granted');
313
} else {
314
  console.log('Location permission not granted');
315
}
316

317
if (authSettings['scope.camera']) {
318
  console.log('Camera access available');
319
}
320
```
321

322
### Advanced Usage Patterns
323

324
Complex scenarios and best practices for system information usage.
325

326
```typescript
327
// Responsive breakpoint system
328
class ResponsiveBreakpoints {
329
  private windowInfo: WindowInfo;
330
  
331
  constructor() {
332
    this.windowInfo = getWindowInfo();
333
  }
334
  
335
  get isMobile(): boolean {
336
    return this.windowInfo.windowWidth < 768;
337
  }
338
  
339
  get isTablet(): boolean {
340
    return this.windowInfo.windowWidth >= 768 && this.windowInfo.windowWidth < 1024;
341
  }
342
  
343
  get isDesktop(): boolean {
344
    return this.windowInfo.windowWidth >= 1024;
345
  }
346
  
347
  get orientation(): 'portrait' | 'landscape' {
348
    return this.windowInfo.windowWidth > this.windowInfo.windowHeight 
349
      ? 'landscape' : 'portrait';
350
  }
351
  
352
  // Update on window resize
353
  update(): void {
354
    this.windowInfo = getWindowInfo();
355
  }
356
}
357

358
// Device capability detection
359
class DeviceCapabilities {
360
  private deviceInfo: DeviceInfo;
361
  private systemInfo: SystemInfo;
362
  
363
  constructor() {
364
    this.deviceInfo = getDeviceInfo();
365
    this.systemInfo = getSystemInfoSync();
366
  }
367
  
368
  get isHighDPI(): boolean {
369
    return this.systemInfo.pixelRatio >= 2;
370
  }
371
  
372
  get isRetina(): boolean {
373
    return this.systemInfo.pixelRatio >= 3;
374
  }
375
  
376
  get isLowEndDevice(): boolean {
377
    return this.deviceInfo.benchmarkLevel !== undefined && 
378
           this.deviceInfo.benchmarkLevel < 30;
379
  }
380
  
381
  get supportsTouchEvents(): boolean {
382
    return 'ontouchstart' in window;
383
  }
384
  
385
  get supportsWebGL(): boolean {
386
    try {
387
      const canvas = document.createElement('canvas');
388
      return !!(canvas.getContext('webgl') || canvas.getContext('experimental-webgl'));
389
    } catch {
390
      return false;
391
    }
392
  }
393
  
394
  getOptimalImageQuality(): 'low' | 'medium' | 'high' {
395
    if (this.isLowEndDevice) return 'low';
396
    if (this.isHighDPI) return 'high';
397
    return 'medium';
398
  }
399
}
400

401
// Safe area layout helper
402
class SafeAreaLayout {
403
  private windowInfo: WindowInfo;
404
  
405
  constructor() {
406
    this.windowInfo = getWindowInfo();
407
  }
408
  
409
  getSafeAreaCSS(): Record<string, string> {
410
    const { safeArea, screenWidth, screenHeight } = this.windowInfo;
411
    
412
    return {
413
      paddingTop: `${safeArea.top}px`,
414
      paddingBottom: `${screenHeight - safeArea.bottom}px`,
415
      paddingLeft: `${safeArea.left}px`,
416
      paddingRight: `${screenWidth - safeArea.right}px`
417
    };
418
  }
419
  
420
  getSafeAreaInsets(): SafeAreaInsets {
421
    const { safeArea, screenWidth, screenHeight } = this.windowInfo;
422
    
423
    return {
424
      top: safeArea.top,
425
      bottom: screenHeight - safeArea.bottom,
426
      left: safeArea.left,
427
      right: screenWidth - safeArea.right
428
    };
429
  }
430
  
431
  hasNotch(): boolean {
432
    const insets = this.getSafeAreaInsets();
433
    return insets.top > 20 || insets.bottom > 0 || insets.left > 0 || insets.right > 0;
434
  }
435
}
436

437
// Usage examples
438
const breakpoints = new ResponsiveBreakpoints();
439
const capabilities = new DeviceCapabilities();
440
const safeArea = new SafeAreaLayout();
441

442
// Apply responsive styles
443
if (breakpoints.isMobile) {
444
  document.body.className += ' mobile-layout';
445
}
446

447
// Optimize based on device capabilities
448
const imageQuality = capabilities.getOptimalImageQuality();
449
console.log(`Using ${imageQuality} quality images`);
450

451
// Handle safe areas
452
if (safeArea.hasNotch()) {
453
  const safeAreaCSS = safeArea.getSafeAreaCSS();
454
  Object.assign(document.body.style, safeAreaCSS);
455
}
456

457
// Listen for orientation changes
458
window.addEventListener('resize', () => {
459
  breakpoints.update();
460
  console.log(`New orientation: ${breakpoints.orientation}`);
461
});
462
```
463

464
### System Information Caching
465

466
Efficient caching patterns for system information that rarely changes.
467

468
```typescript
469
class SystemInfoCache {
470
  private static instance: SystemInfoCache;
471
  private cache: Map<string, { data: any, timestamp: number }> = new Map();
472
  private readonly TTL = 60000; // 1 minute TTL
473
  
474
  static getInstance(): SystemInfoCache {
475
    if (!SystemInfoCache.instance) {
476
      SystemInfoCache.instance = new SystemInfoCache();
477
    }
478
    return SystemInfoCache.instance;
479
  }
480
  
481
  getSystemInfo(): SystemInfo {
482
    const cached = this.cache.get('systemInfo');
483
    if (cached && Date.now() - cached.timestamp < this.TTL) {
484
      return cached.data;
485
    }
486
    
487
    const systemInfo = getSystemInfoSync();
488
    this.cache.set('systemInfo', {
489
      data: systemInfo,
490
      timestamp: Date.now()
491
    });
492
    
493
    return systemInfo;
494
  }
495
  
496
  getDeviceInfo(): DeviceInfo {
497
    const cached = this.cache.get('deviceInfo');
498
    if (cached && Date.now() - cached.timestamp < this.TTL) {
499
      return cached.data;
500
    }
501
    
502
    const deviceInfo = getDeviceInfo();
503
    this.cache.set('deviceInfo', {
504
      data: deviceInfo,
505
      timestamp: Date.now()
506
    });
507
    
508
    return deviceInfo;
509
  }
510
  
511
  clearCache(): void {
512
    this.cache.clear();
513
  }
514
}
515

516
// Usage
517
const systemCache = SystemInfoCache.getInstance();
518
const systemInfo = systemCache.getSystemInfo(); // Cached after first call
519
const deviceInfo = systemCache.getDeviceInfo(); // Cached after first call
520
```
521

522
## Types
523

524
```typescript { .api }
525
interface CallbackOptions {
526
  success?: (res: any) => void;
527
  fail?: (err: any) => void;
528
  complete?: (res: any) => void;
529
}
530

531
type DeviceType = 'phone' | 'tablet' | 'desktop' | 'unknown';
532
type ThemeSetting = 'light' | 'dark' | 'auto';
533
type DeviceOrientation = 'portrait' | 'landscape';
534
type PermissionScope = 
535
  | 'scope.userLocation'
536
  | 'scope.camera' 
537
  | 'scope.record'
538
  | 'scope.writePhotosAlbum'
539
  | 'scope.addressBook'
540
  | 'scope.invoiceTitle'
541
  | 'scope.notification'
542
  | 'scope.clipboard';
543
```