@alicloudfe/components-console-menu
v1.1.0
Published
React component for Alibaba Cloud.
Downloads
29
Readme
@alicloudfe/components-console-menu
为阿里云控制台提供标准的应用级别的导航菜单,也可以应用在其他的中后台产品中
1.0 的新特性
组件模块
基础导航菜单
在之前的版本中默认导出的 <ConsoleMenu>
组件包含了完整的路由行为,在 1.0 中,默认导出的组件 不再包含 路由行为,你可以根据自己项目中的路由环境来映射 <ConsoleMenu>
的展现和行为(如设置 activeKey
等)。
import ConsoleMenu from '@alicloudfe/components-console-menu'
import { Route, Link } from 'react-router-dom'
const mapLocationToActiveKey = (location) => {
if (!location || !location.pathname || location.pathname === '/') {
return 'overview'
}
return location.pathname.replace(/^\//, '')
}
const App = () => (
<Route>
{
({ location }) => (
<ConsoleMenu
header="Aliyun Console"
activeKey={location.pathname}
>
<ConsoleMenu.Item key="overview">
<Link to="/overview">概览</Link>
</ConsoleMenu.Item>
<ConsoleMenu.Item key="list">
<Link to="/list">列表</Link>
</ConsoleMenu.Item>
<ConsoleMenu.SubMenu key="logs">
<ConsoleMenu.Item key="daily">
<Link to="/daily">日常</Link>
</ConsoleMenu.Item>
<ConsoleMenu.Item key="prod">
<Link to="/prod">生产</Link>
</ConsoleMenu.Item>
</ConsoleMenu.SubMenu>
</ConsoleMenu>
)
}
</Route>
)
你也可以用结构化的描述来定制 <ConsoleMenu>
的内容。下面的示例作用和上面的作用完全相同:
import ConsoleMenu from '@alicloudfe/components-console-menu'
import { Route, Link } from 'react-router-dom'
const mapLocationToActiveKey = (location) => {
if (!location || !location.pathname || location.pathname === '/') {
return 'overview'
}
return location.pathname.replace(/^\//, '')
}
const renderAsLink = ({ key, label }) => (
<Link to={`/${key}`}>{label}</Link>
)
const items = [
{ key: 'overview', label: '概览', render: renderAsLink },
{ key: 'list', label: '列表', render: renderAsLink },
{
key: 'logs',
label: '列表',
items: [
{ key: 'daily', label: '日常', render: renderAsLink },
{ key: 'prod', label: '生产', render: renderAsLink, visible: false },
]
},
]
const App = () => (
<Route>
{
({ location }) => (
<ConsoleMenu
header="Aliyun Console"
items={items}
activeKey={location.pathname}
/>
)
}
</Route>
)
带有路由功能的导航菜单
如果你的项目使用了 dva^2.0.0
,我们也提供了 <RoutableMenu>
组件来提供与之适配的路由功能。
(截止目前为止, <RoutableMenu>
必须使用 items 进行结构化的传值,使用组件声明方式来编写子组件的方式可能会存在问题,我们计划在不久之后来修复这个问题)
import RoutableMenu from '@alicloudfe/components-console-menu/RoutableMenu'
const items = [
{
// 在当前路由路径为 `/overview` 时将该 Item 变为选中状态
key: '/overview',
label: '概览',
// 点击该 Item 会跳转至 `/overview`
to: '/overview'
},
{
key: '/product/:region',
label: '产品',
to: '/product/cn-hangzhou'
},
{
// 在当前路由路径匹配 `/instance/:region?` 时将该 Item 变为选中状态
key: '/instance/:region?',
label: '实例',
to: (routeProps, item) => {
// 该方法并不是我们推荐的做法,只是为了表示 `to` 可以用函数表达式来声明:
// 第一个参数是当前的 route props ,第二个参数是当前的 item 的结构化信息
// 你可以利用这些信息来动态地返回需要进行跳转的 pathname 或 location
// 下面的这个例子使用了当前路由的匹配信息(注意:并不是对于该 item 的匹配)
// 来进行相应的跳转。如果当前的路由中包含 param: region ,(譬如从
// `/product/cn-hangzhou` 点击该 item 将会跳转到 `/instance/cn-hangzhou`
//
// 在实际项目中的最佳实践是直接派发父级 pathname ,然后在 <Route> 中通过上下文
// 或者其他方式进行路由重定向
//
const { match: { params: { region } = {} } = {} } = routeProps
return `/instance/${region}`
},
// 除了使用 `key` 来匹配单个的路由路径之外,还可以使用 `activePathPatterns` 来
// 尝试匹配多个路由路径,`<RoutableMenu>` 内置的匹配算法将会在尝试将当前的路径匹配
// `key` 失败之后,按照 `activePathPatterns` 指定的顺序依次进行尝试匹配,一旦匹配
// 成功,则将该 Item 变为选中状态
activePathPatterns: [
'/instance/:regionId/:instanceId',
],
},
{
key: 'logs',
label: '列表',
items: [
{
key: '/daily',
label: '日常',
// 使用 href 将使用超链接的方式打开指定的链接,区别于应用内的路由跳转
href: 'https://daily.project.com',
},
{
key: '/prod',
label: '生产',
to: '/prod',
},
]
},
]
const App = () => (
<RoutableMenu header="Aliyun Console" items={items} />
)
可高度定制的组件
所有的展示组件( Presentation Components )都已经通过StyledComponents
导出,这些组件可以作为样式自定义的切入点。如果你希望自定义 <ConsoleMenu>
的样式,可以使用 styled-components
的方式对样式进行修改,而不用担心对全局或其他模块产生冲突。如这个例子所示:
import styled from 'styled-components'
import ConsoleMenu, { StyledComponents } from '@alicloudfe/components-console-menu'
const CustomizedConsoleMenu = styled(ConsoleMenu)`
${StyledComponents.Item} {
font-size: 14px;
}
/* any css is ok here */
`
// CustomizedConsoleMenu中的Item样式已经修改
// ConsoleMenu的样式没有变化
// 可以将CustomizedConsoleMenu理解为ConsoleMenu的“fork”
const App = () => (
<CustomizedConsoleMenu header="Aliyun Console" items={[{ key: 'overview', label: '概览' }]} />
)
API 变动参考
Props
| 旧版本 | 1.0 | 说明 |
| :---: | :---: | :--- |
| config.title
| header
| config
属性中的 title
和 navs
定义分别调整为 props 中的 header
和 items
,绝大部分属于语义化和结构化的调整 |
| config.navs
| items
| 同上,内部元素的调整可以参考 Props.config.navs v.s. Props.items 来浏览变更 |
| onClick
| onItemClick
| 语义化调整 |
| open
| -- | 该属性已经被移除,导航菜单本身不应具备「展开」和「收起」的行为,这给其他组件的设计带来了一些不利因素;现在这些行为统一归纳到 @ali/wind-rc-app-layout
并受其控制,导航菜单不再对这些行为负责 |
| toggleOpen
| -- | 该属性已经被移除,导航菜单本身不应具备「展开」和「收起」的行为,这给其他组件的设计带来了一些不利因素;现在这些行为统一归纳到 @ali/wind-rc-app-layout
并受其控制,导航菜单不再对这些行为负责 |
| decentSubNav
| -- | 该属性已经被移除,现在该行为已经内置在默认的行为中,当一个父节点中的所有子节点都被设置成不可见时,该父节点也会相应地从当前组件树中移除 |
| params
| -- | 该属性已经被移除,可以使用 RoutableMenu
并声明 item 元素的 to
属性,由于该属性可以被声明为一个函数,该函数将在每次路由跳转之前执行并将返回结果作为跳转的目标 pathname 或 location,理论上你可以编写任何代码来执行路由跳转 |
| level
| -- | 该属性已经被移除,在新的设计规范中,L2 导航被调整到应用的内容区,相关的功能请参考 @ali/wind-rc-page
|
| history
| -- | 该属性已经被移除,你可以直接使用 <RoutableMenu>
来获得操控应用路由的能力 |
| location
| -- | 该属性已经被移除,你可以直接使用 <RoutableMenu>
来获得操控应用路由的能力 |
Props.config.navs[i] v.s. Props.items[i]
| config.navs[i] | items[i] | 说明 |
| :---: | :---: | :--- |
| key
| key
| 在之前的版本中 key 既可以当做需要进行跳转的路径,也可以当做进行尝试匹配的路径,但是在新版本中,key 只会作为进行尝试匹配的路径,你需要使用 to
来定义需要进行跳转的路径。 |
| -- | to
| 在之前的版本中只需要定义 key 即可同时当做跳转路径和需要尝试匹配的路径,在新版本中,你 必须 定义 to
属性才可以正常进行跳转,具体用法可以参考 RoutableItemDescriptor API |
| -- | linkProps
| 自定义内置 Link
组件的 props ,如果定义了 to
,linkProps
将透传至 React-Router Link 组件;如果定义了 href
,则 linkProps
将透传至 <a>
,如 target="_blank"
等 |
| title
| label
| 定义默认显示的内容 |
| hide
| visible
| 是否显示该菜单项,注意 visible
和 hide
的值是相反的 |
| url
| href
| 使用超链接的方式打开指定的链接,区别于应用内的路由跳转 |
| highlight
| activePathPatterns
| 需要尝试进行匹配并进行高亮的路由路径集合 |
| subNav
| items
| 子菜单项 |
| type
| -- | 该属性已经被移除,现在每个 Item 的类型由 label
/ to
/ href
来定义:当只有 label
声明时,该 Item 将不具任何特质,等同于原有的 type: "title"
;声明了 label
的 Item 将具备默认的应用内路由跳转的能力,等同于原有的 type: "link"
;声明了 href
的 Item 将使用超链接的方式打开指定的链接,等同于原有的 type: "stateLink"
|
| navs
| -- | 该属性已经被移除,在最新的视觉和交互规范中,L2 导航被放置到了右侧的内容区,你可以将 <ConsoleMenu>
传入 @ali/wind-rc-page
的 <Page.Content>
的 menu
属性中 |
| open
| -- | 该属性已经被移除,请使用组件的属性 openKeys
或 defaultOpenKeys
来进行手动控制 |
使用 L2 导航
import RoutableMenu from '@alicloudfe/components-console-menu/RoutableMenu'
import Page from '@ali/wind-rc-page'
const menu = (
<RoutableMenu
type="secondary"
items={[]}
/>
)
const MyPage = () => (
<Page>
<Page.Content menu={menu}>
Hello, World
</Page.Content>
</Page>
)
视觉和交互
- 移除关于
width
/min-width
的限制,组件宽度自适应容器宽度 - 更新主题颜色,适配最新的设计标准
安装
同级依赖
在 1.0 版本中,<ConsoleMenu>
组件的同级依赖( peer dependencies )增加了 styled-components
为组件提供基础的样式能力,使用了 React Hooks 封装业务逻辑,并应用了一些其他的底层更新带来的问题修复和特性。请保证你的项目正确安装了下面的这些依赖
| 依赖名称 | 版本 |
| :--- | :---: |
| styled-components
| ^4.2.0
|
| react
| ^16.8.0
|
| react-dom
| ^16.8.0
|
| prop-types
| ^15.7.0
|
| @alicloudfe/components
| ^1.0.0
|
安装最新版本
npm i -S @alicloudfe/components-console-menu
使用示例
基本使用
下面的示例展示了使用 <ConsoleMenu>
/ <ConsoleMenu.Item>
以及 <ConsoleMenu.SubMenu>
等组件,组合而成一个完整的视图级别的导航菜单
MDXInstruction:importDemo:BasicDemo
次级导航
使用 type="secondary"
可以将导航的样式变为次级导航,功能与主导航一致
MDXInstruction:importDemo:SecondaryNavDemo
组件受控
使用 activeKey
可以控制导航的当前选中的 key ,下面的示例展示了如何结合 <Route>
和 <Link>
来自定义受路由控制的导航菜单
MDXInstruction:importDemo:ControlledMenuDemo
使用结构化声明
使用 items
可以将所有的菜单项进行结构化声明,就像 Table.dataSource
一样
MDXInstruction:importDemo:ItemsDeclarationDemo
可路由的导航菜单
使用 <RoutableMenu>
可以获得常用的路由功能,如将当前路由路径映射到对应的 activeKey
,以及点击菜单项之后的路由跳转等功能
该功能同级依赖于 dva^2.0.0
,请确保你的项目中安装了该依赖的正确版本
MDXInstruction:importDemo:RoutableMenuDemo
可切换header的导航菜单
可以通过配置headers
来为header提供数据源,当提供headers之后,header类型应为string非ReactNode, 否则会导致下拉菜单不能勾选☑️
MDXInstruction:importDemo:SwitchHeaderMenuDemo
APIs
ConsoleMenu
MDXInstruction:renderInterface:IConsoleMenuProps
IItemDescriptor
MDXInstruction:renderInterface:IItemDescriptor
RoutableMenu
继承自 <ConsoleMenu>
,重复的属性不再赘述,请参阅 ConsoleMenu API
MDXInstruction:renderInterface:IRoutableMenuProps
IRoutableItemDescriptor
继承自 IItemDescriptor
,重复的属性不再赘述,请参阅 IItemDescriptor