name: rc-console-menu zhName: 控制台菜单 type: biz-component

@aliwind/rc-console-menu

为阿里云控制台提供标准的应用级别的导航菜单，也可以应用在其他的中后台产品中

1.0 的新特性

组件模块

基础导航菜单

在之前的版本中默认导出的 <ConsoleMenu> 组件包含了完整的路由行为，在 1.0 中，默认导出的组件 不再包含 路由行为，你可以根据自己项目中的路由环境来映射 <ConsoleMenu> 的展现和行为（如设置 activeKey 等）。

import ConsoleMenu from '@aliwind/rc-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 '@aliwind/rc-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 '@aliwind/rc-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 '@aliwind/rc-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 '@aliwind/rc-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 | | @aliwind/component | ^1.0.0 |

安装最新版本

npm i -S @aliwind/rc-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

APIs

ConsoleMenu

MDXInstruction:renderInterface:IConsoleMenuProps

IItemDescriptor

MDXInstruction:renderInterface:IItemDescriptor

RoutableMenu

继承自 <ConsoleMenu> ，重复的属性不再赘述，请参阅 ConsoleMenu API

MDXInstruction:renderInterface:IRoutableMenuProps

IRoutableItemDescriptor

继承自 IItemDescriptor ，重复的属性不再赘述，请参阅 IItemDescriptor

MDXInstruction:renderInterface:IRoutableItemDescriptor