For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt, and this page is available as Markdown at /next/zh/ui/components/swiper.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • Swiper

    一个适用于 ReactLynx 的轮播组件,提供轮播分页和手势处理基础能力。
    Info

    你可以查看源码来了解它的运行原理,也欢迎大家提 MR 来丰富其能力。

    基础用法
    进阶用法

    基本用法

    常见分页内容优先使用 normal mode。明确设置 item 尺寸和容器尺寸,再用 onChange 将当前索引同步到指示器或页面状态。

    示例

    循环

    当首尾项目需要衔接时使用 loop mode。它适合推荐位、活动卡片或其他循环浏览内容,避免滑到边界时出现硬停顿。

    弹性反弹

    bounce 内容适合用于边界反馈或拉动加载。正常浏览时应保持隐藏,只在用户拖过边界时展示轻量状态。

    Custom

    当 slide 需要持续响应滑动进度时,使用 custom mode。把进度值映射到 translate、scale 和 rotate 等 transform,就可以构建卡片堆叠交互。

    你可以查看进阶用法 了解更多

    结构

    <Swiper>
      {({ index }) => <SwiperItem />}
    </Swiper>

    组件 API

    Swiper

    autoPlayiOSAndroidHarmony
    类型boolean·默认值false
    是否启用自动播放
    autoPlayIntervaliOSAndroidHarmony
    类型number·默认值2000
    自动播放间隔
    blockNativeEventiOSAndroidHarmony
    类型boolean·默认值false
    是否阻止原生事件。当Swiper在Scrollview、List或其他会阻止Swiper触摸事件的组件中时可能有用。
    bounceConfigiOSAndroidHarmony
    类型BounceConfig
    回弹参数配置
    childreniOSAndroidHarmony
    类型(prop: {index: number, item: T, realIndex: number}) => ReactElement
    Swiper的子元素应该是一个函数,返回一个SwiperItem
    consumeSlideEventiOSAndroidHarmony
    类型[number, number][]·默认值[[-180, -135], [-45, 45], [135, 180]]
    决定Swiper如何响应不同角度的触摸。默认情况下,Swiper只会响应水平方向的触摸。更多信息请参考 https://lynxjs.org/zh/api/elements/built-in/view.html#consume-slide-event
    containerWidthiOSAndroidHarmony
    类型number·默认值lynx.__globalProps.screenWidth ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio
    轮播图视口的宽度,单位为px。使用时必须显式传入父容器内的可用宽度。例如,父容器与屏幕等宽且左右各有16px内边距时,将containerWidth设置为screenWidth - 32。
    customAnimationFirstScreeniOSAndroidHarmony
    类型(value: number, index: number) => CSSProperties
    在JS中使用的自定义动画效果,应该是一个JS函数。customAnimationFirstScreen应该是与'main-thread:customAnimation'内容相同的函数,但不带'main thread'注解。这是对MainThreadScript不支持首屏的临时解决方案。我们正在努力移除重复的JS版本的customAnimation。目前这是必需的。
    dataiOSAndroidHarmony
    类型T[]
    轮播图数据集合
    durationiOSAndroidHarmony
    类型number·默认值500
    翻页或滑动动画的持续时间
    initialIndexiOSAndroidHarmony
    类型number·默认值0
    Swiper的初始索引,该值仅在首屏时使用。后续更新将被忽略。
    itemHeightiOSAndroidHarmony
    类型number | auto
    轮播图项高度
    itemWidthiOSAndroidHarmony
    类型number
    轮播图项宽度
    loopiOSAndroidHarmony
    类型boolean·默认值false
    是否开启循环轮播
    loopDuplicateCountiOSAndroidHarmony
    类型number·默认值2
    当loop为true时,Swiper会复制前2个和后2个项目来创建循环效果。此属性可用于自定义复制第一个和最后一个项目的数量。
    main-thread:customAnimationiOSAndroidHarmony
    类型(value: number, index: number) => CSSProperties
    自定义动画效果,应该是一个主线程函数
    main-thread:easingiOSAndroidHarmony
    类型(progress: number) => number
    自定义翻页效果的缓动函数
    main-thread:onOffsetChangeiOSAndroidHarmony
    类型(offset: number) => void
    Swiper偏移量改变时的回调函数。应该是一个主线程函数
    offsetLimitiOSAndroidHarmony
    类型[number, number]
    用于限制或扩展Swiper的偏移量范围。可用于限制偏移量以避免过度滚动。例如,当mode === 'normal'且modeConfig.align === 'start'时,滑动到最后一个项目技术上意味着最后一个项目的左边缘与容器的左边缘对齐,留下空白区域,这通常不是我们想要的。因此我们添加了offsetLimit为[0, containerWidth - itemWidth],来限制Swiper的偏移量。在这种情况下,当滑动到末尾时,最后一个项目的右边缘与容器的右边缘对齐,不会留下空白区域。
    onChangeiOSAndroidHarmony
    类型(current: number) => void
    当前索引改变时的回调函数
    onSwipeStartiOSAndroidHarmony
    类型(current: number) => void
    开始滑动时的回调函数。可与onSwipeStop配合使用。用于在滑动时禁用点击事件。
    onSwipeStopiOSAndroidHarmony
    类型(current: number) => void
    停止滑动时的回调函数。可与onSwipeStart配合使用。用于在滑动时禁用点击事件。
    resetOnReuseiOSAndroidHarmony
    类型boolean·默认值false
    在重用Swiper组件时是否重置Swiper的进度和状态。
    RTLiOSAndroidHarmony
    类型boolean | lynx-rtl·默认值false
    是否启用RTL模式。
    styleiOSAndroidHarmony
    类型CSSProperties
    Swiper组件根元素的样式,用于背景、边框、圆角和溢出等。尺寸通过containerWidth和itemHeight配置,方向通过RTL配置。外层内边距和CSS类放在包裹view上。
    swiperKeyiOSAndroidHarmony
    类型unknown
    Swiper组件的key。更改此值将重置Swiper的进度和状态。可在重用Swiper组件时使用。重置时,将再次使用initialIndex。
    trackStyleiOSAndroidHarmony
    类型CSSProperties
    包含所有轮播项的内部滑动轨道的样式。这是实际移动/滑动的元素。

    SwiperItem

    childreniOSAndroidHarmony
    类型ReactElement<any, string | JSXElementConstructor<any>> | ReactElement<any, string | JSXElementConstructor<any>>[]
    Children of SwiperItem
    indexiOSAndroidHarmony
    类型number
    Index of current SwiperItem, out of Swiper's data.
    overlapiOSAndroidHarmony
    类型boolean
    应用到SwiperItem自身渲染的view上的overlap属性,用于处理透明度渲染问题。
    realIndexiOSAndroidHarmony
    类型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.
    styleiOSAndroidHarmony
    类型CSSProperties
    Style of SwiperItem

    SwiperRef

    cancelAnimationiOSAndroidHarmony
    类型() => void
    取消当前正在运行的动画。谨慎使用,可能会破坏内部状态。
    swipeNextiOSAndroidHarmony
    类型() => void
    滑动到下一个项目
    swipePreviOSAndroidHarmony
    类型() => void
    滑动到上一个项目
    swipeToiOSAndroidHarmony
    类型(index: number, options?: {animate?: boolean, onFinished?: () => void}) => void
    滑动到指定索引的项目

    辅助类型

    RenderFunctionProps

    index
    类型number
    当前 SwiperItem 在 Swiper 数据中的逻辑索引。
    item
    类型T
    当前 SwiperItem 对应的数据项。
    realIndex
    类型number
    当前 SwiperItem 的物理索引,为兼容已有手动传参用法保留。SwiperItem 在 Swiper 的 children 函数内渲染时会自动获取该值。

    BounceConfig

    enableiOSAndroidHarmony
    类型boolean·默认值false
    是否启用回弹效果。当loop为true时忽略此设置。
    endBounceItemiOSAndroidHarmony
    类型ReactElement<any, string | JSXElementConstructor<any>>
    右侧回弹项(水平方向时)
    endBounceItemWidthiOSAndroidHarmony
    类型number·默认值50
    回弹项的宽度。当过度滚动回弹时,你会感受到越来越大的阻力,以防止过度滚动超过bounceItemWidth
    onEndBounceItemBounceiOSAndroidHarmony
    类型(bounceParams: {offset: number, type: 'start' | 'end'}) => void
    当endBounceItem处于回弹状态时,释放手指将调用此函数。
    onStartBounceItemBounceiOSAndroidHarmony
    类型(bounceParams: {offset: number, type: 'start' | 'end'}) => void
    当startBounceItem处于回弹状态时,释放手指将调用此函数。
    startBounceItemiOSAndroidHarmony
    类型ReactElement<any, string | JSXElementConstructor<any>>
    左侧回弹项(水平方向时)
    startBounceItemWidthiOSAndroidHarmony
    类型number·默认值50
    回弹项的宽度。当过度滚动回弹时,你会感受到越来越大的阻力,以防止过度滚动超过bounceItemWidth

    OnBounceParams

    offset
    类型number
    type
    类型start | end

    SwipeToOptions

    animate
    类型boolean
    onFinished
    类型() => void

    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.

    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。