0
# View Containers
1

2
Foundation layout and container components for structuring application UI, including basic views, scrollable containers, and overlay components.
3

4
## Capabilities
5

6
### View
7

8
Basic view container component that serves as the fundamental building block for layout structures.
9

10
```typescript { .api }
11
/**
12
 * Basic view container component
13
 * @supported all platforms
14
 */
15
const View: ComponentType<ViewProps>;
16

17
interface ViewProps extends StandardProps {
18
  /** Whether to enable flexible layout
19
   * @supported weapp, alipay, swan, tt, qq, jd, h5
20
   * @default false
21
   */
22
  enableFlex?: boolean;
23
  /** Hover class name applied when the view is pressed
24
   * @supported weapp, alipay, swan, tt, qq, jd
25
   */
26
  hoverClass?: string;
27
  /** Time delay in milliseconds before hover class is applied
28
   * @supported weapp, alipay, swan, tt, qq, jd
29
   * @default 50
30
   */
31
  hoverStartTime?: number;
32
  /** Time delay in milliseconds before hover class is removed
33
   * @supported weapp, alipay, swan, tt, qq, jd
34
   * @default 400
35
   */
36
  hoverStayTime?: number;
37
  /** Whether hover effect is disabled
38
   * @supported weapp, alipay, swan, tt, qq, jd
39
   * @default false
40
   */
41
  hoverStopPropagation?: boolean;
42
}
43
```
44

45
### ScrollView
46

47
Scrollable view container with pull-to-refresh functionality and scroll event handling.
48

49
```typescript { .api }
50
/**
51
 * Scrollable view container
52
 * @supported all platforms
53
 */
54
const ScrollView: ComponentType<ScrollViewProps>;
55

56
interface ScrollViewProps extends StandardProps {
57
  /** Allow horizontal scrolling
58
   * @default false
59
   */
60
  scrollX?: boolean;
61
  /** Allow vertical scrolling
62
   * @default false
63
   */
64
  scrollY?: boolean;
65
  /** Distance from top edge to trigger upper pull refresh
66
   * @default 50
67
   */
68
  upperThreshold?: number;
69
  /** Distance from bottom edge to trigger lower pull refresh
70
   * @default 50
71
   */
72
  lowerThreshold?: number;
73
  /** Top scroll position
74
   * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
75
   */
76
  scrollTop?: number;
77
  /** Left scroll position
78
   * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
79
   */
80
  scrollLeft?: number;
81
  /** Child element ID to scroll into view
82
   * @supported weapp, alipay, swan, tt, qq, jd, h5
83
   */
84
  scrollIntoView?: string;
85
  /** Enable scrolling with animation
86
   * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
87
   * @default false
88
   */
89
  scrollWithAnimation?: boolean;
90
  /** Enable bounce effect on iOS
91
   * @supported weapp, tt, qq, jd, h5
92
   * @default true
93
   */
94
  enableBackToTop?: boolean;
95
  /** Enable pull-down refresh
96
   * @supported weapp, tt, qq, jd
97
   * @default false
98
   */
99
  enablePullDownRefresh?: boolean;
100
  /** Background color for pull-down refresh
101
   * @supported weapp, tt, qq, jd
102
   * @default "#FFF"
103
   */
104
  refresherBackground?: string;
105
  /** Whether refresh indicator is triggered
106
   * @supported weapp, tt, qq, jd
107
   * @default false
108
   */
109
  refresherTriggered?: boolean;
110
  /** Threshold distance to trigger refresh
111
   * @supported weapp, tt, qq, jd
112
   * @default 45
113
   */
114
  refresherThreshold?: number;
115
  /** Maximum pull-down distance
116
   * @supported weapp, tt, qq, jd
117
   * @default 100
118
   */
119
  refresherMaxDragDistance?: number;
120
  /** Default refresh indicator style
121
   * @supported weapp, tt, qq, jd
122
   * @default "black"
123
   */
124
  refresherDefaultStyle?: string;
125
  /** Scroll event callback */
126
  onScroll?: (event: ScrollViewScrollEvent) => void;
127
  /** Upper threshold reached callback */
128
  onScrollToUpper?: (event: TaroEvent) => void;
129
  /** Lower threshold reached callback */
130
  onScrollToLower?: (event: TaroEvent) => void;
131
  /** Pull-down refresh triggered callback */
132
  onRefresherPulling?: (event: TaroEvent) => void;
133
  /** Refresh state change callback */
134
  onRefresherRefresh?: (event: TaroEvent) => void;
135
  /** Refresh restoration callback */
136
  onRefresherRestore?: (event: TaroEvent) => void;
137
  /** Pull-down refresh abort callback */
138
  onRefresherAbort?: (event: TaroEvent) => void;
139
}
140
```
141

142
### Block
143

144
Basic block container component for grouping elements without styling.
145

146
```typescript { .api }
147
/**
148
 * Basic block container component
149
 * @supported all platforms
150
 */
151
const Block: ComponentType<BlockProps>;
152

153
interface BlockProps extends StandardProps {
154
  // No specific props beyond StandardProps
155
}
156
```
157

158
### Swiper and SwiperItem
159

160
Swiper container for creating slide presentations and carousels.
161

162
```typescript { .api }
163
/**
164
 * Swiper container for slides
165
 * @supported all platforms
166
 */
167
const Swiper: ComponentType<SwiperProps>;
168

169
interface SwiperProps extends StandardProps {
170
  /** Whether dots indicator is shown
171
   * @default false
172
   */
173
  indicatorDots?: boolean;
174
  /** Active dot color
175
   * @default "rgba(0, 0, 0, .3)"
176
   */
177
  indicatorColor?: string;
178
  /** Active dot color
179
   * @default "#000000"
180
   */
181
  indicatorActiveColor?: string;
182
  /** Whether auto play is enabled
183
   * @default false
184
   */
185
  autoplay?: boolean;
186
  /** Current slide index
187
   * @default 0
188
   */
189
  current?: number;
190
  /** Auto play interval in milliseconds
191
   * @default 5000
192
   */
193
  interval?: number;
194
  /** Animation duration in milliseconds
195
   * @default 500
196
   */
197
  duration?: number;
198
  /** Whether circular swiping is enabled
199
   * @default false
200
   */
201
  circular?: boolean;
202
  /** Whether vertical swiping is enabled
203
   * @default false
204
   */
205
  vertical?: boolean;
206
  /** Previous margin for showing previous slide
207
   * @supported weapp, alipay, swan, tt, qq, jd, h5
208
   * @default "0px"
209
   */
210
  previousMargin?: string;
211
  /** Next margin for showing next slide
212
   * @supported weapp, alipay, swan, tt, qq, jd, h5
213
   * @default "0px"
214
   */
215
  nextMargin?: string;
216
  /** Zoom multiple for pinch zoom
217
   * @supported weapp, alipay, swan, tt, qq, jd
218
   * @default 1
219
   */
220
  displayMultipleItems?: number;
221
  /** Animation change callback */
222
  onChange?: (event: SwiperChangeEvent) => void;
223
  /** Transition callback */
224
  onTransition?: (event: SwiperTransitionEvent) => void;
225
  /** Animation end callback */
226
  onAnimationFinish?: (event: SwiperAnimationFinishEvent) => void;
227
}
228

229
/**
230
 * Individual slide item for Swiper
231
 * @supported all platforms
232
 */
233
const SwiperItem: ComponentType<SwiperItemProps>;
234

235
interface SwiperItemProps extends StandardProps {
236
  /** Unique identifier for the slide item
237
   * @supported weapp, alipay, swan, tt, qq, jd, h5
238
   */
239
  itemId?: string;
240
}
241
```
242

243
### MovableArea and MovableView
244

245
Components for creating draggable and movable elements within defined areas.
246

247
```typescript { .api }
248
/**
249
 * Movable area container for draggable content
250
 * @supported weapp, alipay, swan, tt, qq, jd, h5
251
 */
252
const MovableArea: ComponentType<MovableAreaProps>;
253

254
interface MovableAreaProps extends StandardProps {
255
  /** Scale ratio
256
   * @supported weapp, alipay, swan, tt, qq, jd, h5
257
   * @default false
258
   */
259
  scaleArea?: boolean;
260
}
261

262
/**
263
 * Draggable view component within MovableArea
264
 * @supported weapp, alipay, swan, tt, qq, jd, h5
265
 */
266
const MovableView: ComponentType<MovableViewProps>;
267

268
interface MovableViewProps extends StandardProps {
269
  /** Movement direction
270
   * @default "none"
271
   */
272
  direction?: 'all' | 'vertical' | 'horizontal' | 'none';
273
  /** Whether element is inert (not draggable)
274
   * @default false
275
   */
276
  inertia?: boolean;
277
  /** Distance threshold for smooth transition
278
   * @default 0
279
   */
280
  outOfBounds?: boolean;
281
  /** X-coordinate position
282
   * @supported weapp, alipay, swan, tt, qq, jd, h5
283
   */
284
  x?: number;
285
  /** Y-coordinate position
286
   * @supported weapp, alipay, swan, tt, qq, jd, h5
287
   */
288
  y?: number;
289
  /** Whether damping is enabled
290
   * @supported weapp, alipay, swan, tt, qq, jd, h5
291
   * @default false
292
   */
293
  damping?: number;
294
  /** Friction coefficient
295
   * @supported weapp, alipay, swan, tt, qq, jd, h5
296
   * @default 2
297
   */
298
  friction?: number;
299
  /** Whether scaling is disabled
300
   * @supported weapp, alipay, swan, tt, qq, jd, h5
301
   * @default false
302
   */
303
  disabled?: boolean;
304
  /** Scale value
305
   * @supported weapp, alipay, swan, tt, qq, jd, h5
306
   * @default 1
307
   */
308
  scale?: number;
309
  /** Minimum scale value
310
   * @supported weapp, alipay, swan, tt, qq, jd, h5
311
   * @default 0.5
312
   */
313
  scaleMin?: number;
314
  /** Maximum scale value
315
   * @supported weapp, alipay, swan, tt, qq, jd, h5
316
   * @default 10
317
   */
318
  scaleMax?: number;
319
  /** Scale value for double tap
320
   * @supported weapp, alipay, swan, tt, qq, jd, h5
321
   * @default 1
322
   */
323
  scaleValue?: number;
324
  /** Animation flag
325
   * @supported weapp, alipay, swan, tt, qq, jd, h5
326
   * @default false
327
   */
328
  animation?: boolean;
329
  /** Position change callback */
330
  onChange?: (event: MovableViewChangeEvent) => void;
331
  /** Scale change callback */
332
  onScale?: (event: MovableViewScaleEvent) => void;
333
}
334
```
335

336
### Cover Components
337

338
Overlay components for displaying content above native components.
339

340
```typescript { .api }
341
/**
342
 * Cover view component for overlaying native components
343
 * @supported weapp, alipay, swan, tt, qq, jd
344
 */
345
const CoverView: ComponentType<CoverViewProps>;
346

347
interface CoverViewProps extends StandardProps {
348
  /** Scroll position when using scroll-view
349
   * @supported weapp, alipay, swan, tt, qq, jd
350
   */
351
  scrollTop?: number;
352
}
353

354
/**
355
 * Cover image component for overlaying content
356
 * @supported weapp, alipay, swan, tt, qq, jd
357
 */
358
const CoverImage: ComponentType<CoverImageProps>;
359

360
interface CoverImageProps extends StandardProps {
361
  /** Image source URL
362
   * @supported weapp, alipay, swan, tt, qq, jd
363
   */
364
  src?: string;
365
  /** Image load callback */
366
  onLoad?: (event: CoverImageLoadEvent) => void;
367
  /** Image error callback */
368
  onError?: (event: CoverImageErrorEvent) => void;
369
}
370
```
371

372
### Specialty Containers
373

374
Additional container components for specific use cases.
375

376
```typescript { .api }
377
/**
378
 * Page container wrapper component
379
 * @supported weapp, tt, qq, jd
380
 */
381
const PageContainer: ComponentType<PageContainerProps>;
382

383
interface PageContainerProps extends StandardProps {
384
  /** Whether container is shown
385
   * @default false
386
   */
387
  show?: boolean;
388
  /** Container duration in milliseconds
389
   * @default 300
390
   */
391
  duration?: number;
392
  /** Z-index value
393
   * @default 100
394
   */
395
  zIndex?: number;
396
  /** Overlay mask
397
   * @default true
398
   */
399
  overlay?: boolean;
400
  /** Container position
401
   * @default "bottom"
402
   */
403
  position?: 'top' | 'bottom' | 'right' | 'center';
404
  /** Round corner radius
405
   * @default 0
406
   */
407
  round?: number;
408
  /** Close on overlay click
409
   * @default false
410
   */
411
  closeOnOverlayClick?: boolean;
412
  /** Container enter callback */
413
  onEnter?: (event: TaroEvent) => void;
414
  /** Container after enter callback */
415
  onAfterEnter?: (event: TaroEvent) => void;
416
  /** Container leave callback */
417
  onLeave?: (event: TaroEvent) => void;
418
  /** Container after leave callback */
419
  onAfterLeave?: (event: TaroEvent) => void;
420
  /** Click overlay callback */
421
  onClickOverlay?: (event: TaroEvent) => void;
422
}
423

424
/**
425
 * Portal component for rendering outside component tree
426
 * @supported weapp, tt, qq, jd
427
 */
428
const RootPortal: ComponentType<RootPortalProps>;
429

430
interface RootPortalProps extends StandardProps {
431
  /** Whether portal is enabled
432
   * @default true
433
   */
434
  enable?: boolean;
435
}
436

437
/**
438
 * Media query matching component
439
 * @supported weapp, alipay, swan, tt, qq, jd, h5
440
 */
441
const MatchMedia: ComponentType<MatchMediaProps>;
442

443
interface MatchMediaProps extends StandardProps {
444
  /** Minimum width for media query
445
   * @supported weapp, alipay, swan, tt, qq, jd, h5
446
   */
447
  minWidth?: number;
448
  /** Maximum width for media query
449
   * @supported weapp, alipay, swan, tt, qq, jd, h5
450
   */
451
  maxWidth?: number;
452
  /** Width for media query
453
   * @supported weapp, alipay, swan, tt, qq, jd, h5
454
   */
455
  width?: number;
456
  /** Minimum height for media query
457
   * @supported weapp, alipay, swan, tt, qq, jd, h5
458
   */
459
  minHeight?: number;
460
  /** Maximum height for media query
461
   * @supported weapp, alipay, swan, tt, qq, jd, h5
462
   */
463
  maxHeight?: number;
464
  /** Height for media query
465
   * @supported weapp, alipay, swan, tt, qq, jd, h5
466
   */
467
  height?: number;
468
  /** Orientation for media query
469
   * @supported weapp, alipay, swan, tt, qq, jd, h5
470
   */
471
  orientation?: 'landscape' | 'portrait';
472
}
473

474
/**
475
 * Animated view container
476
 * @supported weapp, tt, qq, jd
477
 */
478
const AnimationView: ComponentType<AnimationViewProps>;
479

480
interface AnimationViewProps extends StandardProps {
481
  // Animation-specific props would be defined based on platform capabilities
482
}
483
```
484

485
## Types
486

487
```typescript { .api }
488
// Event interfaces for ScrollView
489
interface ScrollViewScrollEvent extends TaroEvent {
490
  detail: {
491
    scrollLeft: number;
492
    scrollTop: number;
493
    scrollHeight: number;
494
    scrollWidth: number;
495
    deltaX: number;
496
    deltaY: number;
497
  };
498
}
499

500
// Event interfaces for Swiper
501
interface SwiperChangeEvent extends TaroEvent {
502
  detail: {
503
    current: number;
504
    source: 'autoplay' | 'touch' | '';
505
  };
506
}
507

508
interface SwiperTransitionEvent extends TaroEvent {
509
  detail: {
510
    dx: number;
511
    dy: number;
512
  };
513
}
514

515
interface SwiperAnimationFinishEvent extends TaroEvent {
516
  detail: {
517
    current: number;
518
    source: 'autoplay' | 'touch' | '';
519
  };
520
}
521

522
// Event interfaces for MovableView
523
interface MovableViewChangeEvent extends TaroEvent {
524
  detail: {
525
    x: number;
526
    y: number;
527
    source: 'touch' | 'touch-out-of-bounds' | 'out-of-bounds' | 'friction' | '';
528
  };
529
}
530

531
interface MovableViewScaleEvent extends TaroEvent {
532
  detail: {
533
    x: number;
534
    y: number;
535
    scale: number;
536
  };
537
}
538

539
// Event interfaces for Cover components
540
interface CoverImageLoadEvent extends TaroEvent {
541
  detail: {
542
    // Load event details
543
  };
544
}
545

546
interface CoverImageErrorEvent extends TaroEvent {
547
  detail: {
548
    errMsg: string;
549
  };
550
}
551
```