导航类 · Tabs
标签栏
当内容需要分组并在不同模块页面中展示,可使用 Tabs 标签栏目对不同的组/页之间进行切换
代码演示
如何引入
基本用法
标签栏支持三种样式的显示:线条式,按钮式,卡片式。默认选中第一项。
标签页支持两种传入方式,两者渲染流程上有所区别:
标签页支持两种传入方式,两者渲染流程上有所区别:
- 通过
tabList
传入标签页对象的数组,当使用tabList
时每次只渲染当前传入的节点 - 或使用
<TabPane>
逐项显式传入,使用<TabPane>
时默认会渲染所有面板,可以通过设置keepDOM={false}
只渲染当前面板,此时不会有动画效果。
带图标的
有图标的标签栏。
更多选项收入 More 展示
支持将多余 Tab 合并为 ”更多“ 下拉菜单,
more
传入数字即可,数字表示收入下拉菜单的 Tab 数量。(>=v2.59.0)也支持高级配置,向
more
传入对象,内可传入count
: 表示收入下拉菜单的 Tab 数量render
: 自定义 Trigger 的渲染函数,返回的 ReactNode 会被渲染为下拉菜单的 TriggerdropdownProps
: 传入 DropDown Props,会被透传到下拉菜单,如果需要自定义下拉菜单,使用 dropdownProps 中的 render 方法
垂直的标签栏
支持水平和垂直两种模式,
tabPosition='left|top'
滚动折叠
通过设置
collapsible
可以支持滚动折叠,目前只支持 horizontal 模式。自定义滚动箭头渲染
通过 renderArrow 修改滚动折叠模式下,左右切换箭头的渲染,入参为溢出的 items 和 位置
修改切换箭头的渲染位置
通过
arrowPosition
来修改溢出指示器的位置,可选 start
both
end
禁用
禁用标签栏中的某一个标签页。
标签栏内容扩展
传入
tabBarExtraContent
属性可以在标签栏右侧添加附加操作。标签栏二次封装
传入
renderTabBar
函数可对标签栏进行二次封装。动态更新
通过绑定事件,可以使标签栏动态更新。
关闭
关闭标签栏中的某一个标签页。
只有卡片样式的页签支持关闭选项。使用
只有卡片样式的页签支持关闭选项。使用
closable={true}
来开启。API 参考
Tab
属性 | 说明 | 类型 | 默认值 |
---|---|---|---|
activeKey | 当前激活的 tab 页的 itemKey 值 | string | 无 |
arrowPosition | 折叠模式下,左右切换箭头渲染位置 >=2.61.0 | "start" "end" "both" | 无 |
className | 类名 | string | 无 |
collapsible | 折叠的 Tabs,>=1.1.0 | boolean | false |
visibleTabsStyle | 整体滚动区域 Style >=2.61.0 | style: CSSProperties | 无 |
contentStyle | 内容区域外层样式对象 | CSSProperties | 无 |
defaultActiveKey | 初始化选中的 tab 页的 key 值 | string | '1' |
keepDOM | 使用 TabPane 写法时是否渲染隐藏面板的 DOM 结构 | boolean | true |
lazyRender | 懒渲染,仅当面板激活过才被渲染在 DOM 树中 | boolean | false |
more | 将一部分 Tab 渲染到下拉菜单中 >= 2.59.0 | number | {count:number,render:()=>ReactNode,dropdownProps:DropDownProps} | - |
renderTabBar | 用于二次封装标签栏 | (tabBarProps: object, defaultTabBar: React.ComponentType) => ReactNode | 无 |
renderArrow | 折叠滚动模式下,自定义左右切换箭头如何渲染,默认为箭头按钮 hover 时展开溢出项 >=2.61.0 | (items: OverflowItem[],pos:"start"|"end", handleArrowClick:()=>void)=> ReactNode | 无 |
preventScroll | 指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法 | boolean | |
showRestInDropdown | 是否将收起的 Tab 展示在下拉菜单中(仅当 collapsible 为 true 时生效) >= 2.61.0 | boolean | true |
size | 大小,提供 large 、medium 、small 三种类型,>=1.11.0,目前仅支持线性 Tabs | string | large |
style | 样式对象 | CSSProperties | 无 |
tabBarExtraContent | 用于扩展标签栏的内容 | ReactNode | 无 |
tabList | 标签页对象组成的数组,该对象支持 itemKey(对应 activeKey,tab(标签页文字)及 icon(标签页图标) | TabPane[] | 无 |
tabPaneMotion | 是否使用动画切换 tabs | boolean | true |
tabPosition | tab 的位置,支持top (水平), left (垂直) | string | top |
type | 标签栏的样式,可选line 、 card 、 button | string | line |
onChange | 切换 tab 页时的回调函数 | function(activeKey: string) | 无 |
onTabClick | 单击事件 | function(key: string, e: Event) | 无 |
onTabClose | 关闭 tab 页时的回调函数 >=2.1.0 | function(tabKey: string) | 无 |
onVisibleTabsChange | 折叠滚动模式下,溢出项切换变化回调 >= 2.61.0 | (visibleState:Record\<string,bool>)=>void | 无 |
TabPane
属性 | 说明 | 类型 | 默认值 |
---|---|---|---|
className | 类名 | string | 无 |
disabled | 标签页栏是否禁用 | boolean | 无 |
icon | 标签页栏 icon | ReactNode | 无 |
itemKey | 对应 activeKey | string | 无 |
style | 样式对象 | CSSProperties | 无 |
tab | 标签页栏显示文字 | ReactNode | 无 |
closable | 允许关闭 tab >=2.1.0 | boolean | false |
Accessibility
ARIA
- 关于 role
- TabBar 对应的 role 为
tablist
- TabBar 中的 Tab 对应的 role 为
tab
- TabPane 对应的 role 为
tabpanel
- TabBar 对应的 role 为
- aria-orientation: 表明 TabBar 的方向,有
vertical
和horizontal
两种。当传入 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
键,将焦点移动到已被选择的选项卡元素的选项卡面板上 - 当焦点位于水平选项卡列表中的选项卡元素上时,使用
左右箭头
来切换选项 - 当焦点位于垂直选项卡列表中的选项卡元素上时,使用
上下箭头
来切换选项 - 当焦点位于选项卡列表中的未被激活的选项卡元素上时,可以使用
Space
或Enter
键来激活该选项卡 - 当键盘用户想要直接将焦点聚焦到选项卡列表中的最后一个选项卡元素时:
- Mac 用户:
fn
+右箭头
- Windows 用户:
End
- Mac 用户:
- 当键盘用户想要直接将焦点聚焦到选项卡列表中的第一个选项卡元素时:
- Mac 用户:
fn
+左箭头
- Windows 用户:
Home
- Mac 用户:
- 当选项卡允许被删除时:
- 用户可以使用
Delete
键删除选项卡 - 删除后,焦点转移到被删除选项卡元素的后一个元素上;若被删除元素无后一个元素则转移到前一个元素上
- 用户可以使用
设计变量
文案规范
- 标签文案需要准确清晰地解释标签内容
- 用简短的,易区分的标签
- 尽量保持在一个词以内
FAQ
- 为什么在 Tabs 中使用 Typography 的省略 ellipsis 失效?因为 Tabs 渲染 TabPane 时,默认是全部渲染 display: none。此时这些组件无法获取到正确的宽度或高度值。建议 1.x 的版本开启 lazyRender,或者关闭 keepDOM。0.x 的版本需要使用 tabList 的写法。
- 为什么在 Tabs 中使用 Collapse/Collapsible/Resizable Table 等组件的高度或宽度值不对?原因同上,另外如果 collapse 不需要动画,也可以通过设置 motion={false} 来关闭动画效果。此时无需获取组件的高度。