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/view-pager.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • ViewPager

    适用于 ReactLynx 的分页横向内容导航组件,支持屏外页面懒加载。
    Info

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

    基础用法

    基于数据渲染页面,并通过切换事件跟踪当前页。

    示例

    自动高度

    不显式设置高度,让页面内容决定分页器的自然高度。

    动态高度

    在不同高度的页面切换时,通过主线程连续插值分页器高度。

    懒渲染

    按曝光范围懒渲染页面,并通过命令式控件切换页面。

    嵌套列表

    组合横向分页与各自独立滚动的垂直列表。

    结构

    <ViewPager data={pages}>
      {(page, index) => <Page />}
    </ViewPager>

    组件 API

    ViewPager

    bouncesiOSAndroid
    类型boolean·默认值true
    在支持的平台启用原生回弹效果。
    childreniOSAndroid
    类型(item: T, index: number) => ReactNode
    渲染页面内容。此函数有意不传入选中状态,因此原生滑动无需让 React 重新渲染页面内容。
    classNameiOSAndroidHarmony
    类型string
    类名
    dataiOSAndroid
    类型readonly T[]
    页面数据。ViewPager 为每条数据创建一个直接的原生 viewpager-item 子节点。
    enableScrolliOSAndroid
    类型boolean·默认值true
    启用水平滑动手势。
    getItemKeyiOSAndroid
    类型(item: T, index: number) => string | number
    返回条目的稳定唯一键。不传时使用条目索引;当条目可能插入、删除或重排时请提供此函数。
    getItemPropsiOSAndroid
    类型(item: T, index: number) => ViewPagerItemProps
    单个自动生成条目的原生属性。类名与 itemClassName 合并;样式覆盖 itemStyle 的同名属性。条目的 key、ref 和 children 由 ViewPager 管理。
    idiOSAndroid
    类型string
    应用于原生 ViewPager 根节点的标识符。
    initialSelectIndexiOSAndroid
    类型number·默认值0
    初始页面索引,后续修改不生效。使用 ref.scrollToPage 切换页面。
    itemClassNameiOSAndroid
    类型string
    应用于每个自动生成的 viewpager-item 的类名。
    itemStyleiOSAndroid
    类型CSSProperties
    应用于每个自动生成的 viewpager-item 的样式。
    lazyOptionsiOSAndroid
    类型ViewPagerLazyOptions
    基于曝光的懒渲染。初始页面立即渲染,其他页面在占位节点进入配置的曝光区域时渲染;已渲染页面保持挂载。不传时渲染全部页面。
    main-thread:onOffsetChangeiOSAndroid
    类型(event: ViewPagerOffsetChangeEvent) => void
    主线程滚动进度回调,需使用主线程函数。
    main-thread:onPageChangeiOSAndroid
    类型(event: ViewPagerChangeEvent) => void
    主线程页面切换完成回调,需使用主线程函数。
    main-thread:onPageWillChangeiOSAndroid
    类型(event: ViewPagerWillChangeEvent) => void
    主线程页面即将切换回调,需使用主线程函数。
    onOffsetChangeiOSAndroid
    类型(event: ViewPagerOffsetChangeEvent) => void
    原生滚动进度事件,从 event.detail 读取数据。
    onPageChangeiOSAndroid
    类型(event: ViewPagerChangeEvent) => void
    原生页面切换完成事件,从 event.detail.index 读取选中索引。
    onPageWillChangeiOSAndroid
    类型(event: ViewPagerWillChangeEvent) => void
    原生页面切换完成前事件,从 event.detail 读取数据。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    viewpagerPropsiOSAndroid
    类型Omit<ViewPagerProps, style | ref | children | id | className | initial-select-index | align-width | enable-scroll | allow-horizontal-gesture | bounces | keep-item-view | bindchange | bindwillchange | bindoffsetchange | main-thread:bindchange | main-thread:bindwillchange | main-thread:bindoffsetchange>
    组件未管理的原生分页器属性。

    ViewPagerRef

    scrollToPageiOSAndroid
    类型(index: number, smooth?: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    通过原生节点引用切换页面,默认使用动画。索引限制在有效范围内,空列表忽略请求。onPageChange 表示切换完成,success 表示调用成功。

    辅助类型

    ViewPagerItemProps

    ViewPagerItemProps
    类型Omit<NativeViewPagerItemProps, key | ref | children | style> & {style?: unknown}

    ViewPagerExposureMargin

    ViewPagerExposureMargin
    类型px | rpx

    ViewPagerLazyOptions

    ViewPagerLazyOptions
    类型{enableLazy: false} | {enableLazy: true, exposureLeft?: ViewPagerExposureMargin, exposureRight?: ViewPagerExposureMargin, scene: string}
    禁用懒渲染。

    ViewPagerChangeEvent

    ViewPagerChangeEvent
    类型BaseEvent<"bindchange", ViewPagerChange>

    ViewPagerWillChangeEvent

    ViewPagerWillChangeEvent
    类型BaseEvent<"bindwillchange", ViewPagerChange>

    ViewPagerOffsetChangeEvent

    ViewPagerOffsetChangeEvent
    类型BaseEvent<"bindchange", ViewPagerOffsetChange>
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。