导航类 · Navigation
导航
为页面和功能提供导航的菜单列表。

代码演示

如何引入

基本使用

通过传递 items 参数,你能够快速得到一个导航栏。
每个导航项目包括:
  • itemKey:导航项目的唯一标识(必须)
  • text:导航文案
  • icon:导航图标
参数含义详见 Nav.ItemNav.Sub

导航缩进

版本:>= 0.16.0
导航缩进目前仅对第一级导航有效果。

纯文案导航

如果导航项目没有传入 icon 字段,那么文案会自动向左填充。

定义头部和底部

开发者可能会经常定义 Logo 区域和收起按钮区域,Navigation 则提供了这样的容器方便开发者快速定义导航头部和底部,你仅需按要求传入 header 或 footer 即可。
对于 footer,semi-ui 额外封装了一个收起功能按钮,开发者可以通过传递 collapseButton = true 开启此功能,不过该参数仅在 mode = "vertical" (垂直导航)生效。
参数详见Nav.HeaderNav.Footer

导航样式定义

Navigation 目前提供了个两个参数用于定义导航样式:stylebodyStyle,其中 style 用于定义导航组件最外层的样式,而 bodyStyle 用于定义导航列表的样式。(导航头部和导航底部则都接受各自的 style 参数)。
例如你需要一个导航列表可以滚动,导航头部和底部固定的导航组件,可以这么使用:

JSX 写法

用户可以使用 JSX 写法定义导航头部、导航项以及导航底部。

配合 react-router 等路由组件

为了在使用 react-router 等路由组件时,能将 NavItem 包裹在路由组件提供的 Link 或者 NavLink 中来让用户点击 NavItem 时候触发路由组件的点击事件, 我们需要自定义渲染。
使用 renderWrapper 在每个导航项外包裹自定义导航组件 查看此 CodeSandBox

导航方向

Navigation 目前提供两种方向的导航:
  • 垂直方向(默认), mode = "vertical"
  • 水平方向, mode = "horizontal"
特别注意的是,有一些功能(参数)仅在 mode = "vertical" 时有效:
  • isCollapsed (导航收起到侧边)
  • defaultOpenKeys | openKeys (指定默认的以及受控的展开子导航项 key 数组,这个参数仅在 mode = "vertical"isCollapsed = false 有效)
  • Footer 组件的 collapseButton 收起侧边栏功能按钮

竖直方向

水平方向

水平加垂直

一般的平台设计会采取水平加垂直导航的模式,这里有一个比较常见的例子。

展开收起箭头位置

toggleIconPosition 设置 'left' 或 'right', 默认 right

缩进限制

默认无缩进,需要导航项依据层级缩进请将 limitIndent 设置为 false
React Jsx 方式用 Nav.Item 传入导航项时 请手动给 Nav.Item 传入 level props。
Object 方式 传入导航项时 无需关心 level
limitIndent 只在 竖直方向生效

非受控属性

包括:
  • defaultSelectedKeys(默认被选中的导航项 key 数组)
  • defaultOpenKeys(默认展开的导航项 key 数组,仅 mode = "vertical"isCollapsed | defaultIsCollapsed = false 的情况下有效)
  • defaultIsCollapsed(侧边栏默认是否收起,仅 mode = "vertical" 时有效)

受控属性

Navigation 组件提供了几个受控属性,配合各种回调,可以很轻松地控制导航。
目前受控的属性为:
  • isCollapsed(侧边栏是否收起,仅 mode =" vertical" 时生效)
  • selectedKeys(当前选中的导航项 key 数组)
  • openKeys (当前展开的导航项数组,仅 mode = "vertical"isCollapsed = false 有效)
对应的回调为:
  • onCollapseChange(isCollapsed: boolean): void
  • onSelect({ itemKey: string, selectedKeys: string[], domEvent: MouseEvent, isOpen: boolean }): void
  • onOpenChange({ itemKey: string, openKeys: string[], domEvent: MouseEvent, isOpen: boolean }): void

API 参考

属性描述类型默认值
bodyStyle导航项列表的自定义样式CSSProperties
className最外层元素的样式名string
defaultIsCollapsed默认是否处于收起状态,仅 mode = "vertical" 时有效booleanfalse
defaultOpenKeys初始打开的子导航 itemKey 数组,仅 mode = "vertical" 且侧边栏处于展开状态时有效string[][]
defaultSelectedKeys初始选中的导航项 itemKey 数组string[][]
footer底部区域配置对象或元素,详见 Nav.Footerobject\ ReactNode
getPopupContainer垂直 Nav 折叠或 水平 Nav中 Dropdown 的 getPopupContainer 配置,可指定弹出层容器, >=2.24.0Function
header头部区域配置对象或元素,详见 Nav.Headerobject\ ReactNode
isCollapsed是否处于收起状态的受控属性,仅 mode = "vertical" 时有效boolean
items导航项目列表,每一项可以继续带有 items 属性。如果为 string 数组,则会取每一项作为 text 和 itemKeyobject\ string[] \
limitIndent解除缩进限制,可使用 level 自定义导航项缩进,水平模式只能为true >=1.27.0booleantrue
mode导航类型,目前支持横向与竖直,可选值:vertical/horizontalstring
openKeys受控的打开的子导航 itemKey 数组,配合 onOpenChange 回调控制子导航项展开,仅 mode = "vertical" 且侧边栏处于展开状态时有效string[]
prefixCls类名前缀stringsemi
renderWrapper自定义导航项外层组件 >=2.24.0(data:{ itemElement:ReactElement, isSubNav:boolean, isInSubNav:boolean, props:SubNavProps| ItemProps })=>ReactNode
selectedKeys受控的导航项 itemKey 数组,配合 onSelect 回调控制导航项选择string[]
style最外层元素的自定义样式CSSProperties
subNavCloseDelay子导航浮层关闭的延迟。collapse 为 true 或 mode 为 "horizontal" 时有效,单位为 msnumber100
subNavMotion子导航折叠动画booleantrue
subNavOpenDelay子导航浮层显示的延迟。collapse 为 true 或 mode 为 "horizontal" 时有效,单位为 msnumber0
toggleIconPosition带有子导航项的的父级导航项箭头位置 >=1.27.0'left' \ 'right'
tooltipHideDelaytooltip 隐藏的延迟,collapse 为 true 时有效,单位为 msnumber100
tooltipShowDelaytooltip 显示的延迟,collapse 为 true 时有效,单位为 msnumber0
onClick点击任意导航项时触发
(itemKey, event, isOpen)=> void
() => {}
onCollapseChange收起状态变化时的回调
(isCollapsed)=>{}
() => {}
onOpenChange切换某个子导航项目显隐状态时触发
({itemKey, openKeys, event, isOpen})=>{}
() => {}
onSelect第一次选中某个可选中导航项目时触发,其中 selectedItems 这个字段版本 >= 0.17.0 后才支持
(onSelectProps)=>{}
() => {}
属性描述类型默认值版本
disabled是否禁用booleanfalse1.17.0
icon导航项目图标ReactNode
indent如果 icon 为空,是否保留其占位,仅对一级导航生效booleanfalse
itemKey导航项目唯一 keystring""
level当前项所在嵌套层级,limitIndent 为 true时,用于自定义缩进位置number1.27.0
link导航项 href 链接,传入时导航项整体会包裹一个 a 标签string-1.0.0
linkOptions透传给 a 标签的参数object-1.0.0
text导航项目文案或元素string|ReactNode""
onClick点击任意导航项时触发function({ itemKey: string, domEvent: MouseEvent, isOpen: boolean })() => {}
onMouseEntermouse enter 时触发function(e) => {}() => {}
onMouseLeavemouse leave 时触发function(e) => {}() => {}
属性描述类型默认值
disabled是否禁用booleanfalse
dropdownStyle弹出层的 styleCSSProperties
icon导航项目图标ReactNode
indent如果 icon 为空,是否保留其占位,仅对一级导航生效booleanfalse
isCollapsed是否处于收起状态的受控属性,仅 mode = "vertical"booleanfalse
isOpen是否打开booleanfalse
itemKey导航项目唯一 keystring""
level当前项所在嵌套层级,limitIndent 为 true时,用于自定义缩进位置number0
maxHeight最大高度number999
text导航项目文案或组件string|ReactNode""
onMouseEntermouse enter 时触发function(e) => {}() => {}
onMouseLeavemouse leave 时触发function(e) => {}() => {}
属性描述类型默认值版本
children子元素ReactNode
className最外层样式名string
link导航项 href 链接,传入时导航项整体会包裹一个 a 标签string-1.0.0
linkOptions透传给 a 标签的参数object-1.0.0
logoLogoReactNode
style最外层样式CSSProperties
textLogo 文案ReactNode
属性描述类型默认值
children子元素ReactNode
className最外层样式名string
collapseButton是否展示底部“收起侧边栏”按钮,mode="vertical" 且 Footer 组件的 children 参数为空才有效果boolean|ReactNodefalse
collapseText“收起”按钮的文案(collapsed:boolean) => string|ReactNode
style最外层样式CSSProperties

Accessibility

  • 键盘和焦点

  • Navigation 内的每个可点击 item 都可以被聚焦,相互之间使用 TabShift + Tab 切换焦点,并且可以通过 Enter 键激活每个链接
  • 当某个 item 可被打开弹层时
    • 打开弹层方式为 hover :该 item 被聚焦时,弹层打开。键盘用户可以通过下箭头将焦点移动到弹层上,Esc 键可以将焦点返回到 item 上
    • 打开弹层的方式为 click :该 item 被聚焦时,点击 Enter 键,打开弹层。键盘用户可以通过下箭头将焦点移动到弹层上,Esc 键可以将焦点返回到 item 上
    • 键盘交互暂未完整支持嵌套场景

文案规范

  • 导航栏菜单使用句子大小写格式
  • 尽量精简
✅ 推荐用法❌ 不推荐用法
Appeal centerAppeal Center

设计变量

FAQ

  • 导航动画丢失?
    在使用函数式组件时,应该用 useState 或者 useMemo 包裹一下 items,原因是 items 直接传一个数组会触发组件重新渲染。
  • 当子菜单高度超过999px,部分导航消失? 请查看 此 issue