Material UI v5 使用TypeScript自定义主题无法访问自定义Palette属性

故障原因与修复方案 #

• 问题1：代码结构错误，运行时代码被写入类型声明块
  你把createTheme创建主题的运行时代码写到了declare module "@mui/material/styles"类型扩展块内部，类型声明块仅用于补充TS类型定义，不能包含运行时逻辑，这会直接导致类型扩展不生效。
  修复方式：将类型扩展代码和主题创建代码拆分，类型扩展要么写在文件顶部所有导入之后、创建主题代码之前，要么单独放到src/theme.d.ts类型声明文件中。

• 问题2：Palette接口中自定义字段的类型定义错误
  你在Palette接口定义中给Accent指定的类型是PaletteOptions["primary"]，但实际生成的主题中palette下的颜色字段类型是PaletteColor，不是配置用的PaletteOptions类型，会导致类型不匹配。同时你扩展了SimplePaletteColorOptions添加了自定义颜色字段，但没有同步扩展PaletteColor接口，会导致实际访问主题中primary等内置颜色的自定义字段时类型报错。
  修复方式：调整类型定义如下：

  declare module "@mui/material/styles" {
      // 扩展配置用的类型
      export interface PaletteOptions {
          Gradient: Gradient;
          Accent: SimplePaletteColorOptions;
          Background: BackgroundType;
          Meta: meta;
      }   
      // 扩展实际生成主题的类型
      export interface Palette {
          Gradient: Gradient;
          Accent: PaletteColor;
          Background: BackgroundType;
          Meta: meta;
      }
      // 扩展基础颜色选项
      export interface SimplePaletteColorOptions {
          onLight?: string;
          onDark?: string;
          containerLight?: string;
          containerDark?: string;
          onContainerLight?: string;
          onContainerDark?: string;
          ButtonLight?: string;
          ButtonDark?: string;
          onButtonLight?: string;
          onButtonDark?: string;
      }
      // 补充扩展实际生成的颜色类型
      export interface PaletteColor extends SimplePaletteColorOptions {}
  }
  

• 问题3：类型声明未被TS识别
  如果你的类型扩展是写在单独的.d.ts文件中，需要确保tsconfig.json的include数组包含了该声明文件的路径，否则TS不会加载自定义类型。
  修复方式：检查tsconfig.json中include配置，确保包含src/**/*或者你声明文件的对应路径。

• 问题4：拼写错误
  注意theme.palette的正确拼写是带两个t的palette，如果你的访问代码写的是theme.pallete（少一个t），也会出现找不到属性的报错。

内容的提问来源于stack exchange，提问作者reza47