导航类 · Tabs
标签栏
当内容需要分组并在不同模块页面中展示,可使用 Tabs 标签栏目对不同的组/页之间进行切换

代码演示

如何引入

基本用法

标签栏支持三种样式的显示:线条式,按钮式,卡片式。默认选中第一项。
标签页支持两种传入方式,两者渲染流程上有所区别:
  • 通过 tabList 传入标签页对象的数组,当使用 tabList 时每次只渲染当前传入的节点
  • 或使用 <TabPane> 逐项显式传入,使用 <TabPane> 时默认会渲染所有面板,可以通过设置 keepDOM={false} 只渲染当前面板,此时不会有动画效果。
注意事项
1. tabList 与 TabPane Children 同时使用时,会优先渲染通过 tabList 传入的数据。不建议同时配置
2. 使用 TabPane Children 时, TabPane 必须为 Tabs 的直接子元素,否则 Tabs 将无法正确收集子组件如 itemKey 等相关属性

带图标的

有图标的标签栏。

垂直的标签栏

支持水平和垂直两种模式, tabPosition='left|top'

滚动折叠

v>= 1.1.0
通过设置 collapsible 可以支持滚动折叠,目前只支持 horizontal 模式。

禁用

禁用标签栏中的某一个标签页。

标签栏内容扩展

传入 tabBarExtraContent 属性可以在标签栏右侧添加附加操作。

标签栏二次封装

传入 renderTabBar 函数可对标签栏进行二次封装。

动态更新

通过绑定事件,可以使标签栏动态更新。

关闭

关闭标签栏中的某一个标签页。
只有卡片样式的页签支持关闭选项。使用 closable={true} 来开启。

API 参考

Tab

属性说明类型默认值
activeKey当前激活的 tab 页的 itemKey 值string
className类名string
collapsible折叠的 Tabs,>=1.1.0booleanfalse
contentStyle内容区域外层样式对象CSSProperties
defaultActiveKey初始化选中的 tab 页的 key 值string'1'
keepDOM使用 TabPane 写法时是否渲染隐藏面板的 DOM 结构,>=1.0.0booleantrue
lazyRender懒渲染,仅当面板激活过才被渲染在 DOM 树中, >=1.0.0booleanfalse
renderTabBar用于二次封装标签栏(tabBarProps: object, defaultTabBar: React.ComponentType) => ReactNode
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean
size大小,提供 largemediumsmall 三种类型,>=1.11.0,目前仅支持线性 Tabsstringlarge
style样式对象CSSProperties
tabBarExtraContent用于扩展标签栏的内容ReactNode
tabList标签页对象组成的数组,该对象支持 itemKey(对应 activeKey,tab(标签页文字)及 icon(标签页图标)TabPane[]
tabPaneMotion是否使用动画切换 tabsbooleantrue
tabPositiontab 的位置,支持top(水平), left(垂直),>=1.0.0stringtop
type标签栏的样式,可选linecardbuttonstringline
onChange切换 tab 页时的回调函数function(activeKey: string)
onTabClick单击事件function(key: string, e: Event)
onTabClose关闭 tab 页时的回调函数 >=2.1.0function(tabKey: string)

TabPane

属性说明类型默认值
className类名string
disabled标签页栏是否禁用boolean
icon标签页栏 iconReactNode
itemKey对应 activeKeystring
style样式对象CSSProperties
tab标签页栏显示文字ReactNode
closable允许关闭tab >=2.1.0booleanfalse

Accessibility

ARIA

  • 关于 role
    • TabBar 对应的 role 为 tablist
    • TabBar 中的 Tab 对应的 role 为 tab
    • TabPane 对应的 role 为 tabpanel
  • aria-orientation: 表明 TabBar 的方向,有 verticalhorizontal 两种。当传入 tabPosition 为 left 时, aria-orientation 会被设置为 vertical,tabPosition 为 top 时,设置为 horizontal
  • aria-disabled: 当 TabPane 设置为 disabled 时,对应 Tab 的 aria-disabled 会被设置为 true
  • aria-selected: 表明 Tab 是否被选中
  • aria-controls: 指向 Tab 标签所控制的 TabPane
  • aria-labelledby: 指向设置 TabPane 标签的元素

键盘和焦点

  • 选项卡可以被获取到焦点,但禁用的选项卡除外
  • 键盘用户可以使用 Tab 键,将焦点移动到已被选择的选项卡元素的选项卡面板上
  • 当焦点位于水平选项卡列表中的选项卡元素上时,使用 左右箭头 来切换选项
  • 当焦点位于垂直选项卡列表中的选项卡元素上时,使用 上下箭头 来切换选项
  • 当焦点位于选项卡列表中的未被激活的选项卡元素上时,可以使用 SpaceEnter 键来激活该选项卡
  • 当键盘用户想要直接将焦点聚焦到选项卡列表中的最后一个选项卡元素时:
    • Mac 用户:fn + 右箭头
    • Windows 用户:End
  • 当键盘用户想要直接将焦点聚焦到选项卡列表中的第一个选项卡元素时:
    • Mac 用户:fn + 左箭头
    • Windows 用户:Home
  • 当选项卡允许被删除时:
    • 用户可以使用 Delete 键删除选项卡
    • 删除后,焦点转移到被删除选项卡元素的后一个元素上;若被删除元素无后一个元素则转移到前一个元素上

设计变量

文案规范

  • 标签文案需要准确清晰地解释标签内容
  • 用简短的,易区分的标签
  • 尽量保持在一个词以内

FAQ

  • 为什么在Tabs中使用 Typography 的省略 ellipsis 失效?
    因为Tabs渲染TabPane时,默认是全部渲染display: none。此时这些组件无法获取到正确的宽度或高度值。建议1.x的版本开启lazyRender,或者关闭keepDOM。0.x的版本需要使用tabList的写法。
  • 为什么在Tabs中使用Collapse/Collapsible/Resizable Table等组件的高度或宽度值不对?
    原因同上,另外如果 collapse 不需要动画,也可以通过设置 motion={false} 来关闭动画效果。此时无需获取组件的高度。