@lynx-js/lynx-ui-swiper 0.0.0 → 3.131.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.
Files changed (137) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/LICENSE +201 -0
  3. package/README.md +51 -0
  4. package/dist/Swiper/index.d.ts +11 -0
  5. package/dist/Swiper/index.d.ts.map +1 -0
  6. package/dist/Swiper/index.jsx +261 -0
  7. package/dist/Swiper/index.jsx.map +1 -0
  8. package/dist/Swiper/styles.css +47 -0
  9. package/dist/Swiper/styles.css.map +1 -0
  10. package/dist/SwiperItem/index.d.ts +46 -0
  11. package/dist/SwiperItem/index.d.ts.map +1 -0
  12. package/dist/SwiperItem/index.jsx +86 -0
  13. package/dist/SwiperItem/index.jsx.map +1 -0
  14. package/dist/const/index.d.ts +5 -0
  15. package/dist/const/index.d.ts.map +1 -0
  16. package/dist/const/index.jsx +7 -0
  17. package/dist/const/index.jsx.map +1 -0
  18. package/dist/hooks/useAnimate.d.ts +5 -0
  19. package/dist/hooks/useAnimate.d.ts.map +1 -0
  20. package/dist/hooks/useAnimate.jsx +47 -0
  21. package/dist/hooks/useAnimate.jsx.map +1 -0
  22. package/dist/hooks/useAutoPlay.d.ts +16 -0
  23. package/dist/hooks/useAutoPlay.d.ts.map +1 -0
  24. package/dist/hooks/useAutoPlay.jsx +58 -0
  25. package/dist/hooks/useAutoPlay.jsx.map +1 -0
  26. package/dist/hooks/useAxisLock.d.ts +12 -0
  27. package/dist/hooks/useAxisLock.d.ts.map +1 -0
  28. package/dist/hooks/useAxisLock.jsx +58 -0
  29. package/dist/hooks/useAxisLock.jsx.map +1 -0
  30. package/dist/hooks/useBounceConfig.d.ts +12 -0
  31. package/dist/hooks/useBounceConfig.d.ts.map +1 -0
  32. package/dist/hooks/useBounceConfig.jsx +15 -0
  33. package/dist/hooks/useBounceConfig.jsx.map +1 -0
  34. package/dist/hooks/useBounceView.d.ts +17 -0
  35. package/dist/hooks/useBounceView.d.ts.map +1 -0
  36. package/dist/hooks/useBounceView.jsx +16 -0
  37. package/dist/hooks/useBounceView.jsx.map +1 -0
  38. package/dist/hooks/useChange.d.ts +22 -0
  39. package/dist/hooks/useChange.d.ts.map +1 -0
  40. package/dist/hooks/useChange.jsx +53 -0
  41. package/dist/hooks/useChange.jsx.map +1 -0
  42. package/dist/hooks/useDirection.d.ts +13 -0
  43. package/dist/hooks/useDirection.d.ts.map +1 -0
  44. package/dist/hooks/useDirection.jsx +37 -0
  45. package/dist/hooks/useDirection.jsx.map +1 -0
  46. package/dist/hooks/useFirstScreenStyle.d.ts +34 -0
  47. package/dist/hooks/useFirstScreenStyle.d.ts.map +1 -0
  48. package/dist/hooks/useFirstScreenStyle.jsx +63 -0
  49. package/dist/hooks/useFirstScreenStyle.jsx.map +1 -0
  50. package/dist/hooks/useModeConfig.d.ts +14 -0
  51. package/dist/hooks/useModeConfig.d.ts.map +1 -0
  52. package/dist/hooks/useModeConfig.jsx +33 -0
  53. package/dist/hooks/useModeConfig.jsx.map +1 -0
  54. package/dist/hooks/useOffset.d.ts +37 -0
  55. package/dist/hooks/useOffset.d.ts.map +1 -0
  56. package/dist/hooks/useOffset.jsx +362 -0
  57. package/dist/hooks/useOffset.jsx.map +1 -0
  58. package/dist/hooks/useOffsetLimit.d.ts +16 -0
  59. package/dist/hooks/useOffsetLimit.d.ts.map +1 -0
  60. package/dist/hooks/useOffsetLimit.jsx +51 -0
  61. package/dist/hooks/useOffsetLimit.jsx.map +1 -0
  62. package/dist/hooks/useReset.d.ts +16 -0
  63. package/dist/hooks/useReset.d.ts.map +1 -0
  64. package/dist/hooks/useReset.jsx +68 -0
  65. package/dist/hooks/useReset.jsx.map +1 -0
  66. package/dist/hooks/useSwipeCallback.d.ts +14 -0
  67. package/dist/hooks/useSwipeCallback.d.ts.map +1 -0
  68. package/dist/hooks/useSwipeCallback.jsx +40 -0
  69. package/dist/hooks/useSwipeCallback.jsx.map +1 -0
  70. package/dist/hooks/useVelocity.d.ts +14 -0
  71. package/dist/hooks/useVelocity.d.ts.map +1 -0
  72. package/dist/hooks/useVelocity.jsx +62 -0
  73. package/dist/hooks/useVelocity.jsx.map +1 -0
  74. package/dist/hooks/useVelocity_experiment.d.ts +12 -0
  75. package/dist/hooks/useVelocity_experiment.d.ts.map +1 -0
  76. package/dist/hooks/useVelocity_experiment.jsx +38 -0
  77. package/dist/hooks/useVelocity_experiment.jsx.map +1 -0
  78. package/dist/index.d.ts +5 -0
  79. package/dist/index.d.ts.map +1 -0
  80. package/dist/index.jsx +3 -0
  81. package/dist/store/index.d.ts +3 -0
  82. package/dist/store/index.d.ts.map +1 -0
  83. package/dist/store/index.jsx +18 -0
  84. package/dist/store/index.jsx.map +1 -0
  85. package/dist/types/index.d.ts +62 -0
  86. package/dist/types/index.d.ts.map +1 -0
  87. package/dist/types/index.docs.d.ts +448 -0
  88. package/dist/types/index.docs.d.ts.map +1 -0
  89. package/dist/types/index.jsx +9 -0
  90. package/dist/types/index.jsx.map +1 -0
  91. package/dist/utils/animate.d.ts +4 -0
  92. package/dist/utils/animate.d.ts.map +1 -0
  93. package/dist/utils/animate.jsx +29 -0
  94. package/dist/utils/animate.jsx.map +1 -0
  95. package/dist/utils/compareProps.d.ts +2 -0
  96. package/dist/utils/compareProps.d.ts.map +1 -0
  97. package/dist/utils/compareProps.jsx +14 -0
  98. package/dist/utils/compareProps.jsx.map +1 -0
  99. package/dist/utils/customRound.d.ts +10 -0
  100. package/dist/utils/customRound.d.ts.map +1 -0
  101. package/dist/utils/customRound.jsx +9 -0
  102. package/dist/utils/customRound.jsx.map +1 -0
  103. package/dist/utils/index.d.ts +20 -0
  104. package/dist/utils/index.d.ts.map +1 -0
  105. package/dist/utils/index.jsx +55 -0
  106. package/dist/utils/index.jsx.map +1 -0
  107. package/package.json +47 -4
  108. package/src/Swiper/index.tsx +414 -0
  109. package/src/Swiper/styles.css +44 -0
  110. package/src/SwiperItem/index.tsx +205 -0
  111. package/src/const/index.ts +11 -0
  112. package/src/hooks/useAnimate.ts +80 -0
  113. package/src/hooks/useAutoPlay.ts +95 -0
  114. package/src/hooks/useAxisLock.ts +92 -0
  115. package/src/hooks/useBounceConfig.ts +29 -0
  116. package/src/hooks/useBounceView.tsx +50 -0
  117. package/src/hooks/useChange.ts +131 -0
  118. package/src/hooks/useDirection.ts +59 -0
  119. package/src/hooks/useFirstScreenStyle.ts +200 -0
  120. package/src/hooks/useModeConfig.ts +56 -0
  121. package/src/hooks/useOffset.ts +609 -0
  122. package/src/hooks/useOffsetLimit.ts +98 -0
  123. package/src/hooks/useReset.ts +144 -0
  124. package/src/hooks/useSwipeCallback.ts +66 -0
  125. package/src/hooks/useVelocity.ts +85 -0
  126. package/src/hooks/useVelocity_experiment.ts +50 -0
  127. package/src/index.ts +8 -0
  128. package/src/store/index.ts +23 -0
  129. package/src/types/index.docs.ts +465 -0
  130. package/src/types/index.ts +105 -0
  131. package/src/utils/animate.ts +49 -0
  132. package/src/utils/compareProps.ts +54 -0
  133. package/src/utils/customRound.ts +23 -0
  134. package/src/utils/index.ts +117 -0
  135. package/tsconfig.docs.json +7 -0
  136. package/tsconfig.json +9 -0
  137. /package/{index.js → dist/types/index.docs.jsx} +0 -0
@@ -0,0 +1,465 @@
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 } from '@lynx-js/react'
6
+
7
+ import type { CSSProperties } from '@lynx-js/types'
8
+
9
+ export interface SwiperProps<T> {
10
+ /**
11
+ * Swiper items data set
12
+ * @Android
13
+ * @iOS
14
+ * @Harmony
15
+ * @zh 轮播图数据集合
16
+ */
17
+ data: T[]
18
+ /**
19
+ * Width of swiper item
20
+ * @Android
21
+ * @iOS
22
+ * @Harmony
23
+ * @zh 轮播图项宽度
24
+ */
25
+ itemWidth: number
26
+ /**
27
+ * Height of SwiperItem
28
+ * @Android
29
+ * @iOS
30
+ * @Harmony
31
+ * @zh 轮播图项高度
32
+ */
33
+ itemHeight?: number | 'auto'
34
+ /**
35
+ * Children of Swiper should be a function, returning a SwiperItem
36
+ * @Android
37
+ * @iOS
38
+ * @Harmony
39
+ * @zh Swiper的子元素应该是一个函数,返回一个SwiperItem
40
+ * @example
41
+ * ```tsx
42
+ * <Swiper
43
+ * data={items}
44
+ * itemWidth={350}
45
+ * >
46
+ * {({ index, item }) => (
47
+ * <SwiperItem index={index} key={index}>
48
+ * <image class="image" src={`${item}`}></image>
49
+ * <text class="image-text">Number.{index}</text>
50
+ * </SwiperItem>
51
+ * )}
52
+ * </Swiper>
53
+ * ```
54
+ */
55
+ children: (prop: RenderFunctionProps<T>) => ReactElement
56
+ /**
57
+ * Width of swiper item
58
+ * @defaultValue lynx.__globalProps.screenWidth
59
+ * @Android
60
+ * @iOS
61
+ * @Harmony
62
+ * @zh 轮播图容器的宽度
63
+ */
64
+ containerWidth?: number
65
+ /**
66
+ * Initial index of Swiper, this value will only be used at firstScreen. Later updates will be ignored.
67
+ * @defaultValue 0
68
+ * @Android
69
+ * @iOS
70
+ * @Harmony
71
+ * @zh Swiper的初始索引,该值仅在首屏时使用。后续更新将被忽略。
72
+ */
73
+ initialIndex?: number
74
+ /**
75
+ * Swiper loop back
76
+ * @defaultValue false
77
+ * @Android
78
+ * @iOS
79
+ * @Harmony
80
+ * @zh 是否开启循环轮播
81
+ */
82
+ loop?: boolean
83
+ /**
84
+ * When loop is true, Swiper will duplicate the first 2 items and last 2 items to create a loop effect.
85
+ * This prop can be used to customize how many items to duplicate the first and last item.
86
+ * @defaultValue 2
87
+ * @Android
88
+ * @iOS
89
+ * @Harmony
90
+ * @zh 当loop为true时,Swiper会复制前2个和后2个项目来创建循环效果。此属性可用于自定义复制第一个和最后一个项目的数量。
91
+ */
92
+ loopDuplicateCount?: number
93
+ /**
94
+ * Duration of animation for paging or swiping
95
+ * @defaultValue 500
96
+ * @Android
97
+ * @iOS
98
+ * @Harmony
99
+ * @zh 翻页或滑动动画的持续时间
100
+ */
101
+ duration?: number
102
+ /**
103
+ * Callback fired when currentIndex of Swiper has changed
104
+ * @Android
105
+ * @iOS
106
+ * @Harmony
107
+ * @zh 当前索引改变时的回调函数
108
+ */
109
+ onChange?: (current: number) => void
110
+ /**
111
+ * Callback fired when swiper started to swipe. Can be used with `onSwipeStop`.
112
+ * This is useful for disabling clicking when swiping.
113
+ * @Android
114
+ * @iOS
115
+ * @Harmony
116
+ * @zh 开始滑动时的回调函数。可与`onSwipeStop`配合使用。用于在滑动时禁用点击事件。
117
+ */
118
+ onSwipeStart?: (current: number) => void
119
+ /**
120
+ * Callback fired when swiper stopped to swipe. Can be used with `onSwipeStart`.
121
+ * This is useful for disabling clicking when swiping.
122
+ * @Android
123
+ * @iOS
124
+ * @Harmony
125
+ * @zh 停止滑动时的回调函数。可与`onSwipeStart`配合使用。用于在滑动时禁用点击事件。
126
+ */
127
+ onSwipeStop?: (current: number) => void
128
+ /**
129
+ * Callback fired when offset of Swiper changed.
130
+ * Should be a MainThread function
131
+ * @Android
132
+ * @iOS
133
+ * @Harmony
134
+ * @zh Swiper偏移量改变时的回调函数。应该是一个主线程函数
135
+ */
136
+ 'main-thread:onOffsetChange'?: (offset: number) => void
137
+ /**
138
+ * Custom easing function for paging effect
139
+ * @Android
140
+ * @iOS
141
+ * @Harmony
142
+ * @zh 自定义翻页效果的缓动函数
143
+ */
144
+ 'main-thread:easing'?: (progress: number) => number
145
+ /**
146
+ * Custom animation effect, should be a MainThread function
147
+ * @Android
148
+ * @iOS
149
+ * @Harmony
150
+ * @zh 自定义动画效果,应该是一个主线程函数
151
+ */
152
+ 'main-thread:customAnimation'?: (
153
+ value: number,
154
+ index: number,
155
+ ) => CSSProperties
156
+ /**
157
+ * Custom animation effect used in JS, should be a JS function.
158
+ * customAnimationFirstScreen should be a function of the same content of 'main-thread:customAnimation' without 'main thread' annotation
159
+ * This is a workaround for MainThreadScript's disability for supporting firstScreen.
160
+ * We are working on removing the duplicated JS version of customAnimation. For now, this is needed.
161
+ * @Android
162
+ * @iOS
163
+ * @Harmony
164
+ * @zh 在JS中使用的自定义动画效果,应该是一个JS函数。customAnimationFirstScreen应该是与'main-thread:customAnimation'内容相同的函数,但不带'main thread'注解。这是对MainThreadScript不支持首屏的临时解决方案。我们正在努力移除重复的JS版本的customAnimation。目前这是必需的。
165
+ */
166
+ customAnimationFirstScreen?: (value: number, index: number) => CSSProperties
167
+ /**
168
+ * Whether to enable autoPlay
169
+ * @defaultValue false
170
+ * @Android
171
+ * @iOS
172
+ * @Harmony
173
+ * @zh 是否启用自动播放
174
+ */
175
+ autoPlay?: boolean
176
+ /**
177
+ * Auto play interval
178
+ * @defaultValue 2000
179
+ * @Android
180
+ * @iOS
181
+ * @Harmony
182
+ * @zh 自动播放间隔
183
+ */
184
+ autoPlayInterval?: number
185
+ /**
186
+ * Use this to limit or extend the offset of Swiper's range.
187
+ * This can be useful for limiting offset to avoid overscroll.
188
+ * For example, when mode === 'normal', and modeConfig.align === 'start', swipe to the last item technically means the last item's left
189
+ * edge align with container's left edge, leaving a blank area, which usually is not what we want.
190
+ * So we add an offsetLimit of [0, containerWidth - itemWidth], to limit the offset of Swiper.
191
+ * In this case, when swipe to the end, the last item's right edge align with container's right edge, leaving no blank area.
192
+ * @Android
193
+ * @iOS
194
+ * @Harmony
195
+ * @zh 用于限制或扩展Swiper的偏移量范围。可用于限制偏移量以避免过度滚动。例如,当mode === 'normal'且modeConfig.align === 'start'时,滑动到最后一个项目技术上意味着最后一个项目的左边缘与容器的左边缘对齐,留下空白区域,这通常不是我们想要的。因此我们添加了offsetLimit为[0, containerWidth - itemWidth],来限制Swiper的偏移量。在这种情况下,当滑动到末尾时,最后一个项目的右边缘与容器的右边缘对齐,不会留下空白区域。
196
+ */
197
+ offsetLimit?: [number, number]
198
+ /**
199
+ * BounceParams
200
+ * @Android
201
+ * @iOS
202
+ * @Harmony
203
+ * @zh 回弹参数配置
204
+ */
205
+ bounceConfig?: BounceConfig
206
+ /**
207
+ * key of Swiper Component. Change this will reset Swiper progress and state.
208
+ * Can be used when reusing Swiper Component. Upon resting, `initialIndex` will be used again.
209
+ * @Android
210
+ * @iOS
211
+ * @Harmony
212
+ * @zh Swiper组件的key。更改此值将重置Swiper的进度和状态。可在重用Swiper组件时使用。重置时,将再次使用`initialIndex`。
213
+ */
214
+ swiperKey?: unknown
215
+ /**
216
+ * Whether to reset Swiper progress and state when reuse Swiper Component.
217
+ * Can be useful when used in list.
218
+ * @defaultValue false
219
+ * @Android
220
+ * @iOS
221
+ * @Harmony
222
+ * @zh 在重用Swiper组件时是否重置Swiper的进度和状态。
223
+ */
224
+ resetOnReuse?: boolean
225
+ /**
226
+ * Style for the root element of the Swiper component.
227
+ * This controls the visible viewport/frame that contains the swiper.
228
+ * Use this for: background, borders, padding, dimensions, overflow, etc.
229
+ * @Android
230
+ * @iOS
231
+ * @Harmony
232
+ * @zh Swiper组件根元素的样式。控制包含轮播图的可见视口/框架。用于:背景、边框、内边距、尺寸、溢出等。
233
+ */
234
+ style?: CSSProperties
235
+
236
+ /**
237
+ * Style for the inner sliding track that holds all swiper items.
238
+ * This is the element that actually moves/slides.
239
+ * @Android
240
+ * @iOS
241
+ * @Harmony
242
+ * @zh 包含所有轮播项的内部滑动轨道的样式。这是实际移动/滑动的元素。
243
+ */
244
+ trackStyle?: CSSProperties
245
+ /**
246
+ * Determines how swiper respond to touch in different angle.
247
+ * By default, swiper will only respond to horizontal touches.
248
+ * Refer to https://lynxjs.org/en/api/elements/built-in/view.html#consume-slide-event for more
249
+ * @defaultValue [[-180, -135], [-45, 45], [135, 180]]
250
+ * @Android
251
+ * @iOS
252
+ * @Harmony
253
+ * @zh 决定Swiper如何响应不同角度的触摸。默认情况下,Swiper只会响应水平方向的触摸。更多信息请参考 https://lynxjs.org/zh/api/elements/built-in/view.html#consume-slide-event
254
+ */
255
+ consumeSlideEvent?: [number, number][]
256
+ /**
257
+ * Whether to block native event.
258
+ * Can be useful when swiper is in Scrollview, List or other components that will block swiper's touch event.
259
+ * @defaultValue false
260
+ * @Android
261
+ * @iOS
262
+ * @Harmony
263
+ * @zh 是否阻止原生事件。当Swiper在Scrollview、List或其他会阻止Swiper触摸事件的组件中时可能有用。
264
+ */
265
+ blockNativeEvent?: boolean
266
+ /**
267
+ * Whether to enable RTL mode.
268
+ * @defaultValue false
269
+ * @Android
270
+ * @iOS
271
+ * @Harmony
272
+ * @zh 是否启用RTL模式。
273
+ */
274
+ RTL?: boolean | 'lynx-rtl'
275
+ }
276
+
277
+ /**
278
+ * @hidden
279
+ */
280
+ export interface SwiperPropsNormal<T> extends SwiperProps<T> {
281
+ /**
282
+ * Mode of Swiper. Normal mode will make SwiperItem placed one after another.
283
+ * Custom mode will make SwiperItem placed in absolute position in the most left.
284
+ * This is used for complex modification and customLayout.
285
+ * You need to return proper position of each SwiperItem in 'main-thread:customAnimation'
286
+ * @defaultValue normal
287
+ * @Android
288
+ * @iOS
289
+ * @Harmony
290
+ * @zh Swiper的模式。普通模式会使SwiperItem依次排列。自定义模式会使SwiperItem以绝对定位方式放置在最左侧。这用于复杂的修改和自定义布局。你需要在'main-thread:customAnimation'中返回每个SwiperItem的正确位置
291
+ */
292
+ mode?: 'normal'
293
+ /**
294
+ * Additional config for mode
295
+ * @Android
296
+ * @iOS
297
+ * @Harmony
298
+ * @zh 模式的额外配置
299
+ */
300
+ modeConfig?: {
301
+ /**
302
+ * Alignment of SwiperItem.
303
+ * @defaultValue start
304
+ * @Android
305
+ * @iOS
306
+ * @Harmony
307
+ * @zh `<SwiperItem>` 的对齐方式。
308
+ */
309
+ align?: 'start' | 'center' | 'end'
310
+ /**
311
+ * Space between SwiperItem
312
+ * @defaultValue 0
313
+ * @Android
314
+ * @iOS
315
+ * @Harmony
316
+ * @zh `<SwiperItem>` 之间的间距
317
+ */
318
+ spaceBetween?: number
319
+ }
320
+ }
321
+
322
+ /**
323
+ * @hidden
324
+ */
325
+ export interface SwiperPropsCustom<T> extends SwiperProps<T> {
326
+ /**
327
+ * Mode of Swiper. Normal mode will make SwiperItem placed one after another.
328
+ * Custom mode will make SwiperItem placed in absolute position in the most left.
329
+ * This is used for complex modification and customLayout.
330
+ * You need to return proper position of each SwiperItem in 'main-thread:customAnimation'
331
+ * @defaultValue normal
332
+ * @Android
333
+ * @iOS
334
+ * @Harmony
335
+ * @zh Swiper的模式。普通模式会使SwiperItem依次排列。自定义模式会使SwiperItem以绝对定位方式放置在最左侧。这用于复杂的修改和自定义布局。你需要在'main-thread:customAnimation'中返回每个SwiperItem的正确位置
336
+ */
337
+ mode?: 'custom'
338
+ /**
339
+ * Additional config for mode
340
+ * @Android
341
+ * @iOS
342
+ * @Harmony
343
+ * @zh 模式的额外配置
344
+ */
345
+ modeConfig?: Record<string, unknown>
346
+ }
347
+
348
+ export type SwiperPropsReal<T> = SwiperPropsNormal<T> | SwiperPropsCustom<T>
349
+
350
+ export interface SwipeToOptions {
351
+ animate?: boolean
352
+ onFinished?: () => void
353
+ }
354
+
355
+ export interface BounceConfig {
356
+ /**
357
+ * Whether to enable bounces. Ignored when loop is true.
358
+ * @defaultValue false
359
+ * @Android
360
+ * @iOS
361
+ * @Harmony
362
+ * @zh 是否启用回弹效果。当loop为true时忽略此设置。
363
+ */
364
+ enable?: boolean
365
+ /**
366
+ * The left bounceItem (when in horizontal)
367
+ * @Android
368
+ * @iOS
369
+ * @Harmony
370
+ * @zh 左侧回弹项(水平方向时)
371
+ */
372
+ startBounceItem?: ReactElement
373
+ /**
374
+ * The right bounceItem (when in horizontal)
375
+ * @Android
376
+ * @iOS
377
+ * @Harmony
378
+ * @zh 右侧回弹项(水平方向时)
379
+ */
380
+ endBounceItem?: ReactElement
381
+ /**
382
+ * When startBounceItem is in bounce state, releasing finger will call this.
383
+ * @Android
384
+ * @iOS
385
+ * @Harmony
386
+ * @zh 当startBounceItem处于回弹状态时,释放手指将调用此函数。
387
+ */
388
+ onStartBounceItemBounce?: (bounceParams: onBounceParams) => void
389
+ /** ····· ··
390
+ * When endBounceItem is in bounce state, releasing finger will call this.
391
+ * @Android
392
+ * @iOS
393
+ * @Harmony
394
+ * @zh 当endBounceItem处于回弹状态时,释放手指将调用此函数。
395
+ */
396
+ onEndBounceItemBounce?: (bounceParams: onBounceParams) => void
397
+ /**
398
+ * Width of bounceItem.
399
+ * When overscroll the bounces, you will have larger and larger resistance, to make overscroll not exceed bounceItemWidth
400
+ * @defaultValue 100
401
+ * @Android
402
+ * @iOS
403
+ * @Harmony
404
+ * @zh 回弹项的宽度。当过度滚动回弹时,你会感受到越来越大的阻力,以防止过度滚动超过bounceItemWidth
405
+ */
406
+ startBounceItemWidth?: number
407
+ /**
408
+ * Width of bounceItem.
409
+ * When overscroll the bounces, you will have larger and larger resistance, to make overscroll not exceed bounceItemWidth
410
+ * @defaultValue 100
411
+ * @Android
412
+ * @iOS
413
+ * @Harmony
414
+ * @zh 回弹项的宽度。当过度滚动回弹时,你会感受到越来越大的阻力,以防止过度滚动超过bounceItemWidth
415
+ */
416
+ endBounceItemWidth?: number
417
+ }
418
+
419
+ export interface SwiperRef {
420
+ /**
421
+ * SwiperTo item of index
422
+ * @Android
423
+ * @iOS
424
+ * @Harmony
425
+ * @zh 滑动到指定索引的项目
426
+ */
427
+ swipeTo: (index: number, options?: SwipeToOptions) => void
428
+ /**
429
+ * Swiper to next item
430
+ * @Android
431
+ * @iOS
432
+ * @Harmony
433
+ * @zh 滑动到下一个项目
434
+ */
435
+ swipeNext: () => void
436
+ /**
437
+ * Swiper to previous item
438
+ * @Android
439
+ * @iOS
440
+ * @Harmony
441
+ * @zh 滑动到上一个项目
442
+ */
443
+ swipePrev: () => void
444
+ /**
445
+ * Cancel Current Running Animation.
446
+ * Use with caution, may break internal states.
447
+ * @experimental
448
+ * @Android
449
+ * @iOS
450
+ * @Harmony
451
+ * @zh 取消当前正在运行的动画。谨慎使用,可能会破坏内部状态。
452
+ */
453
+ cancelAnimation: () => void
454
+ }
455
+
456
+ export interface onBounceParams {
457
+ type: 'start' | 'end'
458
+ offset: number
459
+ }
460
+
461
+ export interface RenderFunctionProps<T> {
462
+ item: T
463
+ index: number
464
+ realIndex: number
465
+ }
@@ -0,0 +1,105 @@
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 { CSSProperties, MainThread } from '@lynx-js/types'
6
+
7
+ import type {
8
+ BounceConfig,
9
+ SwipeToOptions,
10
+ SwiperPropsReal as SwiperProps,
11
+ SwiperRef,
12
+ onBounceParams,
13
+ } from './index.docs'
14
+
15
+ export interface SwiperContextProps extends
16
+ Pick<
17
+ SwiperProps<unknown>,
18
+ 'itemWidth' | 'itemHeight' | 'customAnimationFirstScreen' | 'RTL'
19
+ >,
20
+ Required<Pick<SwiperProps<unknown>, 'initialIndex' | 'loop'>>
21
+ {
22
+ setChildrenRef: (ref: MainThread.Element, index: number) => void
23
+ spaceBetween: number
24
+ modeConfig: CompoundModeConfig
25
+ }
26
+
27
+ export interface CompoundNormalModeConfig {
28
+ mode: 'normal'
29
+ align: 'start' | 'center' | 'end'
30
+ }
31
+
32
+ export interface CompoundCustomModeConfig {
33
+ mode: 'custom'
34
+ }
35
+
36
+ export type CompoundModeConfig =
37
+ | CompoundNormalModeConfig
38
+ | CompoundCustomModeConfig
39
+
40
+ export type customAnimation = (
41
+ progress: number,
42
+ props: SwiperProps<unknown>,
43
+ ) => CSSProperties
44
+
45
+ export interface CustomTouch {
46
+ identifier: number
47
+ pageX: number
48
+ pageY: number
49
+ clientX: number
50
+ clientY: number
51
+ x: number
52
+ y: number
53
+ }
54
+
55
+ /**
56
+ * Rewrite forwardRef to make it supports generic
57
+ * see: https://stackoverflow.com/questions/58469229/react-with-typescript-generics-while-using-react-forwardref
58
+ */
59
+ declare module 'react' {
60
+ // biome-ignore lint/complexity/noBannedTypes: Expected
61
+ function forwardRef<T, P = {}>(
62
+ render: (props: P, ref: React.Ref<T>) => React.ReactElement | null,
63
+ ): (props: P & React.RefAttributes<T>) => React.ReactElement | null
64
+ }
65
+
66
+ declare module '@lynx-js/types' {
67
+ interface GlobalProps {
68
+ screenWidth: number
69
+ }
70
+ }
71
+
72
+ export interface ResetOptions {
73
+ fullReset?: boolean
74
+ resetIndex?: number
75
+ }
76
+
77
+ export interface UpdateSwiperInnerContainerOptions {
78
+ itemWidth: number
79
+ loopDuplicateCount: number
80
+ loop: boolean
81
+ dataCount: number
82
+ spaceBetween: number
83
+ itemHeight: SwiperProps<unknown>['itemHeight']
84
+ mode: CompoundModeConfig['mode']
85
+ }
86
+
87
+ export enum SwipeDirection {
88
+ NORMAL = -1,
89
+ NONE = 0,
90
+ REVERT = 1,
91
+ }
92
+
93
+ export interface OffsetLimitResult {
94
+ startLimit: number
95
+ endLimit: number
96
+ isNotEnoughForScreen: boolean
97
+ }
98
+
99
+ export type {
100
+ BounceConfig,
101
+ SwiperRef,
102
+ onBounceParams,
103
+ SwipeToOptions,
104
+ SwiperProps,
105
+ }
@@ -0,0 +1,49 @@
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 function animate(
6
+ duration: number,
7
+ onUpdate: (progress: number) => void,
8
+ onFinished?: () => void,
9
+ ) {
10
+ 'main thread'
11
+ let startTs = 0
12
+ let rafId = 0
13
+
14
+ function tick(ts: number) {
15
+ const progress = Math.max(
16
+ Math.min(((ts - startTs) * 100) / duration, 100),
17
+ 0,
18
+ )
19
+
20
+ onUpdate(progress)
21
+ }
22
+
23
+ function updateRafId(id: number) {
24
+ rafId = id
25
+ }
26
+
27
+ function step(ts: number) {
28
+ if (!startTs) {
29
+ startTs = Number(ts)
30
+ }
31
+ // make sure progress can reach 100%
32
+ if (ts - startTs <= duration + 100) {
33
+ tick(ts)
34
+ updateRafId(requestAnimationFrame(step))
35
+ } else {
36
+ onFinished?.()
37
+ }
38
+ }
39
+
40
+ updateRafId(requestAnimationFrame(step))
41
+
42
+ function cancel() {
43
+ cancelAnimationFrame(rafId)
44
+ }
45
+
46
+ return {
47
+ cancel,
48
+ }
49
+ }
@@ -0,0 +1,54 @@
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
+ type DeepObject = Record<string, unknown>
6
+
7
+ export function comparePropsWithObject(
8
+ prev: unknown,
9
+ next: unknown,
10
+ objectKeys?: string[],
11
+ ): boolean {
12
+ if (prev === next) {
13
+ return true
14
+ }
15
+
16
+ if (
17
+ typeof prev !== 'object' || typeof next !== 'object' || prev === null
18
+ || next === null
19
+ ) {
20
+ return false
21
+ }
22
+
23
+ const prevKeys = Object.keys(prev as DeepObject)
24
+ const nextKeys = Object.keys(next as DeepObject)
25
+
26
+ if (prevKeys.length !== nextKeys.length) {
27
+ return false
28
+ }
29
+
30
+ for (const key of prevKeys) {
31
+ if (objectKeys?.includes(key)) {
32
+ if (
33
+ !comparePropsWithObject(
34
+ (prev as DeepObject)[key],
35
+ (next as DeepObject)[key],
36
+ [],
37
+ )
38
+ ) {
39
+ return false
40
+ }
41
+ } else {
42
+ if (
43
+ !Object.is(
44
+ (prev as DeepObject)[key],
45
+ (next as DeepObject)[key],
46
+ )
47
+ ) {
48
+ return false
49
+ }
50
+ }
51
+ }
52
+
53
+ return true
54
+ }
@@ -0,0 +1,23 @@
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
+ /**
6
+ * Round with threshold other than 0.5
7
+ * eg: customRound(1.8, 0.7) === 2
8
+ * eg: customRound(1.6, 0.7) === 1
9
+ * @param num
10
+ * @param threshold
11
+ * @returns number
12
+ */
13
+ export function customRound(num: number, threshold = 0.5) {
14
+ 'main thread'
15
+ const decimal = num - Math.floor(num)
16
+
17
+ // Check if the decimal part is greater than or equal to 0.9
18
+ if (decimal >= threshold) {
19
+ return Math.ceil(num)
20
+ } else {
21
+ return Math.floor(num)
22
+ }
23
+ }