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/tab-group.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • TabGroup

    用于通过 lynx-ui 构建标签导航的可组合 Tab 原语。此软件包提供 `TabsRoot`、`TabsBar`、`TabsItem`、`TabsIndicator`,以及可选的可滑动 `TabsPanel`。
    Info

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

    基础用法

    基于数据渲染自定义标签项、同步内容、选中状态和指示器。

    示例

    面板

    将标签栏与可滑动的数据驱动内容面板连接起来。

    命令式选择

    通过 ref 以平滑或立即移动的方式选中标签。

    结构

    <TabsRoot>
      <TabsBar
        data={tabs}
        renderTabItem={(tab, index) => <TabsItem />}
      >
        <TabsIndicator />
      </TabsBar>
      <TabsPanel data={panels}>
        {(panel, index) => <PanelContent />}
      </TabsPanel>
    </TabsRoot>

    组件 API

    TabsRoot

    Properties
    childreniOSAndroidHarmony
    类型ReactNode
    子节点
    debugLogiOSAndroidHarmony
    类型boolean·默认值false
    显示调试日志。当您发现错误时,请打开此选项。
    enableRTLiOSAndroidHarmony
    类型boolean·默认值false
    开启 RTL 布局。
    indicatorAnimationiOSAndroidHarmony
    类型TabsIndicatorAnimation·默认值{ type: 'spring', stiffness: 300, damping: 30, mass: 1 }
    切换标签时指示器的动画配置。
    initialSelectIndexiOSAndroid
    类型number·默认值0
    指定初始显示的索引。请使用 selectTab 进行其他更新。
    selectBehavioriOSAndroid
    类型smooth | instant·默认值'smooth'
    控制选中标签时标签栏的滚动方式与指示器的移动方式。'smooth' 表示动画过渡,'instant' 表示直接跳转。
    Events
    onClickItemiOSAndroid
    类型(index: number) => void
    点击回调
    onTabChangediOSAndroid
    类型(index: number) => void
    标签页更改回调

    TabsBar

    Properties
    androidTouchSlopAndroid
    类型default | paging
    Android 触摸识别模式,当处于支持 'paging' 模式的元件中时,需要开启 'paging' 模式。
    bounceableiOSAndroid
    类型boolean
    启用弹性效果
    bounceableOptionsiOSAndroid
    类型boolean | {alwaysBouncing?: boolean, enableBounceEventInFling?: boolean, enableBounces: boolean, endBounceTriggerDistance?: number, estimatedHeight?: number, estimatedWidth?: number, lowerBounceItem?: any, onScrollToBounces?: (e: ScrollToBouncesInfo) => void, singleSidedBounce?: upper | lower | both | iOSBounces | none, startBounceTriggerDistance?: number, upperBounceItem?: any, validAnimationVersion?: boolean}·默认值{ enableBounces: true, singleSidedBounce: "iOSBounces" },
    弹性效果的参数
    childreniOSAndroidHarmony
    类型ReactNode
    子节点
    classNameiOSAndroidHarmony
    类型string
    类名
    dataiOSAndroidHarmony
    类型T[]
    Tabs 的数据。
    debugLogiOSAndroidHarmony
    类型boolean·默认值false
    显示回弹交互的调试日志。
    enableNewArchiOSAndroidHarmony
    类型boolean·默认值true on Lynx SDK >= 4.3; false otherwise
    启用原生 <scroll-view> 新架构。启用后,bounceableOptions 会在 Android、iOS 和 Harmony 上使用原生回弹。Lynx SDK 4.3 及以上版本默认为 true,更早版本默认为 false。
    enableRTLiOSAndroidHarmony
    类型boolean·默认值false
    是否在 RTL 模式下镜像水平回弹方向。
    enableScrolliOSAndroidHarmony
    类型boolean·默认值true
    启用滚动。
    enableScrollMonitoriOSAndroidHarmony
    类型boolean·默认值false
    启用滚动监控。
    estimatedItemStyleiOSAndroid
    类型CSSProperties
    需要设置 items 的预计高度和宽度。
    experimentalNestedScrollBackwardHarmony
    类型selfOnly | selfFirst | parentFirst | parallel
    适配 Harmony 的嵌套滚动行为。'selfOnly' 表示只自身滚动,不与父组件联动。'selfFirst' 表示自身先滚动,自身滚动到边界以后父组件滚动。'parentFirst' 表示父组件先滚动,父组件滚动到边界以后自身滚动。'parallel' 表示自身和父组件同时滚动。
    experimentalNestedScrollForwardHarmony
    类型selfOnly | selfFirst | parentFirst | parallel
    适配 Harmony 的嵌套滚动行为。'selfOnly' 表示只自身滚动,不与父组件联动。'selfFirst' 表示自身先滚动,自身滚动到边界以后父组件滚动。'parentFirst' 表示父组件先滚动,父组件滚动到边界以后自身滚动。'parallel' 表示自身和父组件同时滚动。
    exposureBottomiOSAndroid
    类型string·默认值'10px'
    曝光屏幕下方边距
    exposureIDiOSAndroidHarmony
    类型string
    用于全局曝光的 exposure-id
    exposureLeftiOSAndroid
    类型string·默认值'10px'
    曝光屏幕左侧边距
    exposureRightiOSAndroid
    类型string·默认值'10px'
    曝光屏幕右侧边距
    exposureSceneiOSAndroidHarmony
    类型string
    用于全局曝光的 exposure-scene
    exposureTopiOSAndroid
    类型string·默认值'10px'
    曝光屏幕上方边距
    firstScreenItemCountiOSAndroid
    类型number·默认值1
    懒加载时预计的第一页项数。剩余的子元素会基于曝光状态完成渲染。当此预估较小时,可能会导致第一屏出现空白现象。
    getTabKeyiOSAndroidHarmony
    类型(tabItem: T, index: number) => string
    返回每个 Tab 的稳定唯一键。省略时使用索引;当标签可能插入、删除或重排时请提供此函数。
    iOSBouncesiOSAndroid
    类型boolean·默认值true
    开启iOS上的回弹效果。如果想在安卓上使用,请参考bounceableOption。如果设置了bounceableOption,iOSBounces属性将失效。
    lazyiOSAndroid
    类型boolean·默认值true
    启用懒渲染。只有当用户滚动到可见区域时,才会渲染 items,从而减少初始加载时间和内存使用。
    lazyOptionsiOSAndroid
    类型LazyOptions·默认值true
    启用懒渲染。只有当用户滚动到可见区域时,才会渲染 items,从而减少初始加载时间和内存使用。
    main-thread:gestureiOSAndroid
    类型BaseGesture<BaseGestureConfig, GestureChangeEvent>
    如果想使用 gesture API,请传入该属性。
    onUIAppeariOSAndroidHarmony
    类型(e: CommonEvent) => void
    UI 的曝光事件。
    onUIDisappeariOSAndroidHarmony
    类型(e: CommonEvent) => void
    UI 的消失事件。
    renderTabItemiOSAndroidHarmony
    类型(tabItem: T, index: number) => ReactNode
    渲染每个 Tab 项。TabsItem 会自动从 TabsBar 读取其键。
    sceneiOSAndroid
    类型string
    用于标记懒加载的曝光时机。请确保页面中唯一。
    scrollMonitorTagiOSAndroidHarmony
    类型string·默认值false
    滚动监控的标签。
    scrollPropagationBehavioriOSAndroid
    类型ScrollPropagationBehaviorOption·默认值'native'
    控制滚动事件是否向父级容器传递。'preventPropagate' 在 iOS 上暂时需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 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.
    scrollviewIdiOSAndroid
    类型string·默认值"scrollview"
    滚动视图的id。
    stickyiOSAndroid
    类型ReactElement<any, string | JSXElementConstructor<any>>
    粘性元素,设计用于 Tabs。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    tabsItemWrapperClassiOSAndroid
    类型string
    应用于 scroll-view 内子视图的内部容器的类名。
    temporaryBlockScrollClassiOS
    类型string·默认值'BDXLynxViewPager'
    当 scrollPropagationBehavior 设为 'preventPropagate' 时,被阻止滚动的容器的具体类名。'preventPropagate' 需与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 This is a temporary props and will be deprecated on new Lynx SDK version.
    temporaryBlockScrollTagiOS
    类型number·默认值0
    用于指定当 scrollPropagationBehavior 设为 'preventPropagate' 时被阻止滚动的原生容器标签(对应 UIView 的 Tag 属性)。该值需由原生容器提供方指定,且 'preventPropagate' 必须与 temporaryBlockScrollClass 和 temporaryBlockScrollTag 配合使用。 This is a temporary props and will be deprecated on new Lynx SDK version.
    temporaryNestedScrollAndroid
    类型boolean
    仅 Android 生效的临时开关,用于控制嵌套滚动冲突;映射到原生属性 'enable-nested-scroll'。Android上默认开启。
    testingiOSAndroid
    类型boolean
    测试模式
    Events
    catchLongPressiOSAndroidHarmony
    类型(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    与 onLongPress 相同,但会阻止事件冒泡。
    catchTouchCanceliOSAndroidHarmony
    类型(e: TouchEvent) => void
    与 onTouchCancel 相同,但会阻止事件冒泡。
    catchTouchEndiOSAndroidHarmony
    类型(e: TouchEvent) => void
    与 onTouchEnd 相同,但会阻止事件冒泡。
    catchTouchMoveiOSAndroidHarmony
    类型(e: TouchEvent) => void
    与 onTouchMove 相同,但会阻止事件冒泡。
    catchTouchStartiOSAndroidHarmony
    类型(e: TouchEvent) => void
    与 onTouchStart 相同,但会阻止事件冒泡。
    onContentSizeChangeiOSAndroid
    类型(res: {detail: {scrollHeight: number, scrollWidth: number}}) => void
    滚动内容变化时触发。
    onLayoutChangeiOSAndroidHarmony
    类型(e: EventHandler<LayoutChangeDetailEvent<Target>> | undefined) => void
    当 UI 视口大小改变时发送。
    onLongPressiOSAndroidHarmony
    类型(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    当触摸点在 UI 上按住一段时间后发送。
    onScrolliOSAndroid
    类型(e: ScrollEvent) => void
    滚动时触发。
    onScrollEndiOSAndroid
    类型(e: ScrollEndEvent) => void·默认值undefined
    滚动停止时触发。
    onScrollToLoweriOSAndroid
    类型(e: ScrollToLowerEvent) => void·默认值undefined
    滚动到底部时触发。
    onScrollToUpperiOSAndroid
    类型(e: ScrollToUpperEvent) => void·默认值undefined
    滚动到顶部时触发。
    onTapiOSAndroidHarmony
    类型(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    当触摸点在 UI 上轻触时发送。
    onTouchCanceliOSAndroidHarmony
    类型(e: TouchEvent) => void
    当触摸事件在完成前被中断或取消时发送。
    onTouchEndiOSAndroidHarmony
    类型(e: TouchEvent) => void
    当触摸点从 UI 上移除时发送。
    onTouchMoveiOSAndroidHarmony
    类型(e: TouchEvent) => void
    当触摸点在 UI 上移动时发送。
    onTouchStartiOSAndroidHarmony
    类型(e: TouchEvent) => void
    当触摸点放置在 UI 上时发送。
    onWheel
    类型(e: CommonEvent) => void
    当 scroll-view 触发滚轮事件时发送。

    TabsItem

    childreniOSAndroidHarmony
    类型ReactNode
    标签项的内容。
    classNameiOSAndroidHarmony
    类型string
    类名
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    tabKeyiOSAndroidHarmony
    类型string
    renderTabItem 渲染的 Tab 项会自动从 TabsBar 获取此键。手动渲染时需提供与数据对应的键。

    TabsPanel

    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 根节点的标识符。
    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, children | className | style | id | bounces | ref | initial-select-index | align-width | enable-scroll | allow-horizontal-gesture | keep-item-view | bindchange | bindwillchange | bindoffsetchange | main-thread:bindchange | main-thread:bindwillchange | main-thread:bindoffsetchange>
    组件未管理的原生分页器属性。

    TabsIndicator

    childreniOSAndroidHarmony
    类型ReactNode
    子节点
    classNameiOSAndroidHarmony
    类型string
    类名
    indicatorPropsiOSAndroidHarmony
    类型StandardProps
    TabsIndicator 的原始属性。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式

    TabsRootRef

    selectTab
    类型(index: number, smooth: boolean) => void

    辅助类型

    TabsIndicatorAnimation

    TabsIndicatorAnimation
    类型TabsIndicatorAnimationSpring | TabsIndicatorAnimationTween

    TabsIndicatorAnimationSpring

    damping
    类型number
    指示器动画的弹簧阻尼。
    mass
    类型number
    指示器动画的弹簧质量。
    stiffness
    类型number
    指示器动画的弹簧刚度。
    type
    类型"spring"
    使用弹簧过渡驱动指示器动画。
    velocity
    类型number
    弹簧动画的初始速度。

    TabsIndicatorAnimationTween

    duration
    类型number
    补间动画时长,单位为毫秒。
    ease
    类型(t: number) => number
    补间动画的缓动函数。
    type
    类型"tween"
    使用补间过渡驱动指示器动画。
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。