Umi.js 子路由菜单图标显示问题解析与解决方案

问题背景

在使用 Umi.js 框架开发项目时，开发者经常遇到子路由菜单图标无法正常显示的问题。这是一个典型的前端路由配置问题，特别是在使用 Umi Max 脚手架生成的项目中尤为常见。

现象描述

当开发者在路由配置中为子路由设置图标(icon)属性时，第一级菜单的图标可以正常显示，但第二级及更深层级的菜单图标却无法显示。这给开发者带来了困扰，因为从配置上看似乎没有问题，但实际效果却不尽如人意。

技术原理分析

Umi.js 的菜单渲染机制默认只显示一级菜单的图标，这是出于设计考虑。这种设计有以下几点原因：

1. 视觉层次清晰：避免菜单过于花哨，保持界面简洁
2. 空间利用率：减少菜单占用过多水平空间
3. 一致性：遵循常见后台管理系统的设计惯例

解决方案

要解决子路由图标显示问题，需要在 src/app.tsx 文件中进行布局配置。以下是详细的解决方案：

import { RunTimeLayoutConfig } from '@umijs/max';

export const layout: RunTimeLayoutConfig = (initialState) => {
  return {
    menuItemRender: (menuItemProps, defaultDom) => {
      return (
        <Link to={menuItemProps.path}>
          <div style={{ display: 'flex' }}>
            <span style={{ paddingRight: '8px' }}>
              {menuItemProps.pro_layout_parentKeys && 
               menuItemProps.pro_layout_parentKeys.length > 0 &&
               menuItemProps.icon}
            </span>
            {defaultDom}
          </div>
        </Link>
      );
    },
  };
};

进阶优化

对于使用混合布局(layout: 'mix')的项目，上述方案可能会导致图标显示错乱。建议使用以下优化后的代码：

menuItemRender: (menuItemProps, defaultDom) => {
  return (
    <Link to={menuItemProps.path}>
      <div style={{ display: 'flex' }}>
        {menuItemProps.pro_layout_parentKeys && 
         menuItemProps.pro_layout_parentKeys.length > 1 && (
          <span style={{ paddingRight: '8px' }}>
            {menuItemProps.icon}
          </span>
        )}
        {defaultDom}
      </div>
    </Link>
  );
},

常见问题排查

1. 文件扩展名问题：确保配置文件为 .tsx 而非 .ts
2. 图标组件引入：确认使用的图标组件已正确导入
3. 路由配置检查：验证子路由的 icon 属性是否设置正确
4. 布局模式影响：不同布局模式可能需要不同的图标显示策略

最佳实践建议

1. 保持图标风格一致，避免混用多种图标库
2. 控制菜单层级深度，建议不超过三级
3. 为重要功能菜单保留图标，次要功能可省略
4. 考虑使用 SVG 图标以获得更好的显示效果

通过以上方案，开发者可以灵活控制 Umi.js 项目中各级菜单图标的显示行为，打造更符合项目需求的导航体验。