@lynx-js/lynx-ui-scroll-view 0.0.0 → 3.130.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 ADDED
@@ -0,0 +1,236 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ import { forwardRef, memo, useRef } from '@lynx-js/react'
6
+ import type { ForwardedRef, ReactNode } from '@lynx-js/react'
7
+
8
+ import '@lynx-js/gesture-runtime'
9
+ import type { GestureKind } from '@lynx-js/gesture-runtime'
10
+ import type { BounceableBasicProps, LazyOptions } from '@lynx-js/lynx-ui-common'
11
+ import {
12
+ ExposureEventsMapping,
13
+ LayoutEventsMapping,
14
+ ScrollEventsMapping,
15
+ TouchEventsMapping,
16
+ useRegisteredEvents,
17
+ } from '@lynx-js/lynx-ui-common'
18
+ import { LazyComponent } from '@lynx-js/lynx-ui-lazy-component'
19
+ import type {
20
+ CSSProperties,
21
+ ScrollViewProps as ScrollViewElementProps,
22
+ } from '@lynx-js/types'
23
+
24
+ import ScrollViewBasic from './ScrollViewBasic'
25
+ import ScrollViewWithBouncesHook from './ScrollViewWithBouncesHook'
26
+ import type {
27
+ ScrollViewProps,
28
+ ScrollViewRef,
29
+ ScrollView as ScrollViewType,
30
+ } from './types'
31
+
32
+ export type { ScrollViewProps, ScrollViewRef }
33
+
34
+ export const ScrollView = memo(forwardRef(ScrollViewImpl)) as ScrollViewType
35
+
36
+ const ScrollViewEventMapping: Record<string, string> = {
37
+ onContentSizeChange: 'bindcontentsizechanged',
38
+ }
39
+
40
+ /**
41
+ * @example
42
+ * ```javascript
43
+ * <ScrollView
44
+ scene={`viewpager_${index1}`}
45
+ style={{ width: '100%', height: '100%' }}
46
+ estimatedItemStyle={{ width: '100%', height: '800px' }}
47
+ scrollOrientation='vertical'
48
+ exposureRight="50px"
49
+ exposureBottom="220px"
50
+ >
51
+ {scrollview.map((item, index) => (
52
+ <view
53
+ style={`width:100%;height:580rpx;`}
54
+ >
55
+ <text>{`slot-${index}`}</text>
56
+ </view>
57
+ ))}
58
+ </ScrollView>
59
+ * ```
60
+ */
61
+ function ScrollViewImpl(
62
+ props: ScrollViewProps,
63
+ _ref: ForwardedRef<ScrollViewRef>,
64
+ ) {
65
+ const {
66
+ scrollviewId = 'scrollview',
67
+ horizontal = false,
68
+ style,
69
+ children,
70
+ scrollOrientation,
71
+ lazyOptions,
72
+ className = '',
73
+ bounceableOptions = {
74
+ enableBounces: true,
75
+ singleSidedBounce: 'iOSBounces',
76
+ },
77
+ enableScroll = true,
78
+ enableScrollMonitor = false,
79
+ scrollMonitorTag,
80
+ sticky,
81
+ scrollPropagationBehavior = 'native',
82
+ temporaryBlockScrollClass = 'BDXLynxViewPager',
83
+ temporaryBlockScrollTag = 0,
84
+ temporaryNestedScroll,
85
+ androidTouchSlop,
86
+ 'main-thread:gesture': gesture,
87
+ } = props
88
+ // generates binding events dynamically
89
+ const scrollViewRegisteredEvents = useRef<Record<string, string>>({
90
+ ...ScrollEventsMapping,
91
+ ...ExposureEventsMapping,
92
+ ...TouchEventsMapping,
93
+ ...LayoutEventsMapping,
94
+ ...ScrollViewEventMapping,
95
+ })
96
+ const normalizedLazyOptions: LazyOptions | undefined = lazyOptions
97
+ ? { firstScreenItemCount: 1, ...lazyOptions }
98
+ : undefined
99
+ const registerEvents = useRegisteredEvents(
100
+ props,
101
+ scrollViewRegisteredEvents.current,
102
+ )
103
+
104
+ const isHorizontal = () => {
105
+ return scrollOrientation ? scrollOrientation === 'horizontal' : horizontal
106
+ }
107
+
108
+ // Initialize bounceableProps
109
+ let enableBounce = false
110
+ let bounceableProps: BounceableBasicProps = { enableBounces: false }
111
+ if (typeof bounceableOptions === 'boolean') {
112
+ // Initialize the default value if the bounceableOptions is simply 'true' without specific options
113
+ enableBounce = bounceableOptions
114
+ bounceableProps = {
115
+ enableBounces: enableBounce,
116
+ singleSidedBounce: 'both',
117
+ alwaysBouncing: true,
118
+ validAnimationVersion: true,
119
+ }
120
+ } else if (typeof bounceableOptions === 'object') {
121
+ enableBounce = bounceableOptions.enableBounces
122
+ bounceableProps = bounceableOptions
123
+ bounceableProps.singleSidedBounce = bounceableOptions.singleSidedBounce
124
+ ?? 'both'
125
+ bounceableProps.alwaysBouncing = bounceableOptions.alwaysBouncing ?? true
126
+ bounceableProps.validAnimationVersion =
127
+ bounceableOptions.validAnimationVersion ?? true
128
+ }
129
+ // Only when the enableBounces is true and singleSidedBounce is set to 'iOSBounces' will it use default bounces effect on iOS.
130
+ const platformBounces = enableBounce
131
+ && bounceableProps?.singleSidedBounce === 'iOSBounces'
132
+
133
+ const shouldEnableNested = () => {
134
+ if (
135
+ SystemInfo.platform === 'iOS' && scrollPropagationBehavior !== 'propagate'
136
+ ) {
137
+ return false
138
+ }
139
+ return true
140
+ }
141
+
142
+ const renderChildren = (
143
+ children: ReactNode,
144
+ lazyOptions: LazyOptions | undefined,
145
+ ) => {
146
+ if (!Array.isArray(children)) {
147
+ return children
148
+ }
149
+ const lazy = lazyOptions?.enableLazy
150
+ return children.map((item: ReactNode, index: number) => {
151
+ if (lazy && index >= Number(lazyOptions?.firstScreenItemCount)) {
152
+ return (
153
+ <LazyComponent
154
+ key={`${scrollviewId}_lazy_${index}`}
155
+ scene={lazyOptions?.scene}
156
+ pid={`pid_${index}`}
157
+ estimatedStyle={lazyOptions?.estimatedItemStyle}
158
+ top={lazyOptions?.exposureTop}
159
+ bottom={lazyOptions?.exposureBottom}
160
+ left={lazyOptions?.exposureLeft}
161
+ right={lazyOptions?.exposureRight}
162
+ >
163
+ {item}
164
+ </LazyComponent>
165
+ )
166
+ }
167
+ return item
168
+ })
169
+ }
170
+
171
+ // These props will be spread directly to <scroll-view> element. Make sure it's valid
172
+ type ExtendedScrollViewElementProps = ScrollViewElementProps & {
173
+ 'scroll-x': boolean
174
+ 'scroll-y': boolean
175
+ }
176
+ const elementProps: ExtendedScrollViewElementProps & {
177
+ 'enable-scroll-monitor': boolean
178
+ 'scroll-monitor-tag'?: string
179
+ 'main-thread:gesture'?: GestureKind
180
+ 'enable-new-nested'?: boolean
181
+ 'enable-nested-scroll'?: boolean
182
+ 'force-can-scroll'?: boolean
183
+ 'ios-block-gesture-class'?: string
184
+ 'ios-recognized-view-tag'?: number
185
+ 'className'?: string
186
+ 'style'?: CSSProperties
187
+ 'bounces'?: boolean
188
+ } = {
189
+ 'id': scrollviewId,
190
+ 'scroll-x': isHorizontal(),
191
+ 'scroll-y': !isHorizontal(),
192
+ 'enable-scroll-monitor': enableScrollMonitor,
193
+ 'scroll-monitor-tag': scrollMonitorTag,
194
+ 'main-thread:gesture': gesture as GestureKind,
195
+ 'force-can-scroll': scrollPropagationBehavior === 'preventPropagate',
196
+ 'ios-block-gesture-class': scrollPropagationBehavior === 'preventPropagate'
197
+ ? temporaryBlockScrollClass
198
+ : '',
199
+ 'ios-recognized-view-tag': scrollPropagationBehavior === 'preventPropagate'
200
+ ? temporaryBlockScrollTag
201
+ : 0,
202
+ 'enable-nested-scroll': SystemInfo.platform === 'Android'
203
+ ? (temporaryNestedScroll ?? true)
204
+ : shouldEnableNested(),
205
+ 'enable-new-nested': true,
206
+ 'className': className,
207
+ 'style': style,
208
+ 'bounces': platformBounces,
209
+ 'enable-scroll': enableScroll,
210
+ ...(androidTouchSlop !== undefined
211
+ && { 'android-touch-slop': androidTouchSlop }),
212
+ ...registerEvents,
213
+ }
214
+
215
+ if (
216
+ enableBounce
217
+ && bounceableProps.singleSidedBounce !== 'iOSBounces'
218
+ && bounceableProps.singleSidedBounce !== 'none'
219
+ ) {
220
+ return (
221
+ <ScrollViewWithBouncesHook
222
+ elementProps={elementProps}
223
+ bounceableOptions={bounceableProps}
224
+ sticky={sticky}
225
+ >
226
+ {renderChildren(children, normalizedLazyOptions)}
227
+ </ScrollViewWithBouncesHook>
228
+ )
229
+ } else {
230
+ return (
231
+ <ScrollViewBasic elementProps={elementProps} sticky={sticky}>
232
+ {renderChildren(children, normalizedLazyOptions)}
233
+ </ScrollViewBasic>
234
+ )
235
+ }
236
+ }
@@ -0,0 +1,276 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ import type { ReactElement, ReactNode } from '@lynx-js/react'
6
+
7
+ import type { BaseGesture } from '@lynx-js/gesture-runtime'
8
+ import type {
9
+ BaseScrollEvents,
10
+ BaseUIExposureEvents,
11
+ BaseUIExposureProps,
12
+ BaseUILayoutEvents,
13
+ BaseUITouchEvents,
14
+ BounceableBasicProps,
15
+ ComponentBasicProps,
16
+ LazyOptions,
17
+ } from '@lynx-js/lynx-ui-common'
18
+ import type { CSSProperties } from '@lynx-js/types'
19
+
20
+ export type ScrollView = (props: ScrollViewProps) => ReactElement
21
+
22
+ type ScrollPropagationBehaviorOption =
23
+ | 'native' // Follows platform default behavior
24
+ | 'propagate' // Always allow scroll propagation
25
+ // | 'propagateAtEdge' // @todo Child scrolls first; parent scrolls on next touch at edge
26
+ | 'preventPropagate' // Never allow scroll propagation
27
+
28
+ // biome-ignore lint/suspicious/noEmptyInterface: <explanation>
29
+ export interface ScrollViewRef {}
30
+
31
+ export interface ScrollViewProps
32
+ extends
33
+ BaseUITouchEvents,
34
+ BaseScrollEvents,
35
+ BaseUIExposureEvents,
36
+ BaseUILayoutEvents,
37
+ BaseUIExposureProps,
38
+ ComponentBasicProps
39
+ {
40
+ /**
41
+ * The id of the scrollview.
42
+ * @zh 滚动视图的id。
43
+ * @defaultValue "scrollview"
44
+ * @Android
45
+ * @iOS
46
+ */
47
+ scrollviewId?: string
48
+ /**
49
+ * Enable scroll interaction.
50
+ * @zh 启用滚动。
51
+ * @defaultValue true
52
+ * @Android
53
+ * @iOS
54
+ * @Harmony
55
+ */
56
+ enableScroll?: boolean
57
+ /**
58
+ * Open the bouncing effect on iOS. If you want to use it on Android, please refer to the bounceableOption. If the bounceableOption is set, the iOSBounces property will be invalid.
59
+ * @zh 开启iOS上的回弹效果。如果想在安卓上使用,请参考bounceableOption。如果设置了bounceableOption,iOSBounces属性将失效。
60
+ * @defaultValue true
61
+ * @Android
62
+ * @iOS
63
+ */
64
+ iOSBounces?: boolean
65
+ /**
66
+ * Testing Mode.
67
+ * @zh 测试模式
68
+ * @Android
69
+ * @iOS
70
+ */
71
+ testing?: boolean
72
+ /**
73
+ * Be used to mark the exposure timing of lazy loading. Please ensure that it is unique throughout the page.
74
+ * @zh 用于标记懒加载的曝光时机。请确保页面中唯一。
75
+ * @Android
76
+ * @iOS
77
+ * @deprecated Please use lazyOptions instead.
78
+ */
79
+ scene?: string
80
+ /**
81
+ * Horizontal scroll.
82
+ * @zh 水平滚动。
83
+ * @deprecated 3.119. Use scrollOrientation instead.
84
+ * @Android
85
+ * @iOS
86
+ */
87
+ horizontal?: boolean
88
+ /**
89
+ * Set to 'vertical' for vertical scrolling and set to 'horizontal' for horizontal scrolling.
90
+ * @zh 设置为 'vertical' 为垂直滚动,设置为 'horizontal' 为水平滚动。
91
+ * @defaultValue 'vertical'
92
+ * @since 3.119
93
+ * @iOS
94
+ * @Android
95
+ * @Harmony
96
+ */
97
+ scrollOrientation?: 'vertical' | 'horizontal'
98
+ /**
99
+ * When enabled, only the items that are about to enter the viewport are rendered, reducing initial load time and memory usage; remaining items are rendered as they approach visibility during scroll.
100
+ * @zh 启用懒渲染。只有当用户滚动到可见区域时,才会渲染 items,从而减少初始加载时间和内存使用。
101
+ * @defaultValue true
102
+ * @Android
103
+ * @iOS
104
+ */
105
+ lazyOptions?: LazyOptions
106
+ /**
107
+ * Estimated height and width of the items need to be set.
108
+ * @zh 需要设置 items 的预计高度和宽度。
109
+ * @Android
110
+ * @iOS
111
+ * @deprecated Please use lazyOptions instead.
112
+ */
113
+ estimatedItemStyle?: CSSProperties
114
+ /**
115
+ * When enabled, only the items that are about to enter the viewport are rendered, reducing initial load time and memory usage; remaining items are rendered as they approach visibility during scroll.
116
+ * @zh 启用懒渲染。只有当用户滚动到可见区域时,才会渲染 items,从而减少初始加载时间和内存使用。
117
+ * @defaultValue true
118
+ * @Android
119
+ * @iOS
120
+ * @deprecated Please use lazyOptions instead.
121
+ */
122
+ lazy?: boolean
123
+ /**
124
+ * Sticky item, designed for `Tabs`.
125
+ * @zh 粘性元素,设计用于 `Tabs`。
126
+ * @Android
127
+ * @iOS
128
+ */
129
+ sticky?: ReactElement
130
+ /**
131
+ * Children in scroll-view.
132
+ * @zh `scroll-view` 的子元素。
133
+ * @Android
134
+ * @iOS
135
+ */
136
+ children?: ReactNode
137
+ /**
138
+ * exposure-screen-margin-top
139
+ * @zh 曝光屏幕上方边距
140
+ * @defaultValue '10px'
141
+ * @Android
142
+ * @iOS
143
+ * @deprecated Please use lazyOptions instead.
144
+ */
145
+ exposureTop?: string
146
+ /**
147
+ * exposure-screen-margin-bottom
148
+ * @zh 曝光屏幕下方边距
149
+ * @defaultValue '10px'
150
+ * @Android
151
+ * @iOS
152
+ * @deprecated Please use lazyOptions instead.
153
+ */
154
+ exposureBottom?: string
155
+ /**
156
+ * exposure-screen-margin-left
157
+ * @zh 曝光屏幕左侧边距
158
+ * @defaultValue '10px'
159
+ * @Android
160
+ * @iOS
161
+ * @deprecated Please use lazyOptions instead.
162
+ */
163
+ exposureLeft?: string
164
+ /**
165
+ * exposure-screen-margin-right
166
+ * @zh 曝光屏幕右侧边距
167
+ * @defaultValue '10px'
168
+ * @Android
169
+ * @iOS
170
+ * @deprecated Please use lazyOptions instead.
171
+ */
172
+ exposureRight?: string
173
+ /**
174
+ * Enable scroll monitor.
175
+ * @zh 启用滚动监控。
176
+ * @defaultValue false
177
+ * @iOS
178
+ * @Android
179
+ * @Harmony
180
+ */
181
+ enableScrollMonitor?: boolean
182
+ /**
183
+ * The tag for scroll monitor.
184
+ * @zh 滚动监控的标签。
185
+ * @defaultValue false
186
+ * @iOS
187
+ * @Android
188
+ * @Harmony
189
+ */
190
+ scrollMonitorTag?: string
191
+ /**
192
+ * Estimated first screen item count for lazy rendering. Remaining children will complete rendering based on exposure. When this estimate is small, it may cause a blank screen phenomenon where some nodes exist on the first screen.
193
+ * @zh 懒加载时预计的第一页项数。剩余的子元素会基于曝光状态完成渲染。当此预估较小时,可能会导致第一屏出现空白现象。
194
+ * @defaultValue 1
195
+ * @Android
196
+ * @iOS
197
+ * @deprecated Please use lazyOptions instead.
198
+ */
199
+ firstScreenItemCount?: number
200
+ /**
201
+ * Enable bouncing effect
202
+ * @zh 启用弹性效果
203
+ * @Android
204
+ * @iOS
205
+ * @deprecated Please use bounceableOptions instead.
206
+ */
207
+ bounceable?: boolean
208
+ /**
209
+ * Props for bouncing effect
210
+ * @zh 弹性效果的参数
211
+ * @defaultValue { enableBounces: true, singleSidedBounce: "iOSBounces" },
212
+ * @Android
213
+ * @iOS
214
+ */
215
+ bounceableOptions?: boolean | BounceableBasicProps
216
+ /**
217
+ * Controls whether scroll events propagate to parent containers. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
218
+ * @zh 控制滚动事件是否向父级容器传递。'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。
219
+ * @experimental Currently, this property has limitations because its full functionality depends on a higher native SDK version: on iOS, `propagate` only works if both the parent and this component are set to` propagate` and `useRefactorList={true}` does not support 'propagate'. On Android, `preventPropagate` only functions when the parent is `x-swiper` or `x-viewpager-ng`.
220
+ * @defaultValue 'native'
221
+ * @iOS
222
+ * @Android
223
+ */
224
+ scrollPropagationBehavior?: ScrollPropagationBehaviorOption
225
+ /**
226
+ * The specific class name of the container that is blocked when 'scrollPropagationBehavior' is set to be 'preventPropagate', must be informed by the container provider. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
227
+ * @zh 当 scrollPropagationBehavior 设为 'preventPropagate' 时,被阻止滚动的容器的具体类名。'preventPropagate' 需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。
228
+ * This is a temporary props and will be deprecated on new Lynx SDK version.
229
+ * @defaultValue 'BDXLynxViewPager'
230
+ * @iOS
231
+ */
232
+ temporaryBlockScrollClass?: string
233
+ /**
234
+ * Used to specify the native container tag that is blocked when 'scrollPropagationBehavior' is set to be 'preventPropagate', corresponding to the Tag attribute of UIView. Needs to be specified by the native container provider. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
235
+ * @zh 用于指定当 scrollPropagationBehavior 设为 'preventPropagate' 时被阻止滚动的原生容器标签(对应 UIView 的 Tag 属性)。该值需由原生容器提供方指定,且 'preventPropagate' 必须与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。
236
+ * This is a temporary props and will be deprecated on new Lynx SDK version.
237
+ * @defaultValue 0
238
+ * @iOS
239
+ */
240
+ temporaryBlockScrollTag?: number
241
+ /**
242
+ * Android-only temporary flag to control nested scroll; maps to native 'enable-nested-scroll'. Android default value is true.
243
+ * @zh 仅 Android 生效的临时开关,用于控制嵌套滚动冲突;映射到原生属性 'enable-nested-scroll'。Android上默认开启。
244
+ * @Android
245
+ */
246
+ temporaryNestedScroll?: boolean
247
+ /**
248
+ * If you want to use gesture, pass it here.
249
+ * @zh 如果想使用 gesture API,请传入该属性。
250
+ * @iOS
251
+ * @Android
252
+ */
253
+ 'main-thread:gesture'?: BaseGesture
254
+
255
+ /**
256
+ * Android touch recognition mode. When inside a component that supports 'paging' mode, 'paging' must be enabled.
257
+ * @zh Android 触摸识别模式,当处于支持 'paging' 模式的元件中时,需要开启 'paging' 模式。
258
+ * @Android
259
+ */
260
+ androidTouchSlop?: 'default' | 'paging'
261
+
262
+ /**
263
+ * Being triggered when scrolling content changes.
264
+ * @zh 滚动内容变化时触发。
265
+ * @eventProperty
266
+ * @Android
267
+ * @iOS
268
+ */
269
+ onContentSizeChange?: (res: {
270
+ detail: { scrollWidth: number, scrollHeight: number }
271
+ }) => void
272
+ }
273
+
274
+ export const ScrollEventMapping: Record<string, string> = {
275
+ onContentSizeChange: 'bindcontentsizechange',
276
+ }
@@ -0,0 +1,5 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ export type * from './index.docs'
@@ -0,0 +1,7 @@
1
+ {
2
+ "extends": "../../tools/configs/tsconfig.docs.json",
3
+ "include": [
4
+ "src",
5
+ "dist/types/index.docs.d.ts"
6
+ ]
7
+ }
package/tsconfig.json ADDED
@@ -0,0 +1,9 @@
1
+ {
2
+ "extends": "../../tools/configs/tsconfig.lib.json",
3
+ "compilerOptions": {
4
+ "rootDir": "./src",
5
+ },
6
+ "include": [
7
+ "src",
8
+ ],
9
+ }
File without changes