Material UI 主题级样式覆盖的进化：styleOverrides 回调函数与 `theme.unstable_sx` 实战指南

2026-09-07 10:00:43作者：薛曦旖Francesca

本文基于当前 Material UI 仓库的博客与源码，系统讲解 Material UI v5.3.0 引入的一项关键能力：在全局主题（createTheme）的 styleOverrides 中直接编写回调函数，让开发者无需依赖繁复的 CSS class 命名，即可读取组件运行时 props（ownerState）与主题对象动态定制任意 slot 的样式；并进一步介绍在主题覆盖中使用 sx 简写语法（theme.unstable_sx）与数组返回值的进阶技巧。读完本文，你将掌握从“查 class 名称、改类名”到“读 props 写回调”的主题定制新范式，并能在自己的主题中立刻落地。

从问题说起：为什么 `styleOverrides` 需要回调？

在 v4 时代，Material UI 的样式引擎是 JSS，它无法在全局样式覆盖（style overrides）中通过回调读取组件运行时的动态 props。开发者只能被迫依赖预设的 CSS class 名称来命中不同状态下的元素。

以 Chip 为例，chipClasses.ts 中登记了大量组合类名：元素维度（root、avatar、icon、label、deleteIcon）、尺寸维度（small、medium、large）、颜色维度（primary、secondary 等）互相排列组合，类名数量远超 20 个，且仍难以覆盖全部形态。这种定制体验的痛点在于：开发者为了改一个内边距，必须先弄清楚当前状态下到底命中了哪个类名 key。

从当前仓库的 Chip 组件实现可以看到，即便在新版本中，useUtilityClasses 仍会根据 ownerState（disabled、size、color、onDelete、clickable、variant 等）拼接出诸如 sizeSmall、colorPrimary、clickable、deletable 之类的派生类名——这些正是为老式“按类名定制”机制保留的基石。但如果让开发者直接面向“变量”（size 是多少、variant 是什么）来写样式，就无须关心这些类名到底叫什么。

Material UI v5 的答案是把样式引擎替换为 Emotion，使样式可以基于渲染上下文求值。于是官方提出一个更直观的心智模型：你只需要知道组件某 slot 的名称，然后提供「对象」（静态覆盖）或「回调」（动态覆盖）两种形式之一：

对象 { ... }：静态覆盖，等价于过去的写法人人都会；
回调 (props) => ({ ... })：动态覆盖，根据组件实际收到的 props 返回样式对象。

下面我们先看回调在代码里最直接的落地。

在 `styleOverrides` 中使用回调：`ownerState` 与 `theme`

回调会收到该 slot 在渲染时接收到的 props，绝大多数场景你只会用到其中两个字段：

字段	含义
`props.ownerState`	运行时 props 与组件内部状态的组合。例如 `Chip` 的 `ownerState` 同时包含你传入的 `size`、`variant`、`color`，以及组件根据 props 计算出的 `disabled`、`clickable`、`onDelete` 等派生状态
`props.theme`	你在 `ThemeProvider` 中提供的主题对象；未提供时则为默认主题

下面的例子在全局层面对 MuiChip 做了动态定制：不同 size 使用不同内边距，outlined 变体加粗边框，主色变体的描边色取自调色板：

import { ThemeProvider, createTheme } from '@mui/material/styles';

<ThemeProvider
  theme={createTheme({
    components: {
      MuiChip: {
        styleOverrides: {
          // 你可以在回调里直接用 theme，无需预先在 createTheme 外部保存一份主题引用
          root: ({ ownerState, theme }) => ({
            padding: {
              small: '8px 4px',
              medium: '12px 6px',
              large: '16px 8px',
            }[ownerState.size],
            ...(ownerState.variant === 'outlined' && {
              borderWidth: '2px',
              ...(ownerState.variant === 'primary' && {
                borderColor: theme.palette.primary.light,
              }),
            }),
          }),
          label: {
            padding: 0,
          },
        },
      },
    },
  })}
>
  ...your app
</ThemeProvider>;

这里同时示范了两种覆盖的混用：root 使用回调实现动态样式，label 使用普通对象实现静态覆盖。回调的附带收益（原文特别强调）：回调内部闭包拿到了运行时 theme，因此在写 theme.palette.primary.light 之类的值时不再需要先创建外层作用域变量，代码可以完全内联在 createTheme 的字面量中。

组合展开的边界：object 也可以返回 CSS 片段

上面的回调在返回对象内部使用 ...(condition && {...}) 展开语法拼接条件分支。需要理解的是，条件表达式 ...(ownerState.variant === 'outlined' && {...}) 在条件为假时会展开 false，这种写法是 React/CSS-in-JS 领域常见的“条件对象展开”惯用法，等价于“满足条件才注入这一段样式”。这种方式适合分支较少的情形；当条件较多时，更推荐使用下文“数组作为返回值”的写法，让每个条件独立成项、易于增删。

回调背后：源码是如何执行的？

从源码结构看，回调并不是语法糖魔法，而是由系统样式的求值管线显式支持。在 packages/mui-system/src/createStyled/createStyled.js 的 processStyle 中，第一行就做了关键判断：

const resolvedStyle = typeof style === 'function' ? style(props) : style;

也就是说，凡是出现在样式参数位置的函数，都会被统一“以渲染时的 props 调用一次”，取其返回值作为真正的样式；对象则原样透传。同理，styleThemeOverrides（createStyled.js）会从 theme.components[componentName].styleOverrides 中取出你配置的覆盖，遍历每个 slotKey，逐一对 styleOverrides[slotKey] 调用 processStyle 完成“对象透传 / 函数求值”，最终交给该组件的 overridesResolver 把解析后的样式投递到对应 slot 上。Chip 的 overridesResolver 可以在 Chip.js 看到——它会把解析出的 root、按尺寸/颜色派生的样式段合并到根元素。

因此，你在 styleOverrides 中能写回调，本质是因为主题结构（components.MuiChip.styleOverrides）中 slot 的值允许为函数，且渲染管线始终以 props 为入参求值。主题的类型结构同样反映这一点，见 components.ts 中每个组件 styleOverrides 字段的声明。仓库中的组件测试（例如 packages/mui-material/src/Chip/Chip.test.js）也大量覆盖了通过 styleOverrides 定制主题后组件类名与样式的生成情况，可作为实际行为是否与预期一致的验证入口。

TypeScript：回调是类型安全的

回调的参数类型由系统推导，无需手动标注：

ownerState：对应组件的 ComponentProps 接口，例如 ChipProps、ButtonProps；
theme：@mui/material/styles 导出的 Theme 接口。

{
  MuiChip: {
    styleOverrides: {
      // ownerState: ChipProps
      // theme: Theme
      root: ({ ownerState, theme }) => ({...}),
    },
  }
}

当你通过模块扩充（module augmentation）扩展组件变体时，新声明的 props 会立刻出现在 ownerState.variant 的联合类型中。例如给 Button 增加一个 dashed 变体：

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

之后在 MuiButton 的 styleOverrides.root 回调里写 ownerState.variant === 'dashed'，TypeScript 就会放行并对其他字符串字面量报错——这就是模块扩充带来的“类型驱动开发”体验。theme 对象同样支持通过 declare module '@mui/material/styles' 扩充 Theme 接口，自定义的调色板、形状字段都能被回调里的 theme.xxx 正确识别。

进阶：在主题覆盖里使用 `sx` 语法（`unstable_sx`）

sx 最初被设计为给 styled API 创建的组件注入简写样式的 prop：

import { styled } from '@mui/material/styles';
import Box from '@mui/material/Box';

const Label = styled('span')({
  fontWeight: 'bold',
  fontSize: '0.875rem',
})

<Box sx={{ display: 'flex' }}>
  <Label sx={{ color: 'text.secondary' }}>Label</Label>
</Box>;

所有 Material UI 与 Joy UI 组件都是用 styled API 创建的，因此默认都接受 sx prop。

sx 的价值在于：熟悉之后，一行简写即可替代一大段样板代码，例如 px、py 是左右/上下内边距的简写，color: 'text.secondary' 这类 theme-aware 颜色则免去手动从调色板取值。

既然 styleOverrides 支持了回调，那么「在全局主题覆盖里享受同样的 sx 简写语法」就顺理成章：只需调用主题上的 unstable_sx 函数。下面把 Chip 的 root 改写为 sx 风格：

import { ThemeProvider, createTheme } from '@mui/material/styles';

<ThemeProvider
  theme={createTheme({
    components: {
      MuiChip: {
        styleOverrides: {
          root: ({ theme }) =>
            theme.unstable_sx({
              px: '12px', // shorthand for padding-left & right
              py: '6px', // shorthand for padding-top & bottom
              fontWeight: 500,
              borderRadius: '8px',
            }),
          label: {
            padding: 0,
          },
        },
      },
    },
  })}
>
  ...your app
</ThemeProvider>;

theme.unstable_sx 的实现同样可以佐证：在 createThemeNoVars.js 中，它本质上是把传入的 sx 对象包成 { sx: props, theme } 交给 styleFunctionSx 求值，其可识别的简写配置来自 theme.unstable_sxConfig（默认合并了 defaultSxConfig）。因此凡是在组件 sx prop 上能用的能力——theme-aware 属性、简写、断点响应式对象——在 theme.unstable_sx 里都同样可用。

数组返回值：把条件分支拆成独立样式项

再叠加条件逻辑：假设还需要实现两个规则——

当 <Chip variant="outlined" /> 时，描边色用 palette.text.secondary（主题感知写法即 'text.secondary'）；
当 <Chip size="small" /> 时，字号在移动端视口为 0.875rem、更大视口为 0.75rem。

此时若仍用对象展开拼接，条件一多代码会迅速变得难以增删。改用数组作为回调返回值，每个条件独立成一项，false 项会被自然过滤：

// 为可读性省略 <ThemeProvider>。
{
  root: ({ ownerState, theme }) => [
    theme.unstable_sx({
      px: '12px',
      py: '6px',
      fontWeight: 500,
      borderRadius: '8px',
    }),
    ownerState.variant === 'outlined' && ownerState.color === 'default' &&
      theme.unstable_sx({
        borderColor: 'text.secondary',
      }),
    ownerState.size === 'small' &&
      theme.unstable_sx({
        fontSize: { xs: '0.875rem', sm: '0.75rem' },
      })
  ],
}

这个写法有两个关键支撑点：

数组是合法的样式返回类型：在 createStyled.js 的 processStyle 中，数组返回值会被 flatMap 逐项递归解析，因此可以嵌套、可以包含 false 与 null 等空值；
theme.unstable_sx 的返回值可直接作为样式对象的一部分，多个 sx 调用 + 条件分支最终合并为同一数组，交由 Emotion 处理，顺序即优先级顺序——想要调整某条规则是否覆盖另一条，只需要调整数组中的位置。

fontSize: { xs: '0.875rem', sm: '0.75rem' } 这一写法是响应式断点对象：xs 为默认，sm 及以上视口应用 0.75rem，这正是 sx 体系区别于普通 CSS-in-JS 对象的“降维打击”能力——在全局主题里定制响应式样式不再需要手写 @media 查询。

性能与适用边界提示

「回调 + unstable_sx」的功能非常强大，但它属于全局主题覆盖，回调会在相关组件渲染时执行；且 sx 解析相对原生 CSS-in-JS 对象多一层系统运算。对单次渲染、低频更新的全局覆盖，这部分开销通常可忽略；但如果追求极致性能，仍可考虑把不依赖 props 的部分写成纯对象，仅把动态分支放进回调。原文档亦在文末给出了 sx 性能权衡的进一步说明，值得一读。此外，全局覆盖会影响该组件的所有实例，请务必确认你希望这样的“全局默认值”语义（而不是某个页面的局部差异）。

版本前提与兼容性说明

回调形式的 styleOverrides 与 theme.unstable_sx 自 Material UI v5.3.0 起可用（这是原文发布时的版本事实）。此后该机制持续演进：在当前仓库的 createStyled.js 实现中仍可看到 TODO: v7、TODO v6 等维护注释，表明这段求值管线在后续大版本中被持续重构与保留，但其「函数即回调、对象即静态」的 API 形态对开发者是稳定的。若项目低于 v5.3.0，请先升级后使用。