Material UI 主题 components 键深度解析：defaultProps、styleOverrides 与 variants 定制组件

在 Material UI 中，createTheme 的 components 键是应用级定制的核心入口：你可以用它批量修改组件的默认 props、覆盖任意插槽（slot）的默认样式，并通过 variants 按 prop 条件追加样式。本文基于官方文档 docs/data/material/customization/theme-components/theme-components.md，完整覆盖 defaultProps、styleOverrides、variants、主题内 sx 语法与主题变量等全部用法，并结合仓库源码（@mui/material 与 @mui/system 包）说明这些机制在运行时的真实实现，读完你应能在项目中复制一份可直接运行的主题定制方案。

components 键的定位与边界

components 键用于在整个应用层面保持样式一致性：与其在每个使用点重复写 sx 或 styled，不如在主题里一次性声明组件的默认行为。官方文档同时给出了一个重要边界提醒：

The components key in the theme helps to achieve styling consistency across your application. However, the theme isn't tree-shakable, prefer creating new components for heavy customizations.

也就是说，主题对象不会被 tree-shaking，如果某处需要重度定制，优先用 styled 或包装出新组件，而不是全部堆进主题。从源码结构看，components 键的完整类型定义在 components.ts 中，每个 MuiXxx 键下最多支持三组配置，外加一个全局开关：

export interface Components<Theme = unknown> {
  /**
   * Whether to merge the className and style coming from the component props with the default props.
   * @default false
   */
  mergeClassNameAndStyle?: boolean | undefined;
  MuiAlert?:
    | {
        defaultProps?: ComponentsProps['MuiAlert'] | undefined;
        styleOverrides?: ComponentsOverrides<Theme>['MuiAlert'] | undefined;
        variants?: ComponentsVariants<Theme>['MuiAlert'] | undefined;
      }
    | undefined;
  // ...其余组件键结构相同
}

两个值得注意的源码细节：

• mergeClassNameAndStyle（默认 false）控制组件自身传入的 className/style 是否会与主题 defaultProps 中的同名值合并；
• 除了文档正文演示的 styleOverrides.root.variants 写法，类型定义还给每个组件键提供了顶层 variants 字段，仓库中的 TypeScript 测试 themeComponents.spec.ts 正是将 variants 直接写在 MuiButton 顶层来验证新 variant 的模块扩展。

Theme default props：批量修改组件默认 props

每个 Material UI 组件的 props 都有默认值。要全局修改这些默认值，使用主题 components 键下的 defaultProps：

const theme = createTheme({
  components: {
    // Name of the component
    MuiButtonBase: {
      defaultProps: {
        // The props to change the default for.
        disableRipple: true, // No more ripple, on the whole application 💣!
      },
    },
  },
});

上面示例的效果是全局禁用 MuiButtonBase 的涟漪效果，对应演示代码见 DefaultProps.js。

源码实现：defaultProps 在何处生效

每个组件内部都会调用 useThemeProps，将主题中的 defaultProps 与调用方传入的 props 合并。Material UI 的封装在 useThemeProps.js，它委托给 @mui/system 的实现：

export default function useThemeProps({ props, name }) {
  return systemUseThemeProps({ props, name, defaultTheme, themeId: THEME_ID });
}

真正执行合并的是 getThemeProps.ts：

export default function getThemeProps<Theme, Props, Name extends keyof any>(params: {
  props: Props;
  name: Name;
  theme?: Theme | undefined;
}): Props & ThemedProps<Theme, Name> {
  const { theme, name, props } = params;

  if (
    !theme ||
    !(theme as any).components ||
    !(theme as any).components[name] ||
    !(theme as any).components[name].defaultProps
  ) {
    return props as Props & ThemedProps<Theme, Name>;
  }

  return resolveProps((theme as any).components[name].defaultProps, props) as Props &
    Props & ThemedProps<Theme, Name>;
}

从这段实现可以确认三点：

1. 主题中不存在该组件的 defaultProps 时，props 原样返回，几乎零开销；
2. 合并通过 resolveProps 完成，调用方显式传入的 props 优先级高于主题默认值；
3. 返回类型是 Props & ThemedProps<Theme, Name>，即主题 defaultProps 中声明的字段会自动进入组件的 TypeScript 类型，无需额外声明。

此外，如果你使用 TypeScript 且依赖 Lab 组件，Lab 组件的样式覆盖方式与标准组件略有差异，官方文档单独有说明（见关联文档中指向 about-the-lab 页面的指引）。

Theme style overrides：按插槽覆盖默认样式

主题 styleOverrides 键可以修改任意 Material UI 组件的默认样式。它要求以插槽名为键——用 root 指向最外层元素，值是一个 CSS 属性对象；同时支持嵌套 CSS 选择器作为值：

const theme = createTheme({
  components: {
    // Name of the component
    MuiButton: {
      styleOverrides: {
        // Name of the slot
        root: {
          // Some CSS
          fontSize: '1rem',
        },
      },
    },
  },
});

对应演示见 GlobalThemeOverride.js。各组件暴露了哪些插槽，可以在各组件文档页的 "Slots" 部分查到，例如 Button 除 root 外还有 label、startIcon、endIcon 等插槽可单独覆盖。

Variants：基于 props 条件的样式规则

大多数组件都带有影响外观的设计相关 props，例如 Card 支持 variant prop，取 outlined 时会加上边框。如果想按某个 prop 的值条件化地覆盖样式，就在对应插槽下使用 variants 键，每个条目包含 props 与 style 两个键，当组件 props 匹配时 style 生效。两条使用规则需要牢记：

• 覆盖定义必须写成数组；
• 需要更高优先级的样式要放在数组最后（后者覆盖前者）。

基于已有 prop 覆盖样式

为 outlined 变体的 Card 加粗边框：

const theme = createTheme({
  components: {
    MuiCard: {
      styleOverrides: {
        root: {
          variants: [
            {
              props: { variant: 'outlined' },
              style: {
                borderWidth: '3px',
              },
            },
          ],
        },
      },
    },
  },
});

基于新取值添加样式

为 Button 组件新增一个 dashed 变体（示例演示见 GlobalThemeVariants.js）：

const theme = createTheme({
  components: {
    MuiButton: {
      styleOverrides: {
        root: {
          variants: [
            {
              // `dashed` is an example value, it can be any name.
              props: { variant: 'dashed' },
              style: {
                textTransform: 'none',
                border: `2px dashed ${blue[500]}`,
              },
            },
          ],
        },
      },
    },
  },
});

注意 blue、red 这类调色板颜色来自 @mui/material/colors 导出。

同时基于已有 prop 与新取值

当 variant 为新变体 dashed 且 color 为已有值 secondary 时组合覆盖：

const theme = createTheme({
  components: {
    MuiButton: {
      styleOverrides: {
        root: {
          variants: [
            {
              props: { variant: 'dashed', color: 'secondary' },
              style: {
                border: `4px dashed ${red[500]}`,
              },
            },
          ],
        },
      },
    },
  },
});

TypeScript：用模块扩展声明新 variant

如果项目使用 TypeScript，新增的 variant/颜色取值需要通过模块扩展（module augmentation）声明，否则类型系统无法识别 variant="dashed"：

declare module '@mui/material/Button' {
  interface ButtonPropsVariantOverrides {
    dashed: true;
  }
}

这段声明在仓库中有对应测试验证：themeComponents.spec.ts 对 @mui/material/Button 声明了 dashed: true 扩展，并用 createTheme 构造了含该 variant 的主题，保证类型定义与实际主题结构一致。

从源码结构看，variants 条目的类型定义在 variants.ts：

export type ComponentsVariants<Theme = unknown> = {
  [Name in keyof ComponentsPropsList]?: Array<{
    props:
      | Partial<ComponentsPropsList[Name]>
      | ((
          props: Partial<ComponentsPropsList[Name]> & {
            ownerState: Partial<ComponentsPropsList[Name]>;
          },
        ) => boolean);
    style: Interpolation<{ theme: Theme }>;
  }>;
};

两个要点由此确认：props 既可以是部分 props 对象，也可以是返回 boolean 的回调；style 是 Interpolation 类型，因此可以接收 ({ theme }) => ... 函数以访问主题。

回调形式的 props：条件式样式

props 也可以直接写成一个回调，允许基于条件应用样式，适合"某 prop 不存在某个特定值"这类难以用等值匹配表达的场景：

const theme = createTheme({
  components: {
    MuiButton: {
      styleOverrides: {
        root: {
          variants: [
            {
              props: (props) =>
                props.variant === 'dashed' && props.color !== 'secondary',
              style: {
                textTransform: 'none',
                border: `2px dashed ${blue[500]}`,
              },
            },
          ],
        },
      },
    },
  },
});

Slot ownerState 回调（已弃用）

早期写法允许在插槽样式里用回调访问 ownerState，该方式已被标记为弃用，官方建议统一改用 variants：

 const theme = createTheme({
   components: {
     MuiButton: {
       styleOverrides: {
-        root: ({ ownerState, theme }) => ({ ... }),
+        root: {
+          variants: [...],
         },
       },
     },
   },
 });

如果你在维护旧代码时遇到 root: ({ ownerState, theme }) => ({...}) 这类插槽样式回调，可以按上述 diff 迁移到 variants 数组形式。

sx 语法（实验性）

sx prop 是访问主题对象定义自定义样式的快捷方式，让你在 JSX 中用 CSS 超集编写内联样式。在 styleOverrides 中同样可以使用 sx 语法，用简写 CSS 记法修改主题内样式——当你本来就大量使用 sx prop 时，主题里写同一套语法可以方便地在两处之间迁移样式。官方文档特别标注：sx prop 自 Material UI v5 起作为组件定制功能是稳定的，但直接用在主题对象内部仍属实验性（experimental）。

主题内使用 sx 时通过 theme.unstable_sx 函数访问。演示见 GlobalThemeOverrideSx.js：

const finalTheme = createTheme({
  components: {
    MuiChip: {
      styleOverrides: {
        root: ({ theme }) =>
          theme.unstable_sx({
            px: 1,
            py: 0.25,
            borderRadius: 1,
          }),
        label: {
          padding: 'initial',
        },
        icon: ({ theme }) =>
          theme.unstable_sx({
            mr: 0.5,
            ml: '-2px',
          }),
      },
    },
  },
});

unstable_sx 的来源可以在 createThemeWithVars.js 中找到：createTheme 会在主题对象上挂载 unstable_sxConfig 与 unstable_sx 函数，前者承接 createTheme 入参里的 unstable_sxConfig，后者即 sx(props) 的实现。函数命名中的 unstable_ 前缀与文档"实验性"的定位一致——它提供了 sx 的简写能力，但官方不承诺该 API 的长期稳定性。

Specificity：优先级规则

用主题方式定制组件后，仍然可以用 sx prop 覆盖它们——sx prop 具有更高的 CSS specificity，即使你在主题内部使用了实验性的 sx 语法也一样。这条优先级规则决定了调试顺序：当主题样式"不生效"时，先检查使用点是否有更高优先级的 sx 或 styled 在压制它。

Theme variables：通过主题变量影响全部实例

除了 components 键，还有另一种方式可以改变所有组件实例的外观：调整[主题配置变量]（theme configuration variables）。例如直接修改排版变量，让所有按钮文本统一使用 1rem：

const theme = createTheme({
  typography: {
    button: {
      fontSize: '1rem',
    },
  },
});

对应演示见 ThemeVariables.js。从源码看，这类变量（typography.button、components.MuiButton.styleOverrides 消费的 CSS 变量等）正是 createTheme 的变量版本 createThemeWithVars.js 所构建和注入的内容。

两种定制路径如何选型

需求	推荐手段
全局修改组件默认 props	components.MuiXxx.defaultProps
全局覆盖某插槽默认样式	components.MuiXxx.styleOverrides
按 prop 条件加样式 / 新增 variant	variants（props 支持对象与回调两种形式）
主题内使用 sx 简写	theme.unstable_sx（实验性）
微调全局视觉变量	主题配置变量（如 typography.button）
重度定制、需 tree-shaking	新建 styled / 包装组件（文档明确建议）

所有主题对象仍需用 ThemeProvider 注入应用才能生效；components 键的每个字段、合并逻辑与优先级均可在 components.ts、getThemeProps.ts、variants.ts 中对照源码验证。