0
# Location & Sensor APIs
1

2
Geolocation services and device sensor access including accelerometer, gyroscope, device motion, and location tracking for Taro React Native applications.
3

4
## Capabilities
5

6
### Location Services
7

8
Access device location and monitor location changes.
9

10
```typescript { .api }
11
/**
12
 * Get current device location
13
 * @param options Location options
14
 */
15
function getLocation(options?: {
16
  type?: 'wgs84' | 'gcj02';
17
  altitude?: boolean;
18
  isHighAccuracy?: boolean;
19
  highAccuracyExpireTime?: number;
20
  success?: (res: {
21
    latitude: number;
22
    longitude: number;
23
    speed: number;
24
    accuracy: number;
25
    altitude?: number;
26
    verticalAccuracy?: number;
27
    horizontalAccuracy?: number;
28
  }) => void;
29
  fail?: (res: TaroGeneral.CallbackResult) => void;
30
  complete?: (res: any) => void;
31
}): Promise<{
32
  latitude: number;
33
  longitude: number;
34
  speed: number;
35
  accuracy: number;
36
  altitude?: number;
37
  verticalAccuracy?: number;
38
  horizontalAccuracy?: number;
39
}>;
40

41
/**
42
 * Start continuous location updates
43
 * @param options Location update options
44
 */
45
function startLocationUpdate(options?: {
46
  type?: 'wgs84' | 'gcj02';
47
  success?: (res: TaroGeneral.CallbackResult) => void;
48
  fail?: (res: TaroGeneral.CallbackResult) => void;
49
  complete?: (res: TaroGeneral.CallbackResult) => void;
50
}): Promise<TaroGeneral.CallbackResult>;
51

52
/**
53
 * Stop continuous location updates
54
 * @param options Stop location options
55
 */
56
function stopLocationUpdate(options?: {
57
  success?: (res: TaroGeneral.CallbackResult) => void;
58
  fail?: (res: TaroGeneral.CallbackResult) => void;
59
  complete?: (res: TaroGeneral.CallbackResult) => void;
60
}): Promise<TaroGeneral.CallbackResult>;
61

62
/**
63
 * Listen to location change events
64
 * @param callback Location change callback
65
 */
66
function onLocationChange(callback: (res: {
67
  latitude: number;
68
  longitude: number;
69
  speed: number;
70
  accuracy: number;
71
  altitude?: number;
72
  verticalAccuracy?: number;
73
  horizontalAccuracy?: number;
74
}) => void): void;
75

76
/**
77
 * Stop listening to location change events
78
 * @param callback Optional callback to remove specific listener
79
 */
80
function offLocationChange(callback?: (res: {
81
  latitude: number;
82
  longitude: number;
83
  speed: number;
84
  accuracy: number;
85
}) => void): void;
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
import { 
92
  getLocation, 
93
  startLocationUpdate, 
94
  onLocationChange, 
95
  stopLocationUpdate 
96
} from "@tarojs/taro-rn";
97

98
// Get current location
99
const location = await getLocation({
100
  type: 'wgs84',
101
  altitude: true,
102
  isHighAccuracy: true
103
});
104

105
console.log('Current location:', location.latitude, location.longitude);
106
console.log('Altitude:', location.altitude);
107
console.log('Accuracy:', location.accuracy);
108

109
// Start continuous location tracking
110
await startLocationUpdate({ type: 'wgs84' });
111

112
const locationChangeHandler = (res) => {
113
  console.log('Location changed:', res.latitude, res.longitude);
114
  console.log('Speed:', res.speed, 'm/s');
115
};
116

117
onLocationChange(locationChangeHandler);
118

119
// Stop tracking when done
120
setTimeout(async () => {
121
  await stopLocationUpdate();
122
  offLocationChange(locationChangeHandler);
123
}, 60000); // Stop after 1 minute
124
```
125

126
### Accelerometer
127

128
Access device accelerometer for motion detection.
129

130
```typescript { .api }
131
/**
132
 * Start accelerometer monitoring
133
 * @param options Accelerometer options
134
 */
135
function startAccelerometer(options?: {
136
  interval?: 'game' | 'ui' | 'normal';
137
  success?: (res: TaroGeneral.CallbackResult) => void;
138
  fail?: (res: TaroGeneral.CallbackResult) => void;
139
  complete?: (res: TaroGeneral.CallbackResult) => void;
140
}): Promise<TaroGeneral.CallbackResult>;
141

142
/**
143
 * Stop accelerometer monitoring
144
 * @param options Stop accelerometer options
145
 */
146
function stopAccelerometer(options?: {
147
  success?: (res: TaroGeneral.CallbackResult) => void;
148
  fail?: (res: TaroGeneral.CallbackResult) => void;
149
  complete?: (res: TaroGeneral.CallbackResult) => void;
150
}): Promise<TaroGeneral.CallbackResult>;
151

152
/**
153
 * Listen to accelerometer data changes
154
 * @param callback Accelerometer change callback
155
 */
156
function onAccelerometerChange(callback: (res: {
157
  x: number;
158
  y: number;
159
  z: number;
160
}) => void): void;
161

162
/**
163
 * Stop listening to accelerometer changes
164
 * @param callback Optional callback to remove specific listener
165
 */
166
function offAccelerometerChange(callback?: (res: {
167
  x: number;
168
  y: number;
169
  z: number;
170
}) => void): void;
171
```
172

173
**Usage Examples:**
174

175
```typescript
176
import { 
177
  startAccelerometer, 
178
  onAccelerometerChange, 
179
  stopAccelerometer 
180
} from "@tarojs/taro-rn";
181

182
// Start accelerometer with high frequency
183
await startAccelerometer({ interval: 'game' });
184

185
const accelerometerHandler = (res) => {
186
  console.log('Acceleration X:', res.x);
187
  console.log('Acceleration Y:', res.y);
188
  console.log('Acceleration Z:', res.z);
189
  
190
  // Detect shake gesture
191
  const totalAcceleration = Math.sqrt(res.x * res.x + res.y * res.y + res.z * res.z);
192
  if (totalAcceleration > 15) {
193
    console.log('Shake detected!');
194
  }
195
};
196

197
onAccelerometerChange(accelerometerHandler);
198

199
// Stop after 30 seconds
200
setTimeout(async () => {
201
  await stopAccelerometer();
202
  offAccelerometerChange(accelerometerHandler);
203
}, 30000);
204
```
205

206
### Gyroscope
207

208
Access device gyroscope for rotation detection.
209

210
```typescript { .api }
211
/**
212
 * Start gyroscope monitoring
213
 * @param options Gyroscope options
214
 */
215
function startGyroscope(options?: {
216
  interval?: 'game' | 'ui' | 'normal';
217
  success?: (res: TaroGeneral.CallbackResult) => void;
218
  fail?: (res: TaroGeneral.CallbackResult) => void;
219
  complete?: (res: TaroGeneral.CallbackResult) => void;
220
}): Promise<TaroGeneral.CallbackResult>;
221

222
/**
223
 * Stop gyroscope monitoring
224
 * @param options Stop gyroscope options
225
 */
226
function stopGyroscope(options?: {
227
  success?: (res: TaroGeneral.CallbackResult) => void;
228
  fail?: (res: TaroGeneral.CallbackResult) => void;
229
  complete?: (res: TaroGeneral.CallbackResult) => void;
230
}): Promise<TaroGeneral.CallbackResult>;
231

232
/**
233
 * Listen to gyroscope data changes
234
 * @param callback Gyroscope change callback
235
 */
236
function onGyroscopeChange(callback: (res: {
237
  x: number;
238
  y: number;
239
  z: number;
240
}) => void): void;
241

242
/**
243
 * Stop listening to gyroscope changes
244
 * @param callback Optional callback to remove specific listener
245
 */
246
function offGyroscopeChange(callback?: (res: {
247
  x: number;
248
  y: number;
249
  z: number;
250
}) => void): void;
251
```
252

253
### Device Motion
254

255
Access comprehensive device motion data combining accelerometer and gyroscope.
256

257
```typescript { .api }
258
/**
259
 * Start device motion listening
260
 * @param options Device motion options
261
 */
262
function startDeviceMotionListening(options?: {
263
  interval?: 'game' | 'ui' | 'normal';
264
  success?: (res: TaroGeneral.CallbackResult) => void;
265
  fail?: (res: TaroGeneral.CallbackResult) => void;
266
  complete?: (res: TaroGeneral.CallbackResult) => void;
267
}): Promise<TaroGeneral.CallbackResult>;
268

269
/**
270
 * Stop device motion listening
271
 * @param options Stop device motion options
272
 */
273
function stopDeviceMotionListening(options?: {
274
  success?: (res: TaroGeneral.CallbackResult) => void;
275
  fail?: (res: TaroGeneral.CallbackResult) => void;
276
  complete?: (res: TaroGeneral.CallbackResult) => void;
277
}): Promise<TaroGeneral.CallbackResult>;
278

279
/**
280
 * Listen to device motion changes
281
 * @param callback Device motion change callback
282
 */
283
function onDeviceMotionChange(callback: (res: {
284
  alpha: number;
285
  beta: number;
286
  gamma: number;
287
}) => void): void;
288

289
/**
290
 * Stop listening to device motion changes
291
 * @param callback Optional callback to remove specific listener
292
 */
293
function offDeviceMotionChange(callback?: (res: {
294
  alpha: number;
295
  beta: number;
296
  gamma: number;
297
}) => void): void;
298
```
299

300
**Usage Examples:**
301

302
```typescript
303
import { 
304
  startGyroscope, 
305
  onGyroscopeChange, 
306
  startDeviceMotionListening,
307
  onDeviceMotionChange,
308
  stopGyroscope,
309
  stopDeviceMotionListening
310
} from "@tarojs/taro-rn";
311

312
// Start gyroscope monitoring
313
await startGyroscope({ interval: 'ui' });
314

315
const gyroscopeHandler = (res) => {
316
  console.log('Rotation X:', res.x);
317
  console.log('Rotation Y:', res.y);
318
  console.log('Rotation Z:', res.z);
319
};
320

321
onGyroscopeChange(gyroscopeHandler);
322

323
// Start device motion for orientation
324
await startDeviceMotionListening({ interval: 'ui' });
325

326
const motionHandler = (res) => {
327
  console.log('Alpha (Z-axis):', res.alpha);
328
  console.log('Beta (X-axis):', res.beta);
329
  console.log('Gamma (Y-axis):', res.gamma);
330
  
331
  // Detect device orientation
332
  if (Math.abs(res.gamma) > 45) {
333
    console.log('Device tilted horizontally');
334
  }
335
  if (Math.abs(res.beta) > 45) {
336
    console.log('Device tilted vertically');
337
  }
338
};
339

340
onDeviceMotionChange(motionHandler);
341

342
// Clean up
343
setTimeout(async () => {
344
  await stopGyroscope();
345
  await stopDeviceMotionListening();
346
}, 60000);
347
```
348

349
### Window & Screen Events
350

351
Monitor window resize and screen capture events.
352

353
```typescript { .api }
354
/**
355
 * Listen to window resize events
356
 * @param callback Window resize callback
357
 */
358
function onWindowResize(callback: (res: {
359
  size: {
360
    windowWidth: number;
361
    windowHeight: number;
362
  };
363
}) => void): void;
364

365
/**
366
 * Stop listening to window resize events
367
 * @param callback Optional callback to remove specific listener
368
 */
369
function offWindowResize(callback?: (res: {
370
  size: {
371
    windowWidth: number;
372
    windowHeight: number;
373
  };
374
}) => void): void;
375

376
/**
377
 * Listen to user screen capture events
378
 * @param callback Screen capture callback
379
 */
380
function onUserCaptureScreen(callback: () => void): void;
381

382
/**
383
 * Stop listening to user screen capture events
384
 * @param callback Optional callback to remove specific listener
385
 */
386
function offUserCaptureScreen(callback?: () => void): void;
387
```
388

389
**Usage Examples:**
390

391
```typescript
392
import { 
393
  onWindowResize, 
394
  onUserCaptureScreen,
395
  offWindowResize,
396
  offUserCaptureScreen
397
} from "@tarojs/taro-rn";
398

399
// Monitor window resize
400
const resizeHandler = (res) => {
401
  console.log('Window resized:', res.size.windowWidth, 'x', res.size.windowHeight);
402
  
403
  // Adapt layout based on new size
404
  if (res.size.windowWidth < res.size.windowHeight) {
405
    console.log('Portrait mode');
406
  } else {
407
    console.log('Landscape mode');
408
  }
409
};
410

411
onWindowResize(resizeHandler);
412

413
// Monitor screen capture
414
const captureHandler = () => {
415
  console.log('User took a screenshot');
416
  // Optionally show a message or log the event
417
  showToast({ title: 'Screenshot taken', icon: 'none' });
418
};
419

420
onUserCaptureScreen(captureHandler);
421

422
// Clean up listeners when component unmounts
423
// offWindowResize(resizeHandler);
424
// offUserCaptureScreen(captureHandler);
425
```
426

427
## Sensor Data Processing
428

429
### Motion Detection Patterns
430

431
Common patterns for processing sensor data:
432

433
```typescript
434
import { 
435
  startAccelerometer, 
436
  onAccelerometerChange,
437
  startGyroscope,
438
  onGyroscopeChange
439
} from "@tarojs/taro-rn";
440

441
// Shake detection
442
let lastShakeTime = 0;
443
const shakeThreshold = 15;
444
const shakeInterval = 1000; // Minimum time between shakes
445

446
const shakeDetector = (res) => {
447
  const acceleration = Math.sqrt(res.x * res.x + res.y * res.y + res.z * res.z);
448
  const now = Date.now();
449
  
450
  if (acceleration > shakeThreshold && (now - lastShakeTime) > shakeInterval) {
451
    lastShakeTime = now;
452
    console.log('Shake gesture detected!');
453
    // Trigger shake action
454
  }
455
};
456

457
// Tilt detection
458
const tiltDetector = (res) => {
459
  const tiltX = Math.atan2(res.y, res.z) * (180 / Math.PI);
460
  const tiltY = Math.atan2(res.x, res.z) * (180 / Math.PI);
461
  
462
  if (Math.abs(tiltX) > 30) {
463
    console.log('Device tilted left/right:', tiltX);
464
  }
465
  if (Math.abs(tiltY) > 30) {
466
    console.log('Device tilted forward/back:', tiltY);
467
  }
468
};
469

470
// Rotation tracking
471
let rotationData = { x: 0, y: 0, z: 0 };
472

473
const rotationTracker = (res) => {
474
  // Integrate gyroscope data for rotation tracking
475
  const deltaTime = 0.1; // Assume 10Hz update rate
476
  rotationData.x += res.x * deltaTime;
477
  rotationData.y += res.y * deltaTime;
478
  rotationData.z += res.z * deltaTime;
479
  
480
  console.log('Cumulative rotation:', rotationData);
481
};
482

483
// Start monitoring
484
startAccelerometer({ interval: 'game' });
485
onAccelerometerChange(shakeDetector);
486
onAccelerometerChange(tiltDetector);
487

488
startGyroscope({ interval: 'game' });
489
onGyroscopeChange(rotationTracker);
490
```