0
# Event System
1

2
Comprehensive event type definitions for touch interactions, UI components, media events, and custom events in WeChat Mini Programs.
3

4
## Capabilities
5

6
### Touch Events
7

8
Touch interaction events for user input handling.
9

10
```typescript { .api }
11
interface TouchEvent {
12
  /** Event type */
13
  type: string;
14
  /** Event timestamp */
15
  timeStamp: number;
16
  /** Event target element */
17
  target: EventTarget;
18
  /** Current event target */
19
  currentTarget: EventTarget;
20
  /** Touch detail information */
21
  detail: TouchDetail;
22
  /** All active touches */
23
  touches: Touch[];
24
  /** Changed touches in this event */
25
  changedTouches: Touch[];
26
}
27

28
interface Touch {
29
  /** Touch identifier */
30
  identifier: number;
31
  /** X coordinate relative to page */
32
  pageX: number;
33
  /** Y coordinate relative to page */
34
  pageY: number;
35
  /** X coordinate relative to client */
36
  clientX: number;
37
  /** Y coordinate relative to client */
38
  clientY: number;
39
}
40

41
interface TouchDetail {
42
  /** X coordinate */
43
  x: number;
44
  /** Y coordinate */
45
  y: number;
46
  /** Source (touch/mouse) */
47
  source: string;
48
}
49

50
interface TouchCanvas {
51
  /** Canvas touch event specific properties */
52
  identifier: number;
53
  x: number;
54
  y: number;
55
}
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
Page({
62
  onTouchStart(e: TouchEvent) {
63
    console.log('Touch started at:', e.touches[0].pageX, e.touches[0].pageY);
64
    console.log('Active touches:', e.touches.length);
65
  },
66
  
67
  onTouchMove(e: TouchEvent) {
68
    console.log('Touch moved to:', e.touches[0].pageX, e.touches[0].pageY);
69
  },
70
  
71
  onTouchEnd(e: TouchEvent) {
72
    console.log('Touch ended');
73
    console.log('Changed touches:', e.changedTouches.length);
74
  },
75
  
76
  onTap(e: TouchEvent) {
77
    console.log('Tapped at:', e.detail.x, e.detail.y);
78
  },
79
  
80
  onLongPress(e: TouchEvent) {
81
    console.log('Long pressed at:', e.detail.x, e.detail.y);
82
  }
83
});
84
```
85

86
### UI Component Events
87

88
Events from built-in WeChat Mini Program components.
89

90
```typescript { .api }
91
// Button events
92
interface ButtonTapEvent {
93
  type: 'tap';
94
  target: EventTarget;
95
  currentTarget: EventTarget;
96
  detail: {};
97
}
98

99
interface ButtonGetUserInfoEvent {
100
  type: 'getuserinfo';
101
  target: EventTarget;
102
  currentTarget: EventTarget;
103
  detail: {
104
    userInfo?: {
105
      nickName: string;
106
      avatarUrl: string;
107
      gender: number;
108
      city: string;
109
      province: string;
110
      country: string;
111
      language: string;
112
    };
113
    rawData?: string;
114
    signature?: string;
115
    encryptedData?: string;
116
    iv?: string;
117
    errMsg: string;
118
  };
119
}
120

121
// Form events
122
interface FormSubmitEvent {
123
  type: 'submit';
124
  target: EventTarget;
125
  currentTarget: EventTarget;
126
  detail: {
127
    value: Record<string, any>;
128
    formId: string;
129
  };
130
}
131

132
interface FormResetEvent {
133
  type: 'reset';
134
  target: EventTarget;
135
  currentTarget: EventTarget;
136
  detail: {};
137
}
138

139
// Input events
140
interface InputEvent {
141
  type: 'input';
142
  target: EventTarget;
143
  currentTarget: EventTarget;
144
  detail: {
145
    value: string;
146
    cursor: number;
147
    keyCode: number;
148
  };
149
}
150

151
interface InputConfirmEvent {
152
  type: 'confirm';
153
  target: EventTarget;
154
  currentTarget: EventTarget;
155
  detail: {
156
    value: string;
157
  };
158
}
159

160
interface InputFocusEvent {
161
  type: 'focus';
162
  target: EventTarget;
163
  currentTarget: EventTarget;
164
  detail: {
165
    value: string;
166
    height: number;
167
  };
168
}
169

170
interface InputBlurEvent {
171
  type: 'blur';
172
  target: EventTarget;
173
  currentTarget: EventTarget;
174
  detail: {
175
    value: string;
176
    cursor: number;
177
  };
178
}
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
Page({
185
  onFormSubmit(e: FormSubmitEvent) {
186
    console.log('Form submitted:', e.detail.value);
187
    // e.detail.value contains form field values
188
    const { username, email, age } = e.detail.value;
189
  },
190
  
191
  onInputChange(e: InputEvent) {
192
    console.log('Input value:', e.detail.value);
193
    console.log('Cursor position:', e.detail.cursor);
194
  },
195
  
196
  onButtonTap(e: ButtonTapEvent) {
197
    console.log('Button tapped');
198
  },
199
  
200
  onGetUserInfo(e: ButtonGetUserInfoEvent) {
201
    if (e.detail.userInfo) {
202
      console.log('User info:', e.detail.userInfo);
203
      this.setData({
204
        userInfo: e.detail.userInfo
205
      });
206
    } else {
207
      console.log('User denied authorization');
208
    }
209
  }
210
});
211
```
212

213
### Picker Events
214

215
Events from picker components for selecting values.
216

217
```typescript { .api }
218
interface PickerChangeEvent {
219
  type: 'change';
220
  target: EventTarget;
221
  currentTarget: EventTarget;
222
  detail: {
223
    value: number | number[] | string;
224
  };
225
}
226

227
interface PickerCancelEvent {
228
  type: 'cancel';
229
  target: EventTarget;
230
  currentTarget: EventTarget;
231
  detail: {};
232
}
233

234
interface PickerColumnChangeEvent {
235
  type: 'columnchange';
236
  target: EventTarget;
237
  currentTarget: EventTarget;
238
  detail: {
239
    column: number;
240
    value: number;
241
  };
242
}
243

244
// Date/Time picker specific
245
interface DateTimePickerChangeEvent {
246
  type: 'change';
247
  target: EventTarget;
248
  currentTarget: EventTarget;
249
  detail: {
250
    value: string; // Date string in YYYY-MM-DD or HH:mm format
251
  };
252
}
253

254
// Region picker specific  
255
interface RegionPickerChangeEvent {
256
  type: 'change';
257
  target: EventTarget;
258
  currentTarget: EventTarget;
259
  detail: {
260
    value: [string, string, string]; // [province, city, district]
261
    code: [string, string, string];  // Region codes
262
  };
263
}
264
```
265

266
### Switch and Slider Events
267

268
Events from switch and slider components.
269

270
```typescript { .api }
271
interface SwitchChangeEvent {
272
  type: 'change';
273
  target: EventTarget;
274
  currentTarget: EventTarget;
275
  detail: {
276
    value: boolean;
277
  };
278
}
279

280
interface SliderChangeEvent {
281
  type: 'change';
282
  target: EventTarget;
283
  currentTarget: EventTarget;
284
  detail: {
285
    value: number;
286
  };
287
}
288

289
interface SliderChangingEvent {
290
  type: 'changing';
291
  target: EventTarget;
292
  currentTarget: EventTarget;
293
  detail: {
294
    value: number;
295
  };
296
}
297
```
298

299
### Checkbox and Radio Events
300

301
Events from checkbox and radio group components.
302

303
```typescript { .api }
304
interface CheckboxGroupChangeEvent {
305
  type: 'change';
306
  target: EventTarget;
307
  currentTarget: EventTarget;
308
  detail: {
309
    value: string[]; // Array of selected checkbox values
310
  };
311
}
312

313
interface RadioGroupChangeEvent {
314
  type: 'change';
315
  target: EventTarget;
316
  currentTarget: EventTarget;
317
  detail: {
318
    value: string; // Selected radio value
319
  };
320
}
321
```
322

323
### Media Events
324

325
Events from video, audio, and camera components.
326

327
```typescript { .api }
328
interface VideoEvent {
329
  type: 'play' | 'pause' | 'ended' | 'timeupdate' | 'error' | 'waiting' | 'progress' | 'loadedmetadata' | 'fullscreenchange';
330
  target: EventTarget;
331
  currentTarget: EventTarget;
332
  detail: {
333
    currentTime?: number;
334
    duration?: number;
335
    buffered?: number;
336
    fullScreen?: boolean;
337
    direction?: 'vertical' | 'horizontal';
338
  };
339
}
340

341
interface AudioEvent {
342
  type: 'play' | 'pause' | 'ended' | 'timeupdate' | 'error';
343
  target: EventTarget;
344
  currentTarget: EventTarget;
345
  detail: {
346
    currentTime?: number;
347
    duration?: number;
348
  };
349
}
350

351
interface CameraEvent {
352
  type: 'stop' | 'error' | 'initdone' | 'scancode';
353
  target: EventTarget;
354
  currentTarget: EventTarget;
355
  detail: {
356
    msg?: string;
357
    result?: string;
358
    scanType?: string;
359
    charSet?: string;
360
    path?: string;
361
  };
362
}
363

364
interface ImageLoadEvent {
365
  type: 'load' | 'error';
366
  target: EventTarget;
367
  currentTarget: EventTarget;
368
  detail: {
369
    width?: number;
370
    height?: number;
371
    errMsg?: string;
372
  };
373
}
374
```
375

376
**Usage Examples:**
377

378
```typescript
379
Page({
380
  onVideoPlay(e: VideoEvent) {
381
    console.log('Video started playing');
382
  },
383
  
384
  onVideoTimeUpdate(e: VideoEvent) {
385
    console.log('Video time:', e.detail.currentTime, '/', e.detail.duration);
386
  },
387
  
388
  onVideoEnded(e: VideoEvent) {
389
    console.log('Video playback ended');
390
  },
391
  
392
  onCameraScanCode(e: CameraEvent) {
393
    console.log('QR code scanned:', e.detail.result);
394
    console.log('Scan type:', e.detail.scanType);
395
  },
396
  
397
  onImageLoad(e: ImageLoadEvent) {
398
    console.log('Image loaded:', e.detail.width, 'x', e.detail.height);
399
  }
400
});
401
```
402

403
### Scroll and Navigation Events
404

405
Events from scroll containers and navigation components.
406

407
```typescript { .api }
408
interface ScrollViewEvent {
409
  type: 'scroll' | 'scrolltoupper' | 'scrolltolower' | 'refresherpulling' | 'refresherrefresh' | 'refresherrestore' | 'refresherabort';
410
  target: EventTarget;
411
  currentTarget: EventTarget;
412
  detail: {
413
    scrollLeft?: number;
414
    scrollTop?: number;
415
    scrollHeight?: number;
416
    scrollWidth?: number;
417
    deltaX?: number;
418
    deltaY?: number;
419
  };
420
}
421

422
interface SwiperEvent {
423
  type: 'change' | 'transition' | 'animationfinish';
424
  target: EventTarget;
425
  currentTarget: EventTarget;
426
  detail: {
427
    current: number;
428
    source: string;
429
    currentItemId?: string;
430
  };
431
}
432

433
interface NavigatorSuccessEvent {
434
  type: 'success';
435
  target: EventTarget;
436
  currentTarget: EventTarget;
437
  detail: {};
438
}
439

440
interface NavigatorFailEvent {
441
  type: 'fail';
442
  target: EventTarget;
443
  currentTarget: EventTarget;
444
  detail: {
445
    errMsg: string;
446
  };
447
}
448
```
449

450
### Map Events
451

452
Events from map components for location and interaction handling.
453

454
```typescript { .api }
455
interface MapEvent {
456
  type: 'tap' | 'markertap' | 'labeltap' | 'controltap' | 'callouttap' | 'updated' | 'regionchange' | 'poitap' | 'anchortap';
457
  target: EventTarget;
458
  currentTarget: EventTarget;
459
  detail: {
460
    markerId?: number;
461
    labelId?: number;
462
    controlId?: number;
463
    name?: string;
464
    longitude?: number;
465
    latitude?: number;
466
    causedBy?: string;
467
    type?: number;
468
  };
469
}
470
```
471

472
### Custom Events
473

474
Custom events triggered by components.
475

476
```typescript { .api }
477
interface CustomEvent<T = any> {
478
  type: string;
479
  target: EventTarget;
480
  currentTarget: EventTarget;
481
  detail: T;
482
  bubbles?: boolean;
483
  composed?: boolean;
484
  capturePhase?: boolean;
485
}
486
```
487

488
**Usage Examples:**
489

490
```typescript
491
// Component triggering custom event
492
Component({
493
  methods: {
494
    handleItemClick() {
495
      this.triggerEvent('itemclick', {
496
        id: this.data.itemId,
497
        name: this.data.itemName,
498
        timestamp: Date.now()
499
      }, {
500
        bubbles: true,
501
        composed: true
502
      });
503
    }
504
  }
505
});
506

507
// Parent handling custom event
508
Page({
509
  onItemClick(e: CustomEvent<{ id: string; name: string; timestamp: number }>) {
510
    console.log('Item clicked:', e.detail.name);
511
    console.log('Item ID:', e.detail.id);
512
    console.log('Click time:', e.detail.timestamp);
513
  }
514
});
515
```
516

517
## Event Target Interface
518

519
```typescript { .api }
520
interface EventTarget {
521
  /** Element ID */
522
  id: string;
523
  /** Tag name */
524
  tagName: string;
525
  /** Element dataset */
526
  dataset: Record<string, any>;
527
  /** Bounding client rect */
528
  offsetLeft: number;
529
  offsetTop: number;
530
  offsetWidth: number;
531
  offsetHeight: number;
532
}
533
```
534

535
## Event Handler Patterns
536

537
```typescript { .api }
538
// Event handler function type
539
type EventHandler<T = TouchEvent> = (event: T) => void;
540

541
// Common event handler interface for components/pages
542
interface EventHandlers {
543
  // Touch events
544
  onTouchStart?: EventHandler<TouchEvent>;
545
  onTouchMove?: EventHandler<TouchEvent>;
546
  onTouchEnd?: EventHandler<TouchEvent>;
547
  onTouchCancel?: EventHandler<TouchEvent>;
548
  onTap?: EventHandler<TouchEvent>;
549
  onLongPress?: EventHandler<TouchEvent>;
550
  onLongTap?: EventHandler<TouchEvent>;
551
  
552
  // Form events
553
  onSubmit?: EventHandler<FormSubmitEvent>;
554
  onReset?: EventHandler<FormResetEvent>;
555
  onInput?: EventHandler<InputEvent>;
556
  onFocus?: EventHandler<InputFocusEvent>;
557
  onBlur?: EventHandler<InputBlurEvent>;
558
  
559
  // Picker events
560
  onChange?: EventHandler<PickerChangeEvent>;
561
  onCancel?: EventHandler<PickerCancelEvent>;
562
  
563
  // Media events
564
  onPlay?: EventHandler<VideoEvent>;
565
  onPause?: EventHandler<VideoEvent>;
566
  onEnded?: EventHandler<VideoEvent>;
567
  onError?: EventHandler<VideoEvent>;
568
  
569
  // Custom events
570
  [key: string]: EventHandler<any> | undefined;
571
}
572
```
573

574
## Types
575

576
```typescript { .api }
577
// Base event interface
578
interface BaseEvent {
579
  type: string;
580
  timeStamp: number;
581
  target: EventTarget;
582
  currentTarget: EventTarget;
583
}
584

585
// Touch-related types
586
interface TouchEvent extends BaseEvent {
587
  detail: TouchDetail;
588
  touches: Touch[];
589
  changedTouches: Touch[];
590
}
591

592
// Component event types
593
interface ComponentEvent<T = any> extends BaseEvent {
594
  detail: T;
595
}
596

597
// Event type utilities
598
type EventType = 
599
  | 'tap' | 'touchstart' | 'touchmove' | 'touchend' | 'touchcancel'
600
  | 'input' | 'focus' | 'blur' | 'confirm'
601
  | 'change' | 'cancel' | 'columnchange'
602
  | 'submit' | 'reset'
603
  | 'play' | 'pause' | 'ended' | 'timeupdate' | 'error'
604
  | 'scroll' | 'scrolltoupper' | 'scrolltolower'
605
  | 'load' | 'complete'
606
  | string; // Allow custom event types
607
```