基本用法
常见分页内容优先使用 normal mode。明确设置 item 尺寸和容器尺寸,再用 onChange 将当前索引同步到指示器或页面状态。
示例
循环
当首尾项目需要衔接时使用 loop mode。它适合推荐位、活动卡片或其他循环浏览内容,避免滑到边界时出现硬停顿。
弹性反弹
bounce 内容适合用于边界反馈或拉动加载。正常浏览时应保持隐藏,只在用户拖过边界时展示轻量状态。
Custom
当 slide 需要持续响应滑动进度时,使用 custom mode。把进度值映射到 translate、scale 和 rotate 等 transform,就可以构建卡片堆叠交互。
你可以查看进阶用法 了解更多
结构
<Swiper>
{({ index }) => <SwiperItem />}
</Swiper>
组件 API
Swiper
类型boolean·默认值false
是否启用自动播放
类型boolean·默认值false
是否阻止原生事件。当Swiper在Scrollview、List或其他会阻止Swiper触摸事件的组件中时可能有用。
类型(prop: {index: number, item: T, realIndex: number}) => ReactElement
Swiper的子元素应该是一个函数,返回一个SwiperItem
类型[number, number][]·默认值[[-180, -135], [-45, 45], [135, 180]]
决定Swiper如何响应不同角度的触摸。默认情况下,Swiper只会响应水平方向的触摸。更多信息请参考 https://lynxjs.org/zh/api/elements/built-in/view.html#consume-slide-event
类型number·默认值lynx.__globalProps.screenWidth ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio
轮播图视口的宽度,单位为px。使用时必须显式传入父容器内的可用宽度。例如,父容器与屏幕等宽且左右各有16px内边距时,将containerWidth设置为screenWidth - 32。
类型(value: number, index: number) => CSSProperties
在JS中使用的自定义动画效果,应该是一个JS函数。customAnimationFirstScreen应该是与'main-thread:customAnimation'内容相同的函数,但不带'main thread'注解。这是对MainThreadScript不支持首屏的临时解决方案。我们正在努力移除重复的JS版本的customAnimation。目前这是必需的。
类型number·默认值500
翻页或滑动动画的持续时间
类型number·默认值0
Swiper的初始索引,该值仅在首屏时使用。后续更新将被忽略。
类型boolean·默认值false
是否开启循环轮播
类型number·默认值2
当loop为true时,Swiper会复制前2个和后2个项目来创建循环效果。此属性可用于自定义复制第一个和最后一个项目的数量。
类型(value: number, index: number) => CSSProperties
自定义动画效果,应该是一个主线程函数
类型(progress: number) => number
自定义翻页效果的缓动函数
类型(offset: number) => void
Swiper偏移量改变时的回调函数。应该是一个主线程函数
类型[number, number]
用于限制或扩展Swiper的偏移量范围。可用于限制偏移量以避免过度滚动。例如,当mode === 'normal'且modeConfig.align === 'start'时,滑动到最后一个项目技术上意味着最后一个项目的左边缘与容器的左边缘对齐,留下空白区域,这通常不是我们想要的。因此我们添加了offsetLimit为[0, containerWidth - itemWidth],来限制Swiper的偏移量。在这种情况下,当滑动到末尾时,最后一个项目的右边缘与容器的右边缘对齐,不会留下空白区域。
类型(current: number) => void
当前索引改变时的回调函数
类型(current: number) => void
开始滑动时的回调函数。可与onSwipeStop配合使用。用于在滑动时禁用点击事件。
类型(current: number) => void
停止滑动时的回调函数。可与onSwipeStart配合使用。用于在滑动时禁用点击事件。
类型boolean·默认值false
在重用Swiper组件时是否重置Swiper的进度和状态。
类型boolean | lynx-rtl·默认值false
是否启用RTL模式。
类型CSSProperties
Swiper组件根元素的样式,用于背景、边框、圆角和溢出等。尺寸通过containerWidth和itemHeight配置,方向通过RTL配置。外层内边距和CSS类放在包裹view上。
类型unknown
Swiper组件的key。更改此值将重置Swiper的进度和状态。可在重用Swiper组件时使用。重置时,将再次使用initialIndex。
类型CSSProperties
包含所有轮播项的内部滑动轨道的样式。这是实际移动/滑动的元素。
SwiperItem
类型ReactElement<any, string | JSXElementConstructor<any>> | ReactElement<any, string | JSXElementConstructor<any>>[]
Children of SwiperItem
类型number
Index of current SwiperItem, out of Swiper's data.
类型boolean
应用到SwiperItem自身渲染的view上的overlap属性,用于处理透明度渲染问题。
类型number
Physical index of current SwiperItem.
Kept for compatibility with existing manual usage. This is resolved
automatically when SwiperItem is rendered inside Swiper's children function.
类型CSSProperties
Style of SwiperItem
SwiperRef
类型() => void
取消当前正在运行的动画。谨慎使用,可能会破坏内部状态。
类型(index: number, options?: {animate?: boolean, onFinished?: () => void}) => void
滑动到指定索引的项目
辅助类型
RenderFunctionProps
类型number
当前 SwiperItem 在 Swiper 数据中的逻辑索引。
类型number
当前 SwiperItem 的物理索引,为兼容已有手动传参用法保留。SwiperItem 在 Swiper 的 children 函数内渲染时会自动获取该值。
BounceConfig
类型boolean·默认值false
是否启用回弹效果。当loop为true时忽略此设置。
类型ReactElement<any, string | JSXElementConstructor<any>>
右侧回弹项(水平方向时)
类型number·默认值50
回弹项的宽度。当过度滚动回弹时,你会感受到越来越大的阻力,以防止过度滚动超过bounceItemWidth
类型(bounceParams: {offset: number, type: 'start' | 'end'}) => void
当endBounceItem处于回弹状态时,释放手指将调用此函数。
类型(bounceParams: {offset: number, type: 'start' | 'end'}) => void
当startBounceItem处于回弹状态时,释放手指将调用此函数。
类型ReactElement<any, string | JSXElementConstructor<any>>
左侧回弹项(水平方向时)
类型number·默认值50
回弹项的宽度。当过度滚动回弹时,你会感受到越来越大的阻力,以防止过度滚动超过bounceItemWidth
OnBounceParams
SwipeToOptions
Advanced Usage
Use the advanced APIs when the default slide layout is not enough. customAnimation
lets each item respond to swipe progress, while mode decides whether Swiper
places items for you or leaves placement to your animation function.
Understanding customAnimation
type customAnimation = (value: number, index: number) => CSSProperties
customAnimation is a main thread function. While Swiper is scrolling, each
SwiperItem receives its distance from the active item and returns the style it
should use for that frame.
The function parameter value represents the distance of this <SwiperItem> relative to the selected <SwiperItem>.
In this example, when <Swiper>'s progress is 2:
<SwiperItem>-2 receives a value of 0
<SwiperItem>-1 receives a value of -1
<SwiperItem>-3 receives a value of 1
Furthermore, when <Swiper>'s progress is updated to 3:
<SwiperItem>-2 receives a value of -1
<SwiperItem>-1 receives a value of -2
<SwiperItem>-3 receives a value of 0
Use this value as a stable input for interpolation. For example, 0 is the
active item, -1 is the previous item, and 1 is the next item.
Practice with customAnimation
This pattern is useful when Swiper should keep its normal layout but the items
need visual treatment such as scale, opacity, or rotation.
Understanding mode
<Swiper> supports two mode options: normal and custom. Their differences are as follows:
mode='normal'
-
<SwiperItem>s are arranged sequentially in the direction
-
Provides center alignment, right alignment, and other capabilities through modeConfig
mode='custom'
-
The position of <SwiperItem> needs to be specified through customAnimation
-
Offers higher customization capabilities
To summarize:
normal mode handles the position of <SwiperItem>s, making it more suitable for horizontal sliding scenarios and easier to use
custom mode requires manual position calculation but offers higher extensibility
Practice with customAnimation when mode='custom'
Use custom mode when item placement itself is part of the design. In this
mode, the animation function should return both position and visual style.