如何在TypeScript中为MUI 5 Typography扩展自定义Props

我尝试给MUI的Typography组件添加自定义opacity属性，写了以下模块扩充代码：

// mui.d.ts

declare module "@mui/material/Typography" {
  interface TypographyProps {
    opacity: string | number;
  }
}

以及主题配置代码：

export const theme = createTheme({
  components: {
    MuiTypography: {
      styleOverrides: {
        root: ({ ownerState }) => ({
          opacity: ownerState.opacity,
        }),
      },
    },
  },
});

但使用新增的opacity属性时，出现了TypeScript错误：

重载 1 共 2 个，'(props: { component: ElementType<any>; } & SystemProps<Theme> & { align?: "inherit" | "left" | "right" | "center" | "justify" | undefined; children?: ReactNode; ... 6 more ...; variantMapping?: Partial<...> | undefined; } & CommonProps & Omit<...>): Element'，给出以下错误。
    类型 '{ children: string; opacity: number; }' 中缺少属性 'component'，但类型 '{ component: ElementType<any>; }' 中需要该属性。
  重载 2 共 2 个，'(props: DefaultComponentProps<TypographyTypeMap<{}, "span">>): Element'，给出以下错误。
    类型 '{ children: string; opacity: number; }' 不能赋值给类型 'IntrinsicAttributes & SystemProps<Theme> & { align?: "inherit" | "left" | "right" | "center" | "justify" | undefined; children?: ReactNode; ... 6 more ...; variantMapping?: Partial<...> | undefined; } & CommonProps & Omit<...>'。
      属性 'opacity' 在类型 'IntrinsicAttributes & SystemProps<Theme> & { align?: "inherit" | "left" | "right" | "center" | "justify" | undefined; children?: ReactNode; ... 6 more ...; variantMapping?: Partial<...> | undefined; } & CommonProps & Omit<...>' 上不存在。ts(2769)
OverridableComponent.d.ts(21, 7): 'component' 在此处声明。

问题原因 #

MUI的组件Props是基于TypographyTypeMap类型映射构建的，直接扩充TypographyProps接口不会被TypeScript正确识别——因为TypographyProps本质是通过OverrideProps工具类型从TypographyTypeMap生成的，必须修改底层的类型映射定义才能生效。

解决方案 #

修改mui.d.ts的模块扩充代码，直接扩充TypographyTypeMap的props部分：

// mui.d.ts
import { TypographyTypeMap } from '@mui/material/Typography';
import { OverrideProps } from '@mui/material/OverridableComponent';
import React from 'react';

declare module '@mui/material/Typography' {
  // 保留原有的覆盖接口（无需修改可留空）
  interface TypographyPropsVariantOverrides {}
  interface TypographyPropsColorOverrides {}

  // 扩充TypographyTypeMap的props
  interface TypographyTypeMap<P = {}, D extends React.ElementType = 'span'> {
    props: P & {
      opacity?: string | number; // 设为可选属性更符合实际使用场景
    };
  }

  // 重新定义TypographyProps，确保基于修改后的TypeMap生成
  type TypographyProps<D extends React.ElementType = TypographyTypeMap['defaultComponent']> = OverrideProps<TypographyTypeMap<{}, D>, D>;
}

补充说明 #

1. 主题配置代码无需修改，依然可以通过ownerState.opacity获取自定义属性并应用样式。
2. 将opacity设为可选属性（opacity?），避免使用时必须传该属性，更符合组件使用习惯。
3. 确保mui.d.ts被TypeScript编译流程识别，可在tsconfig.json的include数组中添加该文件路径：

{
  "include": ["src/**/*", "mui.d.ts"]
}

修改后即可正常使用自定义属性：

<Typography opacity={0.7}>带透明度的文本</Typography>

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