企业官网建设流程全解析

Umi Max 如何开启 layout 插件自动生成顶部导航与侧边菜单

【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi

在 Umi Max（@umijs/max）项目中，页面框架的顶部导航和侧边栏菜单不需要手写：layout 插件内置了 Ant Design 的 Layout（@ant-design/pro-layout），只要在配置里开启插件、并给路由写上name，菜单就会根据路由配置自动生成。本文按“创建项目 → 开启插件 → 配置路由生成菜单 → 运行时微调 → 启动验证”的路径，说明如何在 Umi Max 中完成这一步。前提环境：Node 版本 22 或以上，包管理工具推荐使用 pnpm。

创建 Umi Max 项目

使用create-umi选择Ant Design Pro模板创建项目，模板默认依赖@umijs/max并预装了一套插件：

$ npx create-umi@latest ? Pick Umi App Template › - Use arrow-keys. Return to submit. Simple App ❯ Ant Design Pro Vue Simple App

注意 Umi Max 项目中命令行请使用max，而不是umi，例如：

$ npx max g jest

新建的 Umi Max 项目默认安装了一批可单独开启的插件，layout 即其中之一：权限（access）、站点统计（analytics）、Antd、图表（charts）、dva、initial-state、数据流、布局和菜单（layout）、国际化（i18n）、model、乾坤微前端（qiankun）、请求库、Tailwind CSS 等。

构建时开启 layout 插件

在配置文件config/config.ts中加入layout属性即可开启插件：

// config/config.ts import { defineConfig } from 'umi'; export default defineConfig({ layout: { title: 'Ant Design', locale: false, // 默认开启，如无需菜单国际化可关闭 }, });

仓库中 Ant Design Pro 示例的写法可以参考 config/config.ts：

/** * @name layout 插件 * @doc https://umijs.org/docs/max/layout-menu */ layout: { locale: true, ...defaultSettings, },

两个常用构建时配置项：

• title：显示在布局左上角的产品名，Type 为string，默认值为package.json中的name。
• locale：是否开启菜单国际化，Type 为boolean。开启后路由里配置的菜单名会被当作国际化 key，插件去 locales 文件中查找menu.[key]对应的文案（默认值为该 key；多级路由会查找menu.[key].[key]），该功能需要配合 i18n 插件使用；如无需菜单国际化可配置false关闭。

除插件特有配置外，构建时配置会透传给@ant-design/pro-layout，支持它的配置项。

配置路由，让菜单自动生成

顶部导航和侧边栏菜单是根据路由配置自动生成的。路由中新增的关键字段如下（示例来自官方文档）：

// config/route.ts export const routes: IBestAFSRoute[] = [ { path: '/welcome', component: 'IndexPage', name: '欢迎', // 兼容此写法 icon: 'testicon', // --- // 新页面打开 target: '_blank', // 不展示顶栏 headerRender: false, // 不展示页脚 footerRender: false, // 不展示菜单 menuRender: false, // 不展示菜单顶栏 menuHeaderRender: false, // 权限配置，需要与 plugin-access 插件配合使用 access: 'canRead', // 隐藏子菜单 hideChildrenInMenu: true, // 隐藏自己和子菜单 hideInMenu: true, // 在面包屑中隐藏 hideInBreadcrumb: true, // 子项往上提，仍旧展示 flatMenu: true, }, ];

决定菜单能否生成的字段：

• name（string）：菜单上显示的名称，没有则不展示该菜单。
• icon（string）：菜单上显示的 antd icon，插件会自动按需转化为 Antd icon 的 dom，写法如icon: 'home'（outlined 线框风格可简写）、icon: 'HomeFilled'（实底风格）、icon: 'HomeTwoTone'（双色风格）。它也兼容 icons 功能，打开 icons 功能后可以使用图标集或本地图标。

以 Pro 示例的路由配置 config/routes.ts 为例，name+icon的写法即生效方式：

{ path: '/welcome', name: 'welcome', icon: 'smile', component: './Welcome', }, { name: 'list.table-list', icon: 'table', path: '/list', component: './TableList', },

菜单渲染相关的开关字段：

• xxxRender=false不展示对应模块：headerRender=false不显示顶栏、footerRender=false不显示页脚、menuRender=false不显示菜单、menuHeaderRender=false不显示菜单的 title 和 logo。
• hideInXXX管理 menu 渲染：hideChildrenInMenu=true隐藏子菜单、hideInMenu=true隐藏自己和子菜单、hideInBreadcrumb=true在面包屑中隐藏。
• flatMenu=true打平菜单：该项本身在菜单中隐藏，子项往上提仍旧展示。
• access（string）：配合权限插件（plugin-access）使用。权限插件会把这里配置的 access 字符串与当前用户所有权限做匹配，如果找到相同的项且该权限的值为 false，用户访问该路由时默认展示 403 页面。

layout 插件默认还支持对路由的 403/404 处理和 Error Boundary。

用运行时配置微调布局

运行时配置写在src/app.tsx中，key 为layout。除插件特有配置外，运行时配置支持所有构建时配置并透传给@ant-design/pro-layout：

import { RunTimeLayoutConfig } from '@umijs/max'; export const layout: RunTimeLayoutConfig = (initialState) => { return { // 常用属性 title: 'Ant Design', logo: 'https://img.alicdn.com/tfs/TB1YHEpwUT1gK0jSZFhXXaAtVXa-28-27.svg', // 默认布局调整 rightContentRender: () => <RightContent />, footerRender: () => <Footer />, menuHeaderRender: undefined, // 其他属性见 @ant-design/pro-layout 文档 }; };

常用运行时属性：

• logo（string）：显示在布局左上角产品名前的产品 Logo，默认为 Ant Design Logo。
• rightRender（(initialState: any) => React.ReactNode）：默认展示用户名、头像、退出登录相关组件；initialState是app.ts(x)中getInitialState返回的对象。
• logout（(initialState: any) => void）：点击退出登录的处理逻辑，默认不做处理。注意默认在顶部右侧并不会显示退出按钮，需要在app.ts(x)中配置getInitialState返回一个对象，才可以显示。
• ErrorBoundary（ReactNode）：发生错误后展示的组件，默认为 Ant Design Pro 的错误页。

仓库示例中的 examples/max/app.ts 展示了最简写法：

export const layout = { logout() { alert('logout'); }, };

启动并验证菜单效果

在项目根目录执行启动命令（Umi Max 项目使用max）：

$ max dev

参考仓库示例的 package.json 脚本写法，等价于pnpm dev（"dev": "max dev"），见 examples/max/package.json。启动成功后终端会打印本地访问地址（Umi 文档示例中为https://127.0.0.1:8000，实际端口以终端输出为准），在浏览器中打开该地址即可验证：

• 顶部导航和侧边栏菜单已出现，且条目与路由配置中的name/icon一一对应；
• 布局左上角显示title对应的产品名（未配置时为package.json的name）；
• 配置了layout: false的一级路由（如登录页）不显示全局布局，组件内容占据整个页面。

菜单文案是否展示、能否跳转，都可以直接对照路由配置核对：name为菜单显示名，component为渲染组件路径（相对路径从src/pages开始寻找）。

限制与常见调整

• layout: false用于单独关闭某个路由的全局布局，仅在一级路由生效：

// .umirc.ts export default { routes: [ // 取消 login 页面的全局布局，从而自行实现整个页面 { path: '/login', component: '@/pages/Login', layout: false }, ], }

Pro 示例中登录页和 404 页就是这种用法（path: '/user'与path: '*'均配置了layout: false）。

• 路由未写name就不会出现在菜单里，只渲染页面本身；想让页面进菜单，先补上name。
• 菜单国际化（locale: true）依赖 i18n 插件与src/locales下的多语言文件，key 规则为menu.${submenu-name}.${name}。
• 权限路由需要同时开启 access 插件，并在src/access.ts中定义权限项后，路由上的access字段才会生效。
• layout 插件默认基于 Umi 路由封装配置，支持按路由级别控制展示/隐藏，更多高级菜单玩法（如动态菜单）文档建议参考 ProLayout 的菜单高级用法文档。

完成以上配置后，顶栏与侧边菜单即由路由自动驱动：新增路由时只需补充name（可选icon），无需改动布局代码。

【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi