1 | import { ComponentType } from 'react'
|
2 | import { StandardProps, CommonEventFunction, BaseEventOrigFunction } from './common'
|
3 | interface ScrollViewProps extends StandardProps {
|
4 | /** 允许横向滚动
|
5 | * @default false
|
6 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
7 | * @rn 二选一
|
8 | */
|
9 | scrollX?: boolean
|
10 | /** 允许纵向滚动
|
11 | * @default false
|
12 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
13 | * @rn 二选一
|
14 | */
|
15 | scrollY?: boolean
|
16 | /** 距顶部/左边多远时(单位px),触发 scrolltoupper 事件
|
17 | * @default 50
|
18 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
19 | */
|
20 | upperThreshold?: number
|
21 | /** 距底部/右边多远时(单位px),触发 scrolltolower 事件
|
22 | * @default 50
|
23 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
24 | */
|
25 | lowerThreshold?: number
|
26 | /** 设置竖向滚动条位置
|
27 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
28 | */
|
29 | scrollTop?: number
|
30 | /** 设置横向滚动条位置
|
31 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
32 | */
|
33 | scrollLeft?: number
|
34 | /** 值应为某子元素id(id不能以数字开头)。设置哪个方向可滚动,则在哪个方向滚动到该元素
|
35 | * @supported weapp, alipay, swan, tt, qq, jd, h5
|
36 | */
|
37 | scrollIntoView?: string
|
38 | /** 在设置滚动条位置时使用动画过渡
|
39 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
40 | * @default false
|
41 | */
|
42 | scrollWithAnimation?: boolean
|
43 | /** iOS 点击顶部状态栏、安卓双击标题栏时,滚动条返回顶部,只支持竖向
|
44 | * @supported weapp, alipay, swan, qq, jd, rn
|
45 | * @default false
|
46 | */
|
47 | enableBackToTop?: boolean
|
48 | /** 启用 flexbox 布局。开启后,当前节点声明了 `display: flex` 就会成为 flex container,并作用于其孩子节点。
|
49 | * @supported weapp
|
50 | * @default false
|
51 | */
|
52 | enableFlex?: boolean
|
53 | /** 开启 scroll anchoring 特性,即控制滚动位置不随内容变化而抖动,仅在 iOS 下生效,安卓下可参考 CSS `overflow-anchor` 属性。
|
54 | * @supported weapp
|
55 | * @default false
|
56 | */
|
57 | scrollAnchoring?: boolean
|
58 | /** 开启自定义下拉刷新
|
59 | * @supported weapp
|
60 | * @default false
|
61 | */
|
62 | refresherEnabled?: boolean
|
63 | /** 设置自定义下拉刷新阈值
|
64 | * @supported weapp
|
65 | * @default 45
|
66 | */
|
67 | refresherThreshold?: number
|
68 | /** 设置自定义下拉刷新默认样式,支持设置 `black | white | none`, none 表示不使用默认样式
|
69 | * @supported weapp
|
70 | * @default 'black'
|
71 | */
|
72 | refresherDefaultStyle?: string
|
73 | /** 设置自定义下拉刷新区域背景颜色
|
74 | * @supported weapp
|
75 | * @default '#FFF'
|
76 | */
|
77 | refresherBackground?: string
|
78 | /** 设置当前下拉刷新状态,true 表示下拉刷新已经被触发,false 表示下拉刷新未被触发
|
79 | * @supported weapp
|
80 | * @default false
|
81 | */
|
82 | refresherTriggered?: boolean
|
83 | /** 启用 scroll-view 增强特性
|
84 | * @supported weapp
|
85 | * @default false
|
86 | */
|
87 | enhanced?: boolean
|
88 | /** iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效)
|
89 | * @supported weapp
|
90 | * @default true
|
91 | */
|
92 | bounces?: boolean
|
93 | /** 滚动条显隐控制 (同时开启 enhanced 属性后生效)
|
94 | * @supported weapp
|
95 | * @default true
|
96 | */
|
97 | showScrollbar?: boolean
|
98 | /** 分页滑动效果 (同时开启 enhanced 属性后生效)
|
99 | * @supported weapp
|
100 | * @default false
|
101 | */
|
102 | pagingEnabled?: boolean
|
103 | /** boolean false 滑动减速速率控制 (同时开启 enhanced 属性后生效)
|
104 | * @supported weapp
|
105 | * @default false
|
106 | */
|
107 | fastDeceleration?: boolean
|
108 | /** 当 scroll-with-animation设置为 true 时,可以设置 scroll-animation-duration 来控制动画的执行时间,单位 ms。
|
109 | * @supported alipay
|
110 | */
|
111 | scrollAnimationDuration?: string
|
112 | /** 纵向滚动时,当滚动到顶部或底部时,强制禁止触发页面滚动,仍然只触发 scroll-view 自身的滚动。
|
113 | * @supported alipay
|
114 | * @default false
|
115 | */
|
116 | trapScroll?: string
|
117 | /** 发生滚动前,对滚动方向进行判断,当方向是顶部/左边时,如果值为 always 将始终禁止滚动,如果值为 out-of-bounds 且当前已经滚动到顶部/左边,禁止滚动。
|
118 | * @supported alipay
|
119 | */
|
120 | disableLowerScroll?: string
|
121 | /** 发生滚动前,对滚动方向进行判断,当方向是底部/右边时,如果值为 always 将始终禁止滚动,如果值为 out-of-bounds 且当前已经滚动到底部/右边,禁止滚动。
|
122 | * @supported alipay
|
123 | */
|
124 | disableUpperScroll?: string
|
125 | /** 无障碍访问,(属性)元素的额外描述
|
126 | * @supported qq
|
127 | */
|
128 | ariaLabel?: string
|
129 | /** 开启 passive 特性,能优化一定的滚动性能
|
130 | * @supported weapp
|
131 | * @default false
|
132 | */
|
133 | enablePassive?: string
|
134 | /** 渲染模式
|
135 | * list - 列表模式。只会渲染在屏节点,会根据直接子节点是否在屏来按需渲染,若只有一个直接子节点则性能会退化
|
136 | * custom - 自定义模式。只会渲染在屏节点,子节点可以是 sticky-section list-view grid-view 等组件
|
137 | * @supported weapp
|
138 | * @default 'list'
|
139 | */
|
140 | type?: 'list' | 'custom'
|
141 | /** 是否反向滚动。一般初始滚动位置是在顶部,反向滚动则是在底部。
|
142 | * @supported weapp
|
143 | * @default false
|
144 | */
|
145 | reverse?: boolean
|
146 | /** 指定视口外渲染区域的距离,默认情况下视口外节点不渲染。指定 cache-extent 可优化滚动体验和加载速度,但会提高内存占用且影响首屏速度,可按需启用。
|
147 | * @supported weapp
|
148 | */
|
149 | cacheExtent?: number
|
150 | /** 只 scroll-into-view 到 cacheExtent 以内的目标节点,性能更佳
|
151 | * @supported weapp
|
152 | * @default false
|
153 | */
|
154 | scrollIntoViewWithinExtent?: boolean
|
155 | /** 指定 scroll-into-view 目标节点在视口内的位置。
|
156 | * start - 目标节点显示在视口开始处
|
157 | * center - 目标节点显示在视口中间
|
158 | * end - 目标节点显示在视口结束处
|
159 | * nearest - 目标节点在就近的视口边缘显示,若节点已在视口内则不触发滚动
|
160 | * @supported weapp
|
161 | * @default 'start'
|
162 | */
|
163 | scrollIntoViewAlignment?: 'start' | 'center' | 'end' | 'nearest'
|
164 | /** 滚动到顶部/左边,会触发 scrolltoupper 事件
|
165 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
166 | */
|
167 | onScrollToUpper?: CommonEventFunction
|
168 | /** 滚动到底部/右边,会触发 scrolltolower 事件
|
169 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
170 | */
|
171 | onScrollToLower?: CommonEventFunction
|
172 | /** 滚动时触发
|
173 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn
|
174 | */
|
175 | onScroll?: BaseEventOrigFunction<ScrollViewProps.onScrollDetail>
|
176 | /** 滚动开始事件
|
177 | * @supported weapp
|
178 | */
|
179 | onScrollStart?: BaseEventOrigFunction<ScrollViewProps.onScrollDetail>
|
180 | /** 滚动结束事件
|
181 | * @supported weapp
|
182 | */
|
183 | onScrollEnd?: BaseEventOrigFunction<ScrollViewProps.onScrollDetail>
|
184 | /** 自定义下拉刷新控件被下拉
|
185 | * @supported weapp
|
186 | */
|
187 | onRefresherPulling?: CommonEventFunction
|
188 | /** 自定义下拉刷新被触发
|
189 | * @supported weapp
|
190 | */
|
191 | onRefresherRefresh?: CommonEventFunction
|
192 | /** 自定义下拉刷新被复位
|
193 | * @supported weapp
|
194 | */
|
195 | onRefresherRestore?: CommonEventFunction
|
196 | /** 自定义下拉刷新被中止
|
197 | * @supported weapp
|
198 | */
|
199 | onRefresherAbort?: CommonEventFunction
|
200 | /** 自定义下拉刷新即将触发刷新(拖动超过 refresher-threshold 时)的事件
|
201 | * @supported weapp
|
202 | */
|
203 | onRefresherWillRefresh?: CommonEventFunction
|
204 | /** 滑动开始事件 (同时开启 enhanced 属性后生效)
|
205 | * @supported weapp
|
206 | */
|
207 | onDragStart?: CommonEventFunction<ScrollViewProps.onDragDetail>
|
208 | /** 滑动事件 (同时开启 enhanced 属性后生效)
|
209 | * @supported weapp
|
210 | */
|
211 | onDragging?: CommonEventFunction<ScrollViewProps.onDragDetail>
|
212 | /** 滑动结束事件 (同时开启 enhanced 属性后生效)
|
213 | * @supported weapp
|
214 | */
|
215 | onDragEnd?: CommonEventFunction<ScrollViewProps.onDragDetail>
|
216 | /** 触摸动作开始。
|
217 | * @supported alipay
|
218 | */
|
219 | onTouchStart?: CommonEventFunction
|
220 | /** 触摸后移动。
|
221 | * @supported alipay
|
222 | */
|
223 | onTouchMove?: CommonEventFunction
|
224 | /** 触摸动作结束。
|
225 | * @supported alipay
|
226 | */
|
227 | onTouchEnd?: CommonEventFunction
|
228 | /** 触摸动作被打断,如来电提醒、弹窗。
|
229 | * @supported alipay
|
230 | */
|
231 | onTouchCancel?: CommonEventFunction
|
232 | }
|
233 | declare namespace ScrollViewProps {
|
234 | interface onScrollDetail {
|
235 | /** 横向滚动条位置 */
|
236 | scrollLeft: number
|
237 | /** 竖向滚动条位置 */
|
238 | scrollTop: number
|
239 | /** 滚动条高度 */
|
240 | scrollHeight: number
|
241 | /** 滚动条宽度 */
|
242 | scrollWidth: number
|
243 | deltaX: number
|
244 | deltaY: number
|
245 | isDrag?: boolean
|
246 | }
|
247 | interface onDragDetail {
|
248 | /** 横向滚动条位置 */
|
249 | scrollLeft: number
|
250 | /** 竖向滚动条位置 */
|
251 | scrollTop: number
|
252 | /** 滚动速度 */
|
253 | velocity: number
|
254 | }
|
255 | }
|
256 | /** 可滚动视图区域。使用竖向滚动时,需要给scroll-view一个固定高度,通过 WXSS 设置 height。组件属性的长度单位默认为 px
|
257 | *
|
258 | * Tips:
|
259 | * H5 中 ScrollView 组件是通过一个高度(或宽度)固定的容器内部滚动来实现的,因此务必正确的设置容器的高度。例如: 如果 ScrollView 的高度将 body 撑开,就会同时存在两个滚动条(body 下的滚动条,以及 ScrollView 的滚动条)。
|
260 | * 微信小程序 中 ScrollView 组件如果设置 scrollX 横向滚动时,并且子元素为多个时(单个子元素时设置固定宽度则可以正常横向滚动),需要通过 WXSS 设置 `white-space: nowrap` 来保证元素不换行,并对 ScrollView 内部元素设置 `display: inline-block` 来使其能够横向滚动。
|
261 | * @classification viewContainer
|
262 | * @supported weapp, alipay, swan, tt, qq, jd, h5, rn, harmony
|
263 | * @example_react
|
264 | * ```tsx
|
265 | * export default class PageView extends Component {
|
266 | * constructor() {
|
267 | * super(...arguments)
|
268 | * }
|
269 | *
|
270 | * onScrollToUpper() {}
|
271 | *
|
272 | * // or 使用箭头函数
|
273 | * // onScrollToUpper = () => {}
|
274 | *
|
275 | * onScroll(e){
|
276 | * console.log(e.detail)
|
277 | * }
|
278 | *
|
279 | * render() {
|
280 | * const scrollStyle = {
|
281 | * height: '150px'
|
282 | * }
|
283 | * const scrollTop = 0
|
284 | * const Threshold = 20
|
285 | * const vStyleA = {
|
286 | * height: '150px',
|
287 | * 'backgroundColor': 'rgb(26, 173, 25)'
|
288 | * }
|
289 | * const vStyleB = {
|
290 | * height: '150px',
|
291 | * 'backgroundColor': 'rgb(39,130,215)'
|
292 | * }
|
293 | * const vStyleC = {
|
294 | * height: '150px',
|
295 | * 'backgroundColor': 'rgb(241,241,241)',
|
296 | * color: '#333'
|
297 | * }
|
298 | * return (
|
299 | * <ScrollView
|
300 | * className='scrollview'
|
301 | * scrollY
|
302 | * scrollWithAnimation
|
303 | * scrollTop={scrollTop}
|
304 | * style={scrollStyle}
|
305 | * lowerThreshold={Threshold}
|
306 | * upperThreshold={Threshold}
|
307 | * onScrollToUpper={this.onScrollToUpper.bind(this)} // 使用箭头函数的时候 可以这样写 `onScrollToUpper={this.onScrollToUpper}`
|
308 | * onScroll={this.onScroll}
|
309 | * >
|
310 | * <View style={vStyleA}>A</View>
|
311 | * <View style={vStyleB}>B</View>
|
312 | * <View style={vStyleC}>C</View>
|
313 | * </ScrollView>
|
314 | * )
|
315 | * }
|
316 | * }
|
317 | * ```
|
318 | * @example_vue
|
319 | * ```html
|
320 | * <template>
|
321 | * <view class="container">
|
322 | * <view class="page-body">
|
323 | * <view class="page-section">
|
324 | * <view class="page-section-title">
|
325 | * <text>Vertical Scroll - 纵向滚动</text>
|
326 | * </view>
|
327 | * <view class="page-section-spacing">
|
328 | * <scroll-view :scroll-y="true" style="height: 300rpx;" `@scrolltoupper="upper" `@scrolltolower="lower" `@scroll="scroll" :scroll-into-view="toView" :scroll-top="scrollTop">
|
329 | * <view id="demo1" class="scroll-view-item demo-text-1">1</view>
|
330 | * <view id="demo2" class="scroll-view-item demo-text-2">2</view>
|
331 | * <view id="demo3" class="scroll-view-item demo-text-3">3</view>
|
332 | * </scroll-view>
|
333 | * </view>
|
334 | * </view>
|
335 | * <view class="page-section">
|
336 | * <view class="page-section-title">
|
337 | * <text>Horizontal Scroll - 横向滚动</text>
|
338 | * </view>
|
339 | * <view class="page-section-spacing">
|
340 | * <scroll-view class="scroll-view_H" :scroll-x="true" `@scroll="scroll" style="width: 100%">
|
341 | * <view id="demo21" class="scroll-view-item_H demo-text-1">a</view>
|
342 | * <view id="demo22" class="scroll-view-item_H demo-text-2">b</view>
|
343 | * <view id="demo23" class="scroll-view-item_H demo-text-3">c</view>
|
344 | * </scroll-view>
|
345 | * </view>
|
346 | * </view>
|
347 | * </view>
|
348 | * </view>
|
349 | * </template>
|
350 | *
|
351 | * <script>
|
352 | * const order = ['demo1', 'demo2', 'demo3']
|
353 | * export default {
|
354 | * name: 'Index',
|
355 | * data() {
|
356 | * return {
|
357 | * scrollTop: 0,
|
358 | * toView: 'demo2'
|
359 | * }
|
360 | * },
|
361 | *
|
362 | * methods: {
|
363 | * upper(e) {
|
364 | * console.log('upper:', e)
|
365 | * },
|
366 | *
|
367 | * lower(e) {
|
368 | * console.log('lower:', e)
|
369 | * },
|
370 | *
|
371 | * scroll(e) {
|
372 | * console.log('scroll:', e)
|
373 | * }
|
374 | * }
|
375 | * }
|
376 | * </script>
|
377 | *
|
378 | * <style>
|
379 | * .page-section-spacing{
|
380 | * margin-top: 60rpx;
|
381 | * }
|
382 | * .scroll-view_H{
|
383 | * white-space: nowrap;
|
384 | * }
|
385 | * .scroll-view-item{
|
386 | * height: 300rpx;
|
387 | * }
|
388 | * .scroll-view-item_H{
|
389 | * display: inline-block;
|
390 | * width: 100%;
|
391 | * height: 300rpx;
|
392 | * }
|
393 | *
|
394 | * .demo-text-1 { background: #ccc; }
|
395 | * .demo-text-2 { background: #999; }
|
396 | * .demo-text-3 { background: #666; }
|
397 | * </style>
|
398 | * ```
|
399 | * @see https://developers.weixin.qq.com/miniprogram/dev/component/scroll-view.html
|
400 | */
|
401 | declare const ScrollView: ComponentType<ScrollViewProps>
|
402 | export { ScrollView, ScrollViewProps }
|