@lynx-js/lynx-ui-scroll-view 3.130.0 → 3.132.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.tsx CHANGED
@@ -7,7 +7,7 @@ import type { ForwardedRef, ReactNode } from '@lynx-js/react'
7
7
 
8
8
  import '@lynx-js/gesture-runtime'
9
9
  import type { GestureKind } from '@lynx-js/gesture-runtime'
10
- import type { BounceableBasicProps, LazyOptions } from '@lynx-js/lynx-ui-common'
10
+ import type { LazyOptions } from '@lynx-js/lynx-ui-common'
11
11
  import {
12
12
  ExposureEventsMapping,
13
13
  LayoutEventsMapping,
@@ -24,12 +24,16 @@ import type {
24
24
  import ScrollViewBasic from './ScrollViewBasic'
25
25
  import ScrollViewWithBouncesHook from './ScrollViewWithBouncesHook'
26
26
  import type {
27
+ BounceableBasicProps,
27
28
  ScrollViewProps,
28
29
  ScrollViewRef,
29
30
  ScrollView as ScrollViewType,
30
31
  } from './types'
31
32
 
32
33
  export type { ScrollViewProps, ScrollViewRef }
34
+ export { useBounce } from './hooks/useBounce'
35
+ export type { bounceHandlers } from './hooks/useBounce'
36
+ export type { BounceableBasicProps } from './types'
33
37
 
34
38
  export const ScrollView = memo(forwardRef(ScrollViewImpl)) as ScrollViewType
35
39
 
@@ -70,6 +74,8 @@ function ScrollViewImpl(
70
74
  scrollOrientation,
71
75
  lazyOptions,
72
76
  className = '',
77
+ debugLog = false,
78
+ enableRTL = false,
73
79
  bounceableOptions = {
74
80
  enableBounces: true,
75
81
  singleSidedBounce: 'iOSBounces',
@@ -221,6 +227,8 @@ function ScrollViewImpl(
221
227
  <ScrollViewWithBouncesHook
222
228
  elementProps={elementProps}
223
229
  bounceableOptions={bounceableProps}
230
+ debugLog={debugLog}
231
+ enableRTL={enableRTL}
224
232
  sticky={sticky}
225
233
  >
226
234
  {renderChildren(children, normalizedLazyOptions)}
@@ -11,7 +11,6 @@ import type {
11
11
  BaseUIExposureProps,
12
12
  BaseUILayoutEvents,
13
13
  BaseUITouchEvents,
14
- BounceableBasicProps,
15
14
  ComponentBasicProps,
16
15
  LazyOptions,
17
16
  } from '@lynx-js/lynx-ui-common'
@@ -213,6 +212,24 @@ export interface ScrollViewProps
213
212
  * @iOS
214
213
  */
215
214
  bounceableOptions?: boolean | BounceableBasicProps
215
+ /**
216
+ * Whether horizontal bounce direction should be mirrored in RTL mode.
217
+ * @zh 是否在 RTL 模式下镜像水平回弹方向。
218
+ * @defaultValue false
219
+ * @Android
220
+ * @iOS
221
+ * @Harmony
222
+ */
223
+ enableRTL?: boolean
224
+ /**
225
+ * Display debug logs for bounce interactions.
226
+ * @zh 显示回弹交互的调试日志。
227
+ * @defaultValue false
228
+ * @Android
229
+ * @iOS
230
+ * @Harmony
231
+ */
232
+ debugLog?: boolean
216
233
  /**
217
234
  * Controls whether scroll events propagate to parent containers. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
218
235
  * @zh 控制滚动事件是否向父级容器传递。'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。
@@ -271,6 +288,119 @@ export interface ScrollViewProps
271
288
  }) => void
272
289
  }
273
290
 
291
+ export interface scrollToBouncesInfo {
292
+ direction: 'upper' | 'lower'
293
+ }
294
+
295
+ export interface BounceableBasicProps {
296
+ /**
297
+ * Whether to enable bounce effect
298
+ * @zh 是否开启回弹效果
299
+ * @iOS
300
+ * @Android
301
+ * @Harmony
302
+ */
303
+ enableBounces: boolean
304
+ /**
305
+ * Trigger bounces effect during fling
306
+ * @zh 在快速滑动(fling)时触发回弹效果
307
+ * @defaultValue false
308
+ * @iOS
309
+ * @Android
310
+ * @Harmony
311
+ */
312
+ enableBounceEventInFling?: boolean
313
+ /**
314
+ * The threshold distance of upper bounces, in pixels, when triggering the scrollToBounces event
315
+ * @zh 触发 `scrollToBounces` 事件时,上部回弹的阈值距离(单位:px)
316
+ * @defaultValue 0
317
+ * @iOS
318
+ * @Android
319
+ * @Harmony
320
+ */
321
+ startBounceTriggerDistance?: number
322
+ /**
323
+ * The threshold distance of lower bounces, in pixels, when triggering the scrollToBounces event
324
+ * @zh 触发 `scrollToBounces` 事件时,下部回弹的阈值距离(单位:px)
325
+ * @defaultValue 0
326
+ * @iOS
327
+ * @Android
328
+ * @Harmony
329
+ */
330
+ endBounceTriggerDistance?: number
331
+ /**
332
+ * Content of upper bounces view, which will be displayed during the upper bouncing effect.
333
+ * @zh 上部回弹视图的内容,将在上部回弹效果期间显示。
334
+ * @iOS
335
+ * @Android
336
+ * @Harmony
337
+ */
338
+ // biome-ignore lint/suspicious/noExplicitAny: expected
339
+ upperBounceItem?: any
340
+ /**
341
+ * Content of lower bounces view, which will be displayed during the lower bouncing effect.
342
+ * @zh 下部回弹视图的内容,将在下部回弹效果期间显示。
343
+ * @iOS
344
+ * @Android
345
+ * @Harmony
346
+ */
347
+ // biome-ignore lint/suspicious/noExplicitAny: expected
348
+ lowerBounceItem?: any
349
+ /**
350
+ * Whether the scrollable container can bounce when the content area of the scrollable container is smaller than the viewport area.
351
+ * @zh 当可滚动容器的内容区域小于视口区域时,是否允许容器回弹。
352
+ * @defaultValue true
353
+ * @iOS
354
+ * @Android
355
+ * @Harmony
356
+ */
357
+ alwaysBouncing?: boolean
358
+ /**
359
+ * The direction of the bounce effect. 'both' for bouncing on both ends, 'none' to disable bounce, and 'upper'/'lower' for bouncing on either end
360
+ * @zh 回弹效果的方向。'both' 表示两端都回弹,'none' 表示禁用回弹,'upper'/'lower' 表示只在上端或下端回弹。
361
+ * @defaultValue 'both'
362
+ * @iOS
363
+ * @Android
364
+ * @Harmony
365
+ */
366
+ singleSidedBounce?: 'upper' | 'lower' | 'both' | 'iOSBounces' | 'none'
367
+ /**
368
+ * Unit: px. Optional size hint for bounce effect. Recommended when used in List or <list/>.
369
+ * @zh 单位:px。可选的回弹效果尺寸提示。在列表或 `<list/>` 中使用时推荐设置。
370
+ * @Android
371
+ * @iOS
372
+ * @Harmony
373
+ */
374
+ estimatedHeight?: number
375
+ /**
376
+ * Unit: px. Optional size hint for bounce effect. Recommended when used in List or <list/>.
377
+ * @zh 单位:px。可选的回弹效果尺寸提示。在列表或 `<list/>` 中使用时推荐设置。
378
+ * @Android
379
+ * @iOS
380
+ * @Harmony
381
+ */
382
+ estimatedWidth?: number
383
+ /**
384
+ * requestAnimationFrame don't work under lynx version 2.15.2. This switch should be opened when the version is higher than 2.15.2.
385
+ * @zh `requestAnimationFrame` 在 lynx 2.15.2 以下版本中不起作用。当版本高于 2.15.2 时,应打开此开关。
386
+ * @defaultValue false
387
+ * @iOS
388
+ * @Android
389
+ * @Harmony
390
+ */
391
+ validAnimationVersion?: boolean
392
+ /**
393
+ * When bounces effect is triggered and the bounce distance is larger than startBounceDistance or endBounceDistance on the upper or lower side, the scrollToBounces event will be triggered.
394
+ * @zh 当触发回弹效果并且回弹距离在上侧或下侧大于 `startBounceDistance` 或 `endBounceDistance` 时,将触发 `scrollToBounces` 事件。
395
+ * @defaultValue 0
396
+ * @eventProperty
397
+ * @iOS
398
+ * @Android
399
+ * @Harmony
400
+ */
401
+ onScrollToBounces?: (e: scrollToBouncesInfo) => void
402
+ }
403
+
274
404
  export const ScrollEventMapping: Record<string, string> = {
275
405
  onContentSizeChange: 'bindcontentsizechange',
276
406
  }