0
# Skyline Components
1

2
Advanced UI components including gesture handlers, enhanced layout components, and performance-optimized list views for modern application interfaces.
3

4
## Capabilities
5

6
### Gesture Handlers
7

8
Advanced gesture recognition components for handling complex touch interactions.
9

10
```typescript { .api }
11
/**
12
 * Tap gesture recognition component
13
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
14
 */
15
const TapGestureHandler: ComponentType<TapGestureHandlerProps>;
16

17
interface TapGestureHandlerProps extends StandardProps {
18
  /** Tag identifier for gesture handler
19
   * @supported weapp, tt, qq, jd
20
   */
21
  tag?: string;
22
  /** Whether gesture handler is enabled
23
   * @supported weapp, tt, qq, jd
24
   * @default true
25
   */
26
  enabled?: boolean;
27
  /** Whether to prevent other gesture handlers
28
   * @supported weapp, tt, qq, jd
29
   * @default false
30
   */
31
  shouldCancelWhenOutside?: boolean;
32
  /** Number of taps required
33
   * @supported weapp, tt, qq, jd
34
   * @default 1
35
   */
36
  numberOfTaps?: number;
37
  /** Gesture state change callback */
38
  onGestureEvent?: (event: GestureEvent) => void;
39
  /** Handler state change callback */
40
  onHandlerStateChange?: (event: GestureHandlerStateChangeEvent) => void;
41
}
42

43
/**
44
 * Double tap gesture recognition component
45
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
46
 */
47
const DoubleTapGestureHandler: ComponentType<DoubleTapGestureHandlerProps>;
48

49
interface DoubleTapGestureHandlerProps extends StandardProps {
50
  /** Tag identifier for gesture handler
51
   * @supported weapp, tt, qq, jd
52
   */
53
  tag?: string;
54
  /** Whether gesture handler is enabled
55
   * @supported weapp, tt, qq, jd
56
   * @default true
57
   */
58
  enabled?: boolean;
59
  /** Maximum time between taps in milliseconds
60
   * @supported weapp, tt, qq, jd
61
   * @default 300
62
   */
63
  maxDelayBetweenTaps?: number;
64
  /** Gesture state change callback */
65
  onGestureEvent?: (event: GestureEvent) => void;
66
  /** Handler state change callback */
67
  onHandlerStateChange?: (event: GestureHandlerStateChangeEvent) => void;
68
}
69

70
/**
71
 * Long press gesture recognition component
72
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
73
 */
74
const LongPressGestureHandler: ComponentType<LongPressGestureHandlerProps>;
75

76
interface LongPressGestureHandlerProps extends StandardProps {
77
  /** Tag identifier for gesture handler
78
   * @supported weapp, tt, qq, jd
79
   */
80
  tag?: string;
81
  /** Whether gesture handler is enabled
82
   * @supported weapp, tt, qq, jd
83
   * @default true
84
   */
85
  enabled?: boolean;
86
  /** Minimum press duration in milliseconds
87
   * @supported weapp, tt, qq, jd
88
   * @default 500
89
   */
90
  minDurationMs?: number;
91
  /** Maximum distance finger can move
92
   * @supported weapp, tt, qq, jd
93
   * @default 10
94
   */
95
  maxDist?: number;
96
  /** Gesture state change callback */
97
  onGestureEvent?: (event: GestureEvent) => void;
98
  /** Handler state change callback */
99
  onHandlerStateChange?: (event: GestureHandlerStateChangeEvent) => void;
100
}
101

102
/**
103
 * Pan gesture recognition component
104
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
105
 */
106
const PanGestureHandler: ComponentType<PanGestureHandlerProps>;
107

108
interface PanGestureHandlerProps extends StandardProps {
109
  /** Tag identifier for gesture handler
110
   * @supported weapp, tt, qq, jd
111
   */
112
  tag?: string;
113
  /** Whether gesture handler is enabled
114
   * @supported weapp, tt, qq, jd
115
   * @default true
116
   */
117
  enabled?: boolean;
118
  /** Minimum number of fingers
119
   * @supported weapp, tt, qq, jd
120
   * @default 1
121
   */
122
  minPointers?: number;
123
  /** Maximum number of fingers
124
   * @supported weapp, tt, qq, jd
125
   * @default 10
126
   */
127
  maxPointers?: number;
128
  /** Minimum distance to activate
129
   * @supported weapp, tt, qq, jd
130
   * @default 10
131
   */
132
  minDist?: number;
133
  /** Minimum velocity to activate
134
   * @supported weapp, tt, qq, jd
135
   * @default 0
136
   */
137
  minVelocity?: number;
138
  /** Average touches for velocity calculation
139
   * @supported weapp, tt, qq, jd
140
   * @default false
141
   */
142
  avgTouches?: boolean;
143
  /** Gesture state change callback */
144
  onGestureEvent?: (event: PanGestureEvent) => void;
145
  /** Handler state change callback */
146
  onHandlerStateChange?: (event: GestureHandlerStateChangeEvent) => void;
147
}
148

149
/**
150
 * Scale/pinch gesture recognition component
151
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
152
 */
153
const ScaleGestureHandler: ComponentType<ScaleGestureHandlerProps>;
154

155
interface ScaleGestureHandlerProps extends StandardProps {
156
  /** Tag identifier for gesture handler
157
   * @supported weapp, tt, qq, jd
158
   */
159
  tag?: string;
160
  /** Whether gesture handler is enabled
161
   * @supported weapp, tt, qq, jd
162
   * @default true
163
   */
164
  enabled?: boolean;
165
  /** Gesture state change callback */
166
  onGestureEvent?: (event: ScaleGestureEvent) => void;
167
  /** Handler state change callback */
168
  onHandlerStateChange?: (event: GestureHandlerStateChangeEvent) => void;
169
}
170

171
/**
172
 * Horizontal drag gesture recognition component
173
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
174
 */
175
const HorizontalDragGestureHandler: ComponentType<HorizontalDragGestureHandlerProps>;
176

177
interface HorizontalDragGestureHandlerProps extends StandardProps {
178
  /** Tag identifier for gesture handler
179
   * @supported weapp, tt, qq, jd
180
   */
181
  tag?: string;
182
  /** Whether gesture handler is enabled
183
   * @supported weapp, tt, qq, jd
184
   * @default true
185
   */
186
  enabled?: boolean;
187
  /** Gesture state change callback */
188
  onGestureEvent?: (event: PanGestureEvent) => void;
189
  /** Handler state change callback */
190
  onHandlerStateChange?: (event: GestureHandlerStateChangeEvent) => void;
191
}
192

193
/**
194
 * Vertical drag gesture recognition component
195
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
196
 */
197
const VerticalDragGestureHandler: ComponentType<VerticalDragGestureHandlerProps>;
198

199
interface VerticalDragGestureHandlerProps extends StandardProps {
200
  /** Tag identifier for gesture handler
201
   * @supported weapp, tt, qq, jd
202
   */
203
  tag?: string;
204
  /** Whether gesture handler is enabled
205
   * @supported weapp, tt, qq, jd
206
   * @default true
207
   */
208
  enabled?: boolean;
209
  /** Gesture state change callback */
210
  onGestureEvent?: (event: PanGestureEvent) => void;
211
  /** Handler state change callback */
212
  onHandlerStateChange?: (event: GestureHandlerStateChangeEvent) => void;
213
}
214

215
/**
216
 * Force press gesture recognition component
217
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
218
 */
219
const ForcePressGestureHandler: ComponentType<ForcePressGestureHandlerProps>;
220

221
interface ForcePressGestureHandlerProps extends StandardProps {
222
  /** Tag identifier for gesture handler
223
   * @supported weapp, tt, qq, jd
224
   */
225
  tag?: string;
226
  /** Whether gesture handler is enabled
227
   * @supported weapp, tt, qq, jd
228
   * @default true
229
   */
230
  enabled?: boolean;
231
  /** Minimum force to activate
232
   * @supported weapp, tt, qq, jd
233
   * @default 0.2
234
   */
235
  minForce?: number;
236
  /** Gesture state change callback */
237
  onGestureEvent?: (event: ForcePressGestureEvent) => void;
238
  /** Handler state change callback */
239
  onHandlerStateChange?: (event: GestureHandlerStateChangeEvent) => void;
240
}
241
```
242

243
### Enhanced Layout Components
244

245
High-performance layout components optimized for complex UIs and large datasets.
246

247
```typescript { .api }
248
/**
249
 * High-performance list view component
250
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
251
 */
252
const ListView: ComponentType<ListViewProps>;
253

254
interface ListViewProps extends StandardProps {
255
  /** List type
256
   * @supported weapp, tt, qq, jd
257
   * @default "list"
258
   */
259
  type?: 'list' | 'waterfall';
260
  /** Cross axis count for waterfall layout
261
   * @supported weapp, tt, qq, jd
262
   * @default 2
263
   */
264
  crossAxisCount?: number;
265
  /** Maximum cross axis extent
266
   * @supported weapp, tt, qq, jd
267
   */
268
  maxCrossAxisExtent?: number;
269
  /** Main axis spacing
270
   * @supported weapp, tt, qq, jd
271
   * @default 0
272
   */
273
  mainAxisSpacing?: number;
274
  /** Cross axis spacing
275
   * @supported weapp, tt, qq, jd
276
   * @default 0
277
   */
278
  crossAxisSpacing?: number;
279
  /** Padding
280
   * @supported weapp, tt, qq, jd
281
   */
282
  padding?: string;
283
  /** Scroll direction
284
   * @supported weapp, tt, qq, jd
285
   * @default "vertical"
286
   */
287
  scrollDirection?: 'vertical' | 'horizontal';
288
  /** Whether reverse layout
289
   * @supported weapp, tt, qq, jd
290
   * @default false
291
   */
292
  reverse?: boolean;
293
  /** List scroll callback */
294
  onScroll?: (event: ListViewScrollEvent) => void;
295
  /** Reach top callback */
296
  onScrollToUpper?: (event: TaroEvent) => void;
297
  /** Reach bottom callback */
298
  onScrollToLower?: (event: TaroEvent) => void;
299
}
300

301
/**
302
 * List builder component for dynamic list construction
303
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
304
 */
305
const ListBuilder: ComponentType<ListBuilderProps>;
306

307
interface ListBuilderProps extends StandardProps {
308
  /** Build function for list items
309
   * @supported weapp, tt, qq, jd
310
   */
311
  builder?: (index: number) => any;
312
  /** Number of items in list
313
   * @supported weapp, tt, qq, jd
314
   */
315
  childCount?: number;
316
}
317

318
/**
319
 * High-performance grid view component
320
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
321
 */
322
const GridView: ComponentType<GridViewProps>;
323

324
interface GridViewProps extends StandardProps {
325
  /** Cross axis count
326
   * @supported weapp, tt, qq, jd
327
   * @default 2
328
   */
329
  crossAxisCount?: number;
330
  /** Maximum cross axis extent
331
   * @supported weapp, tt, qq, jd
332
   */
333
  maxCrossAxisExtent?: number;
334
  /** Main axis spacing
335
   * @supported weapp, tt, qq, jd
336
   * @default 0
337
   */
338
  mainAxisSpacing?: number;
339
  /** Cross axis spacing
340
   * @supported weapp, tt, qq, jd
341
   * @default 0
342
   */
343
  crossAxisSpacing?: number;
344
  /** Child aspect ratio
345
   * @supported weapp, tt, qq, jd
346
   * @default 1
347
   */
348
  childAspectRatio?: number;
349
  /** Padding
350
   * @supported weapp, tt, qq, jd
351
   */
352
  padding?: string;
353
  /** Grid scroll callback */
354
  onScroll?: (event: GridViewScrollEvent) => void;
355
}
356

357
/**
358
 * Grid builder component for dynamic grid construction
359
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
360
 */
361
const GridBuilder: ComponentType<GridBuilderProps>;
362

363
interface GridBuilderProps extends StandardProps {
364
  /** Build function for grid items
365
   * @supported weapp, tt, qq, jd
366
   */
367
  builder?: (index: number) => any;
368
  /** Number of items in grid
369
   * @supported weapp, tt, qq, jd
370
   */
371
  childCount?: number;
372
  /** Cross axis count
373
   * @supported weapp, tt, qq, jd
374
   * @default 2
375
   */
376
  crossAxisCount?: number;
377
}
378

379
/**
380
 * Basic list container component
381
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
382
 */
383
const List: ComponentType<ListProps>;
384

385
interface ListProps extends StandardProps {
386
  // Basic list properties
387
}
388

389
/**
390
 * List item component for use within List
391
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
392
 */
393
const ListItem: ComponentType<ListItemProps>;
394

395
interface ListItemProps extends StandardProps {
396
  // List item properties
397
}
398
```
399

400
### Sticky and Advanced Layout
401

402
Components for creating sticky headers, draggable sheets, and nested scroll behaviors.
403

404
```typescript { .api }
405
/**
406
 * Sticky header component
407
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
408
 */
409
const StickyHeader: ComponentType<StickyHeaderProps>;
410

411
interface StickyHeaderProps extends StandardProps {
412
  /** Offset from top when sticky
413
   * @supported weapp, tt, qq, jd
414
   * @default 0
415
   */
416
  offsetY?: number;
417
}
418

419
/**
420
 * Sticky section component
421
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
422
 */
423
const StickySection: ComponentType<StickySectionProps>;
424

425
interface StickySectionProps extends StandardProps {
426
  /** Offset from top when sticky
427
   * @supported weapp, tt, qq, jd
428
   * @default 0
429
   */
430
  offsetY?: number;
431
  /** Whether to push up previous sticky element
432
   * @supported weapp, tt, qq, jd
433
   * @default false
434
   */
435
  pushUp?: boolean;
436
}
437

438
/**
439
 * Draggable bottom sheet component
440
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
441
 */
442
const DraggableSheet: ComponentType<DraggableSheetProps>;
443

444
interface DraggableSheetProps extends StandardProps {
445
  /** Initial child size ratio
446
   * @supported weapp, tt, qq, jd
447
   * @default 0.5
448
   */
449
  initialChildSize?: number;
450
  /** Minimum child size ratio
451
   * @supported weapp, tt, qq, jd
452
   * @default 0.25
453
   */
454
  minChildSize?: number;
455
  /** Maximum child size ratio
456
   * @supported weapp, tt, qq, jd
457
   * @default 1.0
458
   */
459
  maxChildSize?: number;
460
  /** Whether sheet can expand
461
   * @supported weapp, tt, qq, jd
462
   * @default true
463
   */
464
  expand?: boolean;
465
  /** Snap animation duration
466
   * @supported weapp, tt, qq, jd
467
   * @default 250
468
   */
469
  snapAnimationDuration?: number;
470
  /** Sheet drag start callback */
471
  onDragStart?: (event: TaroEvent) => void;
472
  /** Sheet drag end callback */
473
  onDragEnd?: (event: DraggableSheetDragEndEvent) => void;
474
}
475

476
/**
477
 * Nested scroll header component
478
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
479
 */
480
const NestedScrollHeader: ComponentType<NestedScrollHeaderProps>;
481

482
interface NestedScrollHeaderProps extends StandardProps {
483
  /** Nested scroll body component
484
   * @supported weapp, tt, qq, jd (Skyline rendering engine)
485
   */
486
  nestedScrollBody?: any;
487
}
488

489
/**
490
 * Nested scroll body component
491
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
492
 */
493
const NestedScrollBody: ComponentType<NestedScrollBodyProps>;
494

495
interface NestedScrollBodyProps extends StandardProps {
496
  // Nested scroll body properties
497
}
498
```
499

500
### Advanced Interaction Components
501

502
Components for complex interactions, animations, and transitions.
503

504
```typescript { .api }
505
/**
506
 * Share element transition component
507
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
508
 */
509
const ShareElement: ComponentType<ShareElementProps>;
510

511
interface ShareElementProps extends StandardProps {
512
  /** Shared element key for transition
513
   * @supported weapp, tt, qq, jd
514
   */
515
  shareElementKey?: string;
516
  /** Transform type
517
   * @supported weapp, tt, qq, jd
518
   * @default "match"
519
   */
520
  transform?: 'match' | 'scaleOnShow' | 'scaleOnHide';
521
  /** Transition duration in milliseconds
522
   * @supported weapp, tt, qq, jd
523
   * @default 300
524
   */
525
  duration?: number;
526
  /** Easing function
527
   * @supported weapp, tt, qq, jd
528
   * @default "ease"
529
   */
530
  easingFunction?: string;
531
}
532

533
/**
534
 * Component snapshot capture
535
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
536
 */
537
const Snapshot: ComponentType<SnapshotProps>;
538

539
interface SnapshotProps extends StandardProps {
540
  /** Snapshot mode
541
   * @supported weapp, tt, qq, jd
542
   * @default "view"
543
   */
544
  mode?: 'view' | 'image';
545
  /** Snapshot quality
546
   * @supported weapp, tt, qq, jd
547
   * @default 1.0
548
   */
549
  quality?: number;
550
}
551

552
/**
553
 * Open container transition component
554
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
555
 */
556
const OpenContainer: ComponentType<OpenContainerProps>;
557

558
interface OpenContainerProps extends StandardProps {
559
  /** Container transition type
560
   * @supported weapp, tt, qq, jd
561
   * @default "fade"
562
   */
563
  transitionType?: 'fade' | 'fadeThrough' | 'sharedAxis';
564
  /** Transition duration in milliseconds
565
   * @supported weapp, tt, qq, jd
566
   * @default 300
567
   */
568
  transitionDuration?: number;
569
}
570

571
/**
572
 * Inline text span component
573
 * @supported weapp, tt, qq, jd (Skyline rendering engine)
574
 */
575
const Span: ComponentType<SpanProps>;
576

577
interface SpanProps extends StandardProps {
578
  // Inline span properties
579
}
580
```
581

582
## Types
583

584
```typescript { .api }
585
// Gesture event interfaces
586
interface GestureEvent extends TaroEvent {
587
  detail: {
588
    state: GestureHandlerState;
589
    x: number;
590
    y: number;
591
    absoluteX: number;
592
    absoluteY: number;
593
  };
594
}
595

596
interface GestureHandlerStateChangeEvent extends TaroEvent {
597
  detail: {
598
    handlerTag: string;
599
    state: GestureHandlerState;
600
    oldState: GestureHandlerState;
601
  };
602
}
603

604
interface PanGestureEvent extends GestureEvent {
605
  detail: GestureEvent['detail'] & {
606
    translationX: number;
607
    translationY: number;
608
    velocityX: number;
609
    velocityY: number;
610
  };
611
}
612

613
interface ScaleGestureEvent extends GestureEvent {
614
  detail: GestureEvent['detail'] & {
615
    scale: number;
616
    focalX: number;
617
    focalY: number;
618
    velocity: number;
619
  };
620
}
621

622
interface ForcePressGestureEvent extends GestureEvent {
623
  detail: GestureEvent['detail'] & {
624
    force: number;
625
  };
626
}
627

628
// Gesture handler states
629
enum GestureHandlerState {
630
  UNDETERMINED = 0,
631
  FAILED = 1,
632
  BEGAN = 2,
633
  CANCELLED = 3,
634
  ACTIVE = 4,
635
  END = 5,
636
}
637

638
// List and Grid event interfaces
639
interface ListViewScrollEvent extends TaroEvent {
640
  detail: {
641
    scrollLeft: number;
642
    scrollTop: number;
643
    scrollHeight: number;
644
    scrollWidth: number;
645
    deltaX: number;
646
    deltaY: number;
647
  };
648
}
649

650
interface GridViewScrollEvent extends TaroEvent {
651
  detail: {
652
    scrollLeft: number;
653
    scrollTop: number;
654
    scrollHeight: number;
655
    scrollWidth: number;
656
  };
657
}
658

659
// Draggable sheet event interfaces
660
interface DraggableSheetDragEndEvent extends TaroEvent {
661
  detail: {
662
    extent: number;
663
    velocity: number;
664
  };
665
}
666

667
// Layout and transition types
668
type ListViewType = 'list' | 'waterfall';
669
type ScrollDirection = 'vertical' | 'horizontal';
670
type ShareElementTransform = 'match' | 'scaleOnShow' | 'scaleOnHide';
671
type OpenContainerTransitionType = 'fade' | 'fadeThrough' | 'sharedAxis';
672
type SnapshotMode = 'view' | 'image';
673
```
674

675
**Usage Examples:**
676

677
```typescript
678
import { 
679
  TapGestureHandler, 
680
  PanGestureHandler, 
681
  ListView, 
682
  StickyHeader, 
683
  DraggableSheet 
684
} from "@tarojs/components";
685

686
// Gesture handling
687
<TapGestureHandler
688
  numberOfTaps={1}
689
  onHandlerStateChange={(e) => {
690
    if (e.detail.state === GestureHandlerState.ACTIVE) {
691
      console.log('Tapped!');
692
    }
693
  }}
694
>
695
  <View>Tap me</View>
696
</TapGestureHandler>
697

698
// High-performance list
699
<ListView
700
  type="list"
701
  scrollDirection="vertical"
702
  onScrollToLower={() => loadMoreData()}
703
>
704
  {/* List items */}
705
</ListView>
706

707
// Sticky header
708
<StickyHeader offsetY={0}>
709
  <View>This header will stick to top</View>
710
</StickyHeader>
711

712
// Draggable bottom sheet
713
<DraggableSheet
714
  initialChildSize={0.5}
715
  minChildSize={0.25}
716
  maxChildSize={1.0}
717
  onDragEnd={(e) => console.log('Sheet dragged to:', e.detail.extent)}
718
>
719
  <View>Sheet content</View>
720
</DraggableSheet>
721
```