Material UI v5 组件层破坏性变更完整迁移手册（基于 v4 到 v5 官方迁移文档）

本文是一份面向从 Material UI v4 升级到 v5 的开发者的参考型迁移指南，内容完整覆盖官方迁移文档中第二部分——**核心组件（core components）**的全部破坏性变更：从 import 路径迁移、prop 重命名、CSS 类名与 DOM 结构调整，到主题（Theme）与断点（Breakpoints）行为变化。读完本文，你将能够逐组件核对并修复 v4 代码中所有与组件 API、样式类名、事件类型和主题配置相关的破坏性变更，配合仓库中现成的 codemod（自动化迁移脚本）完成绝大部分机械性替换，并对手动项给出可落地的替代方案。

适用前提：本文所述的 v5 变更以官方迁移文档 v5-component-changes.md 为骨架编写。当前仓库中 mui-material 主包版本为 9.x（见 packages/mui-material/package.json），本文描述的是 v4→v5 那次跨越性的 API 演进，文中所有以 @mui/* 开头的导入路径与代码示例均以 v5 及之后的包结构为准。

迁移系列文章与自动化工具

本文是 Material UI v5 迁移指南系列的第 2 部分（组件篇），完整阅读路径如下，建议按顺序进行：

1. 迁移入门（Getting started）
2. 破坏性变更第一部分：样式与主题
3. 破坏性变更第二部分：组件（本文）
4. 从 JSS 迁移
5. 故障排查（Troubleshooting）

v5 相对 v4 引入了大量破坏性变更。好消息是，其中很多变更可以用 codemod 自动解决——请在动手前先阅读主迁移指南中的 运行 codemod 一节，把能自动处理的项先批量处理掉。

:::warning 需要注意 在本文目录中，凡是已经由 codemod 自动处理的变更项都用 ✅ emoji 标注。如果你已经按照主迁移指南的指引运行过 codemod，那么这些 ✅ 项通常无需再手动处理；其余所有变更必须手动逐个修复。 :::

codemod 的实现在当前仓库的 packages/mui-codemod/src/v5.0.0 目录下，包含 preset-safe（安全预设）、variant-prop、link-underline-hover、box-sx-prop、expansion-panel-component 等数十个独立迁移脚本，每个脚本都配有对应的 .test/ 目录与测试文件，可以作为理解每个变更规则的权威依据。

Emotion 作为样式引擎后的一个隐含变化

由于 v5 核心组件改用 Emotion 作为样式引擎，Emotion 自身的 props 不再被组件拦截。例如下面代码中的 as prop 将不会被透传给 SomeOtherComponent：

<MuiComponent component={SomeOtherComponent} as="button" />

AccordionSummary

将 expandIcon 改名为 expandIconWrapper

此次改名是为了更清晰地表达"该元素是图标的包装层而非图标本身"。需要同步更新 CSS 类名与主题覆盖中的 key：

-'.MuiAccordionSummary-expandIcon': {
+'.MuiAccordionSummary-expandIconWrapper': {

 createTheme({
   components: {
     MuiAccordionSummary: {
       styleOverrides: {
-        expandIcon: {
+        expandIconWrapper: {
          // ...
         },
       },
     },
   },
 });

从当前源码可以印证这一命名：packages/mui-material/src/AccordionSummary/AccordionSummary.js 中生成类名 expandIconWrapper: ['expandIconWrapper', expanded && 'expanded']，并通过 useSlot('expandIconWrapper', ...) 渲染图标包装层；其测试文件 AccordionSummary.test.js 也断言"展开内容位于 div.expandIconWrapper 内"且展开时会为它追加 expanded 类。

AppBar

修复 z-index 问题

当 position 为 static 与 relative 时不再设置 z-index，以避免创建层叠上下文（stacking context）引发的渲染问题。

深色模式下的 color prop 替换

深色模式下 color prop 不再生效——AppBar 使用由 elevation（抬升高度）决定的背景色，以遵循 Material Design 深色主题规范。如需恢复 v4 行为，使用 enableColorOnDark：

<AppBar enableColorOnDark />

Alert

✅ 更新 import 路径

组件从 lab 移入 core，现已稳定：

-import Alert from '@mui/lab/Alert';
-import AlertTitle from '@mui/lab/AlertTitle';
+import Alert from '@mui/material/Alert';
+import AlertTitle from '@mui/material/AlertTitle';

Autocomplete

✅ 更新 import 路径

-import Autocomplete from '@mui/lab/Autocomplete';
-import useAutocomplete  from '@mui/lab/useAutocomplete';
+import Autocomplete from '@mui/material/Autocomplete';
+import useAutocomplete from '@mui/material/useAutocomplete';

移除 debug prop

debug prop 被移除。更简单的替代方案包括：open={true} 保持展开、使用 Chrome 开发者工具的 "Emulate focused"（模拟聚焦）功能、或用 React devtools 的 prop setter 查看状态。

更新 renderOption

renderOption 现在需要返回选项的完整 DOM 结构，这让自定义变得更容易。你可以这样迁移：

 <Autocomplete
-  renderOption={(option, { selected }) => (
-    <React.Fragment>
+  renderOption={(props, option, { selected }) => (
+    <li {...props}>
       <Checkbox
         icon={icon}
         checkedIcon={checkedIcon}
         style={{ marginRight: 8 }}
         checked={selected}
       />
       {option.title}
-    </React.Fragment>
+    </li>
   )}
 />

✅ 将 closeIcon 改名为 clearIcon

为避免歧义，closeIcon 更名为 clearIcon：

-<Autocomplete closeIcon={defaultClearIcon} />
+<Autocomplete clearIcon={defaultClearIcon} />

重命名 reason 参数取值

onChange 与 onClose 的 reason 参数取值做了统一，注意大小写驼峰化：

1. create-option → createOption
2. select-option → selectOption
3. remove-option → removeOption

同时，针对聚焦选项的 CSS 规则需要从 [data-focus="true"] 改为全局类名 .Mui-focused——聚焦选项上不再设置 data-focus 属性：

-'.MuiAutocomplete-option[data-focus="true"]': {
+'.MuiAutocomplete-option.Mui-focused': {

✅ 将 getOptionSelected 改名为 isOptionEqualToValue

更名后能更准确地表达其用途（判断选项与值是否相等）：

 <Autocomplete
-  getOptionSelected={(option, value) => option.title === value.title}
+  isOptionEqualToValue={(option, value) => option.title === value.title}

Avatar

✅ 将 circle 改名为 circular

-<Avatar variant="circle">
-<Avatar classes={{ circle: 'className' }}>
+<Avatar variant="circular">
+<Avatar classes={{ circular: 'className' }}>

由于 circular 已是默认值，variant prop 可以直接删除：

-<Avatar variant="circle">
+<Avatar>

当前源码 Avatar.d.ts 中 variant 类型即 'circular' | 'rounded' | 'square'，且 @default 'circular'，可作佐证。

✅ 更新 AvatarGroup import

-import AvatarGroup from '@mui/lab/AvatarGroup';
+import AvatarGroup from '@mui/material/AvatarGroup';

Badge

✅ 重命名 circle 与 rectangle

circle → circular、rectangle → rectangular，以求命名一致：

-<Badge overlap="circle">
-<Badge overlap="rectangle">
+<Badge overlap="circular">
+<Badge overlap="rectangular">

同时所有锚点相关的 classes key 也要同步改名：

 <Badge classes={{
-  anchorOriginTopRightRectangle: 'className',
-  anchorOriginBottomRightRectangle: 'className',
-  anchorOriginTopLeftRectangle: 'className',
-  anchorOriginBottomLeftRectangle: 'className',
-  anchorOriginTopRightCircle: 'className',
-  anchorOriginBottomRightCircle: 'className',
-  anchorOriginTopLeftCircle: 'className',
+  anchorOriginTopRightRectangular: 'className',
+  anchorOriginBottomRightRectangular: 'className',
+  anchorOriginTopLeftRectangular: 'className',
+  anchorOriginBottomLeftRectangular: 'className',
+  anchorOriginTopRightCircular: 'className',
+  anchorOriginBottomRightCircular: 'className',
+  anchorOriginTopLeftCircular: 'className',
 }}>

BottomNavigation

更新事件类型（TypeScript）

onChange 的 event 类型由 React.ChangeEvent 改为 React.SyntheticEvent：

-<BottomNavigation onChange={(event: React.ChangeEvent<{}>) => {}} />
+<BottomNavigation onChange={(event: React.SyntheticEvent) => {}} />

BottomNavigationAction

移除 span 与 wrapper

包裹 children 的 span 元素被移除，wrapper 类 key 也一并删除（细节见当时的 GitHub PR #26923）：

 <button class="MuiBottomNavigationAction-root">
-  <span class="MuiBottomNavigationAction-wrapper">
     {icon}
     <span class="MuiBottomNavigationAction-label">
       {label}
     </span>
-  </span>
 </button>

Box

✅ 更新 borderRadius prop 值变换规则

borderRadius 这个 system prop 的值转换逻辑发生了改变：如果传入数字，会用该数字乘以 theme.shape.borderRadius 的值；要给出明确的像素值，请使用字符串：

-<Box borderRadius="borderRadius">
+<Box borderRadius={1}>

-<Box borderRadius={16}>
+<Box borderRadius="16px">

✅ 使用 sx API

v5 中 Box 的 system props 有了一套可选的替代 API——sx prop。关于两套 API 的权衡可参见 MUI System 文档中的 "API tradeoff" 一节：

<Box border="1px dashed grey" p={[2, 3, 4]} m={2}>
<Box sx={{ border: "1px dashed grey", p: [2, 3, 4], m: 2 }}>

✅ 重命名 CSS 属性

以下属性在 CSS 规范中已被视为废弃写法，故做更名：

1. gridGap → gap
2. gridColumnGap → columnGap
3. gridRowGap → rowGap

-<Box gridGap={1}>
-<Box gridColumnGap={2}>
-<Box gridRowGap={3}>
+<Box gap={1}>
+<Box columnGap={2}>
+<Box rowGap={3}>

:::info 补充 v4 中并未文档化 system 的 grid 相关函数。 :::

移除 clone prop

clone prop 被移除，因为其行为可以通过直接把 sx prop 应用到子元素（若它是 Material UI 组件）来获得：

-<Box sx={{ border: '1px dashed grey' }} clone>
-  <Button>Save</Button>
-</Box>
+<Button sx={{ border: '1px dashed grey' }}>Save</Button>

用 sx 取代 render prop

传入 render prop 的能力被移除——若子元素是 Material UI 组件，直接给它应用 sx 即可：

-<Box sx={{ border: '1px dashed grey' }}>
-  {(props) => <Button {...props}>Save</Button>}
-</Box>
+<Button sx={{ border: '1px dashed grey' }}>Save</Button>

对于非 Material UI 组件，改用 component prop：

-<Box sx={{ border: '1px dashed grey' }}>
-  {(props) => <button {...props}>Save</button>}
-</Box>
+<Box component="button" sx={{ border: '1px dashed grey' }}>Save</Box>

Button

✅ 移除默认 color prop

按钮 color prop 的默认值改为 "primary"，且 "default" 取值被移除。这让按钮更贴近 Material Design 规范并简化 API：

-<Button color="default">
+<Button>

:::info 补充 如果你确实希望保留 v4 中的 default 配色外观，v5 中需要通过主题自定义来实现（原文档提供了一个演示如何复刻 v4 default 按钮配色的 CodeSandbox 示例）。 :::

移除 span 与 label

包裹 children 的 span 元素被移除，label 类 key 也被删除（该包裹层当初是为了兼容 iOS 才存在的，见当时的 GitHub PR #26666）：

 <button class="MuiButton-root">
-  <span class="MuiButton-label">
     children
-  </span>
 </button>

Chip

✅ 将 default 变体改名为 filled

-<Chip variant="default">
+<Chip>

由于 filled 已是默认值，variant prop 可以直接删除。

Checkbox

默认颜色改为 "primary"

checkbox 的 color prop 默认值现在是 "primary"。要继续使用 "secondary"，必须显式声明：

-<Checkbox />
+<Checkbox color="secondary" />

这使 checkbox 更贴近 Material Design 规范。

更新 CSS 类名

该组件不再有 .MuiIconButton-root 与 .MuiIconButton-label 类名，请改而定位 .MuiButtonBase-root：

-<span class="MuiIconButton-root MuiButtonBase-root MuiCheckbox-root PrivateSwitchBase-root">
-  <span class="MuiIconButton-label">
-    <input class="PrivateSwitchBase-input">
+<span class="MuiButtonBase-root MuiCheckbox-root PrivateSwitchBase-root">
+  <span class="PrivateSwitchBase-input">

CircularProgress

✅ 将 static 改名为 determinate

static 变体更名为 determinate，且原先 determinate 的外观被 static 的外观取代。这本来就是对 Material Design 规范的一个例外，现已从规范中移除：

-<CircularProgress variant="static" classes={{ static: 'className' }} />
+<CircularProgress variant="determinate" classes={{ determinate: 'className' }} />

:::error 特别注意 如果你之前自定义过 determinate 变体，那么你的自定义很可能已不再生效，请移除这些自定义。 :::

Collapse

✅ 将 collapsedHeight 改名为 collapsedSize

重命名是为了支持水平方向的折叠：

-<Collapse collapsedHeight={40}>
+<Collapse collapsedSize={40}>

同时 classes.container key 按其他组件的惯例改名为 classes.root：

-<Collapse classes={{ container: 'collapse' }}>
+<Collapse classes={{ root: 'collapse' }}>

CssBaseline

更新样式引擎

组件从 jss 迁移到 @mui/styled-engine（底层是 emotion 或 styled-components）。因此为它定义 style overrides 时应移除 @global 这一层 key，也可以开始用 CSS 模板字符串语法替代 JS 对象语法：

 const theme = createTheme({
   components: {
     MuiCssBaseline: {
-      styleOverrides: {
-        '@global': {
-          html: {
-            WebkitFontSmoothing: 'auto',
-          },
-        },
-      },
+      styleOverrides: `
+        html {
+          -webkit-font-smoothing: auto;
+        }
+      `
     },
   },
 });

body 字体大小变化

body 的字体大小从 theme.typography.body2（0.875rem）改为 theme.typography.body1（1rem）。要恢复旧尺寸，可在主题中覆盖：

const theme = createMuiTheme({
  components: {
    MuiCssBaseline: {
      styleOverrides: {
        body: {
          fontSize: '0.875rem',
          lineHeight: 1.43,
          letterSpacing: '0.01071em',
        },
      },
    },
  },
});

Dialog

✅ 更新过渡动画 props

on* 系列过渡 props 被移除，请改用 TransitionProps：

  <Dialog
-  onEnter={onEnter}
-  onEntered={onEntered}
-  onEntering={onEntering}
-  onExit={onExit}
-  onExited={onExited}
-  onExiting={onExiting}
+  TransitionProps={{
+    onEnter,
+    onEntered,
+    onEntering,
+    onExit,
+    onExited,
+    onExiting,
+  }}
  >

✅ 移除 disableBackdropClick prop

该 prop 已显冗余而被移除。改为在 onClose 中忽略 reason === 'backdropClick' 的关闭事件：

  <Dialog
-  disableBackdropClick
-  onClose={handleClose}
+  onClose={(event, reason) => {
+    if (reason !== 'backdropClick') {
+      handleClose(event, reason);
+    }
+  }}
  />

移除 withMobileDialog 组件

withMobileDialog 高阶组件被移除。

:::warning 注意 在 preset-safe codemod 中会用硬编码函数来避免应用直接崩溃，但仍需要进一步的修复。 :::

hook 化 API 提供了更简单、更灵活的方案：

-import withMobileDialog from '@mui/material/withMobileDialog';
+import { useTheme, useMediaQuery } from '@mui/material';

 function ResponsiveDialog(props) {
-  const { fullScreen } = props;
+  const theme = useTheme();
+  const fullScreen = useMediaQuery(theme.breakpoints.down('sm'));
   const [open, setOpen] = React.useState(false);

 // ...

-export default withMobileDialog()(ResponsiveDialog);
+export default ResponsiveDialog;

✅ 移除 disableTypography prop

DialogTitle 的 DOM 结构被扁平化，disableTypography prop 被移除：

-<DialogTitle disableTypography>
-  <Typography variant="h4" component="h2">
+<DialogTitle>
+  <Typography variant="h4" component="span">
      My header
   </Typography>

Divider

用 border-color 替代 background-color

改用 border-color 而非 background-color，可避免在屏幕缩放时产生不一致的线宽。如果自定义过分隔线颜色，需要改 CSS 属性：

 .MuiDivider-root {
-  background-color: #f00;
+  border-color: #f00;
 }

支持 "middle" 变体搭配 "vertical" 方向

v4 中，同时使用 orientation="vertical" 与 variant="middle" 时，组件会添加左右各 16px 的 margin。v5 为了避免组件内写死间距，移除了这个 margin。

:::info 补充 如果想保留原来的 margin 值，可在主题中用如下代码实现（原文档附带了一个可运行的 CodeSandbox 示例）： :::

 const theme = createTheme({
  components: {
   MuiDivider: {
+     styleOverrides: {
+       root: ({ ownerState, theme }) => ({
+         ...(ownerState.orientation === 'vertical' && ownerState.variant === 'middle' && {
+           marginLeft: theme.spacing(2),
+           marginRight: theme.spacing(2),
+         }),
+       })
+     }
    },
  },
 });

ExpansionPanel（→ Accordion）

✅ 重命名组件

ExpansionPanel 系列改名为 Accordion，以使用更通用的命名习惯：

-import ExpansionPanel from '@mui/material/ExpansionPanel';
-import ExpansionPanelSummary from '@mui/material/ExpansionPanelSummary';
-import ExpansionPanelDetails from '@mui/material/ExpansionPanelDetails';
-import ExpansionPanelActions from '@mui/material/ExpansionPanelActions';
+import Accordion from '@mui/material/Accordion';
+import AccordionSummary from '@mui/material/AccordionSummary';
+import AccordionDetails from '@mui/material/AccordionDetails';
+import AccordionActions from '@mui/material/AccordionActions';

-<ExpansionPanel>
+<Accordion>
-  <ExpansionPanelSummary>
+  <AccordionSummary>
      <Typography>Location</Typography>
      <Typography>Select trip destination</Typography>
-  </ExpansionPanelSummary>
+  </AccordionSummary>
-  <ExpansionPanelDetails>
+  <AccordionDetails>
      <Chip label="Barbados" onDelete={() => {}} />
      <Typography variant="caption">Select your destination of choice</Typography>
-  </ExpansionPanelDetails>
+  </AccordionDetails>
    <Divider />
-  <ExpansionPanelActions>
+  <AccordionActions>
      <Button size="small">Cancel</Button>
      <Button size="small">Save</Button>
-  </ExpansionPanelActions>
+  </AccordionActions>
-</ExpansionPanel>
+</Accordion>

更新事件类型（TypeScript）

-<Accordion onChange={(event: React.ChangeEvent<{}>, expanded: boolean) => {}} />
+<Accordion onChange={(event: React.SyntheticEvent, expanded: boolean) => {}} />

ExpansionPanelDetails（→ AccordionDetails）

移除 display: flex

AccordionDetails（原 ExpansionPanelDetails）不再设置 display: flex——原实现过于主观，大多数开发者期望的是 display: block。

ExpansionPanelSummary（→ AccordionSummary）

将 focused 改名为 focusVisible

 <AccordionSummary
   classes={{
-    focused: 'custom-focus-visible-classname',
+    focusVisible: 'custom-focus-visible-classname',
   }}
 />

移除 IconButtonProps prop

IconButtonProps prop 从 AccordionSummary（原 ExpansionPanelSummary）移除——组件现在渲染的是 <div> 而非 IconButton，该 prop 不再必要。

Fab

✅ 将 round 改名为 circular

-<Fab variant="round">
+<Fab variant="circular">

移除 span 与 label

 <button class="MuiFab-root">
-  <span class="MuiFab-label">
     {children}
-  </span>
 </button>

label 类 key 一并删除（包裹层当初为 iOS 兼容所需，见 PR #27112）。

FormControl

✅ 更新默认变体

默认变体从 standard 改为 outlined，因为 standard 已从 Material Design 规范中移除：

:::success 提示 该变更由 variant-prop codemod 处理——运行前请先阅读其说明。 :::

-<FormControl value="Standard" />
-<FormControl value="Outlined" variant="outlined" />
+<FormControl value="Standard" variant="standard" />
+<FormControl value="Outlined" />

FormControlLabel

label prop 变为必填

label prop 现在是必填的。如果你曾使用没有 label 的 FormControlLabel，直接替换为 control prop 的值即可：

-<FormControlLabel control={<Checkbox />} />
+<Checkbox />

Grid

✅ 将 justify 改名为 justifyContent

-<Grid justify="center">
+<Grid justifyContent="center">

✅ 移除 align / justify 相关 props 与 classes

alignItems、alignContent、justifyContent 这三个 props 以及它们对应的 classes 与 style overrides key 被移除，涉及："align-items-xs-center"、"align-items-xs-flex-start"、"align-items-xs-flex-end"、"align-items-xs-baseline"、"align-content-xs-center"、"align-content-xs-flex-start"、"align-content-xs-flex-end"、"align-content-xs-space-between"、"align-content-xs-space-around"、"justify-content-xs-center"、"justify-content-xs-flex-end"、"justify-content-xs-space-between"、"justify-content-xs-space-around"、"justify-content-xs-space-evenly"。

这些能力现在被视为 MUI System 的一部分，而非 Grid 组件自身所有。如果你仍想为其添加 overrides，可在 styleOverrides 中使用回调函数（基于 props 做条件覆盖）：

 const theme = createTheme({
   components: {
     MuiGrid: {
-      styleOverrides: {
-        'align-items-xs-flex-end': {
-          marginTop: 20,
-        },
-      },
+      styleOverrides: ({ ownerState }) => ({
+        ...ownerState.alignItems === 'flex-end' && {
+          marginTop: 20,
+        },
+      }),
     },
   },
 });

负 margin 行为变化

v4 的 Grid 负 margin 只在容器的顶部与左侧生效。如果需要在所有方向都有负 margin，官方建议改用新版 Grid v2：

- import Grid from '@mui/material/Grid';
+ import Grid from '@mui/material/Grid2';

:::info 补充 Grid2 在 Material UI v5.9.1 中引入，默认在所有方向都带负 margin。更多内容可参考 Grid 组件文档 与 升级到 Grid v2 指南。从当前仓库 packages/mui-material/src/ 的目录结构可以确认 Grid 与 Grid2 是并存的两个独立组件目录。 :::

GridList（→ ImageList）

✅ 重命名组件

GridList 系列改名为 ImageList，以对齐当前 Material Design 的命名。

重命名 GridList 相关 props

• GridList 的 spacing prop 改名为 gap（对齐 CSS 属性名）；
• GridList 的 cellHeight prop 改名为 rowHeight；
• 为 GridList 新增 variant prop；
• GridListItemBar 的 actionPosition prop 改名为 position（相关 class 名同步变化）。

改用 CSS object-fit

图片改用 CSS object-fit。如需兼容 IE 11，要么使用 polyfill（如 object-fit-images 这类 npm 包），要么继续使用 v4 组件。

-import GridList from '@mui/material/GridList';
-import GridListTile from '@mui/material/GridListTile';
-import GridListTileBar from '@mui/material/GridListTileBar';
+import ImageList from '@mui/material/ImageList';
+import ImageListItem from '@mui/material/ImageListItem';
+import ImageListItemBar from '@mui/material/ImageListItemBar';

-<GridList spacing={8} cellHeight={200}>
-  <GridListTile>
+<ImageList gap={8} rowHeight={200}>
+  <ImageListItem>
    <img src="file.jpg" alt="Image title" />
-    <GridListTileBar
+    <ImageListItemBar
      title="Title"
      subtitle="Subtitle"
    />
-  </GridListTile>
-</GridList>
+  </ImageListItem>
+</ImageList>

Hidden

替换已废弃组件

该组件已被废弃，因为其功能完全可以用 sx prop 或 useMediaQuery hook 实现。

:::success 提示 preset-safe codemod 会通过注入一个假的 Hidden 组件来避免应用崩溃，但仍需要进一步的修复。 :::

用 sx prop 替代 implementation="css"：

-<Hidden implementation="css" xlUp><Paper /></Hidden>
-<Hidden implementation="css" xlUp><button /></Hidden>
+<Paper sx={{ display: { xl: 'none', xs: 'block' } }} />
+<Box component="button" sx={{ display: { xl: 'none', xs: 'block' } }} />

-<Hidden implementation="css" mdDown><Paper /></Hidden>
-<Hidden implementation="css" mdDown><button /></Hidden>
+<Paper sx={{ display: { xs: 'none', md: 'block' } }} />
+<Box component="button" sx={{ display: { xs: 'none', md: 'block' } }} />

用 useMediaQuery hook 替代 implementation="js"：

-<Hidden implementation="js" xlUp><Paper /></Hidden>
+const hidden = useMediaQuery(theme => theme.breakpoints.up('xl'));
+return hidden ? null : <Paper />;

Icon

移除 fontSize="default"

fontSize 的默认值从 default 改为 medium 以保持一致。若你在使用取值 default（这种情况很少见），直接删除该 prop 即可：

-<Icon fontSize="default">icon-name</Icon>
+<Icon>icon-name</Icon>

IconButton

✅ 更新 size prop

默认尺寸的内边距缩小到 8px，因此整体从 48px 降到 40px。要保留旧的 48px 默认尺寸，请使用 size="large"。该改动是为了在 Material Design 不再文档化 icon button 模式后，更贴近 Google 自身产品：

- <IconButton>
+ <IconButton size="large">

移除 span 与 label

 <button class="MuiIconButton-root">
-  <span class="MuiIconButton-label">
     <svg />
-  </span>
 </button>

Link

✅ 更新默认 underline prop

underline prop 的默认值从 "hover" 改为 "always"。要复刻 v4 行为，在主题中配置 defaultProps：

:::success 提示 该变更由 link-underline-hover codemod 处理——运行前请先阅读其说明。 :::

createTheme({
  components: {
    MuiLink: {
      defaultProps: {
        underline: 'hover',
      },
    },
  },
});

Menu

✅ 更新过渡动画 props

 <Menu
-  onEnter={onEnter}
-  onEntered={onEntered}
-  onEntering={onEntering}
-  onExit={onExit}
-  onExited={onExited}
-  onExiting={onExiting}
+  TransitionProps={{
+    onEnter,
+    onEntered,
+    onEntering,
+    onExit,
+    onExited,
+    onExiting,
+  }}
 >

:::info 补充 selectedMenu 变体将不再把选中项与锚点做垂直对齐。 :::

修改默认 anchorOrigin.vertical 取值

anchorOrigin.vertical 的默认值按 Material Design 规范调整，菜单现在显示在锚点下方而非覆盖在锚点上。可恢复旧行为：

 <Menu
+  anchorOrigin={{
+    vertical: 'top',
+    horizontal: 'left',
+  }}

MenuItem

更新 CSS 类名

MenuItem 改为继承 ButtonBase 而不是 ListItem。所有 MuiListItem-* 相关类名被移除，且对 ListItem 的主题定制不再影响 MenuItem：

-<li className="MuiButtonBase-root MuiMenuItem-root MuiListItem-root">
+<li className="MuiButtonBase-root MuiMenuItem-root">

用 classes 取代 listItemClasses prop

-<MenuItem listItemClasses={{...}}>
+<MenuItem classes={{...}}>

更多信息参见 MenuItem CSS API 文档。

Modal

✅ 移除 disableBackdropClick prop

改用 onClose 配合 reason === 'backdropClick'：

 <Modal
-  disableBackdropClick
-  onClose={handleClose}
+  onClose={(event, reason) => {
+    if (reason !== 'backdropClick') {
+      handleClose(event, reason);
+    }
+  }}
 />

✅ 移除 onEscapeKeyDown prop

改用 onClose 配合 reason === "escapeKeyDown"：

 <Modal
-  onEscapeKeyDown={handleEscapeKeyDown}
+  onClose={(event, reason) => {
+    if (reason === 'escapeKeyDown') {
+      handleEscapeKeyDown(event);
+    }
+  }}
 />

移除 onRendered prop

onRendered prop 被移除。视使用场景，可以在子元素上用 callback ref，或在子组件内用 effect hook 替代。

NativeSelect

移除 selectMenu slot

selectMenu slot 因冗余被合并进 select。root slot 不再应用于 select 元素本身，而是应用于根元素：

-<NativeSelect classes={{ root: 'class1', select: 'class2', selectMenu: 'class3' }} />
+<NativeSelect classes={{ select: 'class1 class2 class3' }} />

OutlinedInput

移除 labelWidth prop

labelWidth prop 被移除。现在 label prop 承担同一职责——渲染 outlined 缺口改用 CSS 布局而非 JavaScript 测量：

-<OutlinedInput labelWidth={20} />
+<OutlinedInput label="First Name" />

Paper

深色模式背景透明度变化

深色模式下背景透明度随 elevation 变化，以更贴合 Material Design 规范。可在主题中还原：

 const theme = createTheme({
   components: {
     MuiPaper: {
+      styleOverrides: { root: { backgroundImage: 'unset' } },
     },
   },
 });

Pagination

✅ 更新 import

组件从 lab 移入 core，现已稳定：

-import Pagination from '@mui/lab/Pagination';
-import PaginationItem from '@mui/lab/PaginationItem';
-import { usePagination } from '@mui/lab/Pagination';
+import Pagination from '@mui/material/Pagination';
+import PaginationItem from '@mui/material/PaginationItem';
+import usePagination from '@mui/material/usePagination';

✅ 将 round 改名为 circular

-<Pagination shape="round">
-<PaginationItem shape="round">
+<Pagination shape="circular">
+<PaginationItem shape="circular">

Popover

✅ 更新过渡动画 props

  <Popover
-  onEnter={onEnter}
-  onEntered={onEntered}
-  onEntering={onEntering}
-  onExit={onExit}
-  onExited={onExited}
-  onExiting={onExiting}
+  TransitionProps={{
+    onEnter,
+    onEntered,
+    onEntering,
+    onExit,
+    onExited,
+    onExiting,
+  }}
  >

移除 getContentAnchorEl prop

为简化定位逻辑，getContentAnchorEl prop 被移除。

Popper

从 v1 升级到 v2

底层的 Popper.js 从 v1 升级到 v2。CSS 前缀发生了变化：

  popper: {
    zIndex: 1,
-  '&[x-placement*="bottom"] .arrow': {
+  '&[data-popper-placement*="bottom"] .arrow': {

方法名也发生变化：

-popperRef.current.scheduleUpdate()
+popperRef.current.update()

-popperRef.current.update()
+popperRef.current.forceUpdate()

Popper.js 的 Modifiers API 改动幅度过大，此处不展开，需要时请查阅 Popper.js 官方的 v2 迁移指南。

Portal

移除 onRendered prop

同 Modal，onRendered 被移除。可改用子元素上的 callback ref，或在子组件内用 effect hook。

Radio

默认 color prop 更新

radio 的 color prop 默认值现在是 "primary"。继续使用 "secondary" 需显式声明：

-<Radio />
+<Radio color="secondary" />

更新 CSS 类名

不再有 .MuiIconButton-root / .MuiIconButton-label 类名，改而定位 .MuiButtonBase-root：

- <span class="MuiIconButton-root MuiButtonBase-root MuiRadio-root PrivateSwitchBase-root">
-   <span class="MuiIconButton-label">
-     <input class="PrivateSwitchBase-input">
+ <span class="MuiButtonBase-root MuiRadio-root PrivateSwitchBase-root">
+   <span class="PrivateSwitchBase-input">

Rating

✅ 更新 import

组件从 lab 移入 core，现已稳定：

-import Rating from '@mui/lab/Rating';
+import Rating from '@mui/material/Rating';

默认空图标变化

为改善无障碍体验，默认空图标（empty icon）有改动。如果你提供了自定义 icon 但没有 emptyIcon，可通过 emptyIcon={null} 恢复旧行为：

 <Rating
   icon={customIcon}
+  emptyIcon={null}
 />

将 visuallyhidden 改名为 visuallyHidden

  <Rating
    classes={{
-    visuallyhidden: 'custom-visually-hidden-classname',
+    visuallyHidden: 'custom-visually-hidden-classname',
    }}
  />

RootRef

移除该组件

组件已被移除。现在可以直接通过各组件自身的 ref prop 拿到底层 DOM 节点。该组件依赖的 ReactDOM.findDOMNode 在 React.StrictMode 中已被废弃。

:::success 提示 preset-safe codemod 会注入假的 RootRef 组件避免崩溃，但仍需要进一步的修复。 :::

-<RootRef rootRef={ref}>
-  <Button />
-</RootRef>
+<Button ref={ref} />

Select

✅ 更新默认变体

默认变体从 standard 改为 outlined。如果你在用 FormControl 组合 Select，只需更新 FormControl——Select 会从上下文中继承变体：

:::success 提示 该变更由 variant-prop codemod 处理——运行前请先阅读其说明。 :::

-<Select value="Standard" />
-<Select value="Outlined" variant="outlined" />
+<Select value="Standard" variant="standard" />
+<Select value="Outlined" />

移除 labelWidth prop

labelWidth prop 被移除。现在用 label prop 配合 CSS 布局渲染 outlined 变体的缺口（TextField 默认已处理）：

-<Select variant="outlined" labelWidth={20} />
+<Select variant="outlined" label="Gender" />

移除 selectMenu slot

-<Select classes={{ root: 'class1', select: 'class2', selectMenu: 'class3' }} />
+<Select classes={{ select: 'class1 class2 class3' }} />

更新事件类型（TypeScript）

onChange 的 event 类型改为 SelectChangeEvent<T>（而不是 React.ChangeEvent）：

+ import Select, { SelectChangeEvent } from '@mui/material/Select';

-<Select onChange={(event: React.SyntheticEvent, value: unknown) => {}} />
+<Select onChange={(event: SelectChangeEvent<T>, child: React.ReactNode) => {}} />

这是为了避免覆盖触发变更事件的 event.target。

Skeleton

✅ 更新 import

组件从 lab 移入 core，现已稳定：

-import Skeleton from '@mui/lab/Skeleton';
+import Skeleton from '@mui/material/Skeleton';

✅ 重命名 circle 与 rect

circle → circular、rect → rectangular：

-<Skeleton variant="circle" />
-<Skeleton variant="rect" />
-<Skeleton classes={{ circle: 'custom-circle-classname', rect: 'custom-rect-classname',  }} />
+<Skeleton variant="circular" />
+<Skeleton variant="rectangular" />
+<Skeleton classes={{ circular: 'custom-circle-classname', rectangular: 'custom-rect-classname',  }} />

Slider

更新事件类型（TypeScript）

-<Slider onChange={(event: React.SyntheticEvent, value: unknown) => {}} />
+<Slider onChange={(event: Event, value: unknown) => {}} />

将 ValueLabelComponent 与 ThumbComponent 归入 components prop

  <Slider
-  ValueLabelComponent={CustomValueLabel}
-  ThumbComponent={CustomThumb}
+  components={{
+    ValueLabel: CustomValueLabel,
+    Thumb: CustomThumb,
+  }}
  />

CSS 重构

Slider 的 CSS 依据最新 Material Design 规范重做，自定义样式也更直观。v5 中滑块的触控目标面积更大、轨道更粗（可参考 Slider 文档）。若想将密度降低到接近 v4，可使用 size="small" prop。

Snackbar

更新默认定位

通知现在在大屏上默认显示在左下角，更贴近 Gmail、Google Keep、material.io 等产品。恢复 v4 行为：

-<Snackbar />
+<Snackbar anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }} />

✅ 更新过渡动画 props

 <Snackbar
-  onEnter={onEnter}
-  onEntered={onEntered}
-  onEntering={onEntering}
-  onExit={onExit}
-  onExited={onExited}
-  onExiting={onExiting}
+  TransitionProps={{
+    onEnter,
+    onEntered,
+    onEntering,
+    onExit,
+    onExited,
+    onExiting,
+  }}
 >

SpeedDial

✅ 更新 import

-import SpeedDial from '@mui/lab/SpeedDial';
-import SpeedDialAction from '@mui/lab/SpeedDialAction';
-import SpeedDialIcon from '@mui/lab/SpeedDialIcon';
+import SpeedDial from '@mui/material/SpeedDial';
+import SpeedDialAction from '@mui/material/SpeedDialAction';
+import SpeedDialIcon from '@mui/material/SpeedDialIcon';

Stepper

更新组件结构

根元素从 Paper 换成 <div>。Stepper 不再自带 elevation，也不再继承 Paper 的 props。此举是为了鼓励组合式用法：

+<Paper square elevation={2}>
-  <Stepper elevation={2}>
+  <Stepper>
      <Step>
        <StepLabel>Hello world</StepLabel>
      </Step>
    </Stepper>
+<Paper>

移除内建 padding

内建的 24px padding 被移除。如需保留：

-<Stepper>
+<Stepper style={{ padding: 24 }}>
    <Step>
      <StepLabel>Hello world</StepLabel>
    </Step>
  </Stepper>

SvgIcon

移除 fontSize="default"

fontSize 默认值从 default 改为 medium：

-<SvgIcon fontSize="default">
+<SvgIcon>
   <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
 </SvgIcon>

Switch

移除 onChange 的第二个参数

onChange 的第二个参数被废弃，请从 event.target.checked 读取状态：

 function MySwitch() {
-  const handleChange = (event: React.ChangeEvent<HTMLInputElement>, checked: boolean) => {
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const checked = event.target.checked;
   };

   return <Switch onChange={handleChange} />;
 }

更新默认 color prop

color prop 默认值现在是 "primary"：

-<Switch />
+<Switch color="secondary" />

更新 CSS 类名

  <span class="MuiSwitch-root">
-  <span class="MuiIconButton-root MuiButtonBase-root MuiSwitch-switchBase PrivateSwitchBase-root">
-    <span class="MuiIconButton-label">
-      <input class="MuiSwitch-input PrivateSwitchBase-input">
+  <span class="MuiButtonBase-root MuiSwitch-switchBase PrivateSwitchBase-root">
+    <span class="MuiSwitch-input PrivateSwitchBase-input">

Table

重命名默认 padding prop 取值

padding prop 的 default 取值改名为 normal：

-<Table padding="default" />
-<TableCell padding="default" />
+<Table padding="normal" />
+<TableCell padding="normal" />

TablePagination

用 getItemAriaLabel prop 自定义文案

操作按钮（上/下一页）的标签自定义必须通过 getItemAriaLabel prop 完成，这与 Pagination 组件保持一致：

  <TablePagination
-  backIconButtonText="Back"
-  nextIconButtonText="Next"
+  getItemAriaLabel={…}

✅ 重命名 onChangeRowsPerPage 与 onChangePage

  <TablePagination
-  onChangeRowsPerPage={()=>{}}
-  onChangePage={()=>{}}
+  onRowsPerPageChange={()=>{}}
+  onPageChange={()=>{}}

拆分各 label 的类

不同文本标签使用各自独立的类：

  <TablePagination
-  classes={{ caption: 'foo' }}
+  classes={{ selectLabel: 'foo', displayedRows: 'foo' }}
  />

将 input 上的自定义类移到 select

input key 现在作用于另一元素，自定义类应放到 select 上：

  <TablePagination
-  classes={{ input: 'foo' }}
+  classes={{ select: 'foo' }}
  />

Tabs

更新默认 indicatorColor 与 textColor 取值

indicatorColor 与 textColor 的默认值都改为 "primary"。若想保留 v4 配色，分别用 "secondary" 与 "inherit"：

-<Tabs />
+<Tabs indicatorColor="secondary" textColor="inherit" />

更新事件类型（TypeScript）

-<Tabs onChange={(event: React.ChangeEvent<{}>, value: unknown) => {}} />
+<Tabs onChange={(event: React.SyntheticEvent, value: unknown) => {}} />

✅ 新增滚动按钮相关 props

控制滚动按钮的 API 拆成两个 prop：

• scrollButtons：根据可用空间控制滚动按钮何时显示；
• allowScrollButtonsMobile：移除在移动端无条件隐藏滚动按钮的 CSS 媒体查询。

-<Tabs scrollButtons="on" />
-<Tabs scrollButtons="desktop" />
-<Tabs scrollButtons="off" />
+<Tabs scrollButtons allowScrollButtonsMobile />
+<Tabs scrollButtons />
+<Tabs scrollButtons={false} />

Tab

更新默认 minWidth 与 maxWidth

按 Material Design 规范调整默认宽高限制：

• minWidth 从 72px 改为 90px；
• maxWidth 从 264px 改为 360px。

移除 span 与 wrapper

  <button class="MuiTab-root">
-  <span class="MuiTab-wrapper">
      {icon}
      {label}
-  </span>
  </button>

wrapper 类 key 一并删除（相关细节见 PR #26926）。

TextField

✅ 更新默认变体

-<TextField value="Standard" />
-<TextField value="Outlined" variant="outlined" />
+<TextField value="Standard" variant="standard" />
+<TextField value="Outlined" />

:::success 提示 该变更由 variant-prop codemod 处理——运行前请先阅读其说明。 :::

✅ 将 rowsMax 改名为 maxRows

-<TextField rowsMax={6}>
+<TextField maxRows={6}>

✅ 将 rows 改名为 minRows（动态伸缩场景）

-<TextField rows={2} maxRows={5} />
+<TextField minRows={2} maxRows={5} />

自定义 inputComponent 改传 ref

自定义输入组件需改为转发 ref prop，而非 inputRef prop：

-function NumberFormatCustom(props) {
-  const { inputRef, onChange, ...other } = props;
+const NumberFormatCustom = React.forwardRef(function NumberFormatCustom(
+  props,
+  ref,
+) {
  const { onChange, ...other } = props;

  return (
    <NumberFormat
      {...other}
-     getInputRef={inputRef}
+     getInputRef={ref}

重命名 marginDense 与 inputMarginDense 类

对应 prop 由 margin="dense" 改为 size="small"：

-<Input margin="dense" />
+<Input size="small" />

InputAdornment 的 position prop 变为必填语义

position 需设为 start 或 end，分别对应 startAdornment / endAdornment：

-<TextField startAdornment={<InputAdornment>kg</InputAdornment>} />
-<TextField endAdornment={<InputAdornment>kg</InputAdornment>} />
+<TextField startAdornment={<InputAdornment position="start">kg</InputAdornment>} />
+<TextField endAdornment={<InputAdornment position="end">kg</InputAdornment>} />

TextareaAutosize

✅ 用 minRows 取代 rows

-<TextareaAutosize rows={2} />
+<TextareaAutosize minRows={2} />

✅ 将 rowsMax 改名为 maxRows

-<TextareaAutosize rowsMax={6}>
+<TextareaAutosize maxRows={6}>

✅ 将 rowsMin 改名为 minRows

-<TextareaAutosize rowsMin={1}>
+<TextareaAutosize minRows={1}>

ToggleButton

✅ 更新 import

组件从 lab 移入 core，现已稳定：

-import ToggleButton from '@mui/lab/ToggleButton';
-import ToggleButtonGroup from '@mui/lab/ToggleButtonGroup';
+import ToggleButton from '@mui/material/ToggleButton';
+import ToggleButtonGroup from '@mui/material/ToggleButtonGroup';

移除 span 与 label

  <button class="MuiToggleButton-root">
-  <span class="MuiToggleButton-label">
      {children}
-  </span>
  </button>

label 类 key 一并删除（见 PR #27111）。

Tooltip

默认改为可交互（interactive）

Tooltip 现在默认可交互。旧默认行为不满足 WCAG 2.1 的 1.4.3 成功标准（"hoverable"）。为反映新默认值，prop 更名为 disableInteractive。恢复 v4 行为：

-<Tooltip>
+<Tooltip disableInteractive>

可交互 tooltip 不再需要 interactive prop：

-<Tooltip interactive>
+<Tooltip>

Typography

移除 srOnly 变体

改用 visuallyHidden 工具函数配合 sx（或直接作为 style 使用）：

+import { visuallyHidden } from '@mui/utils';

-<Typography variant="srOnly">Create a user</Typography>
+<span style={visuallyHidden}>Create a user</span>

（visuallyHidden 在当前仓库中的实现位于 packages/mui-utils/src/visuallyHidden/visuallyHidden.ts。）

移除 color 与 style 相关覆盖 key

以下类与 style overrides key 被移除："colorInherit"、"colorPrimary"、"colorSecondary"、"colorTextPrimary"、"colorTextSecondary"、"colorError"、"displayInline"、"displayBlock"。这些能力现在归入 MUI System 而非 Typography 本身。若仍需覆盖，可在 styleOverrides 中使用回调：

 const theme = createTheme({
   components: {
     MuiTypography: {
-      styleOverrides: {
-        colorSecondary: {
-          marginTop: '20px',
-        },
-      },
+      styleOverrides: ({ ownerState }) => ({
+        ...ownerState.color === 'secondary' && {
+          marginTop: '20px',
+        },
+      }),
     },
   },
 });

Theme（主题级组件相关变更）

虽然本系列第 1 部分详细覆盖了样式与主题，仍有几项直接影响组件渲染的断点/主题变更被列在组件篇中：

默认背景色

默认背景色现在是浅色模式 #fff、深色模式 #121212，符合 Material Design 规范。

✅ 断点行为变化

断点被当作值而非区间处理。down(key) 的行为变化为：定义的是低于该断点对应值的媒体查询（不含该值），而不是低于"上一个更大的断点"。

因此使用 down() 工具时，断点 key 需要上调一档；使用 between(start, end) 时，end 断点也应上调一档。示例：

-theme.breakpoints.down('sm') // '@media (max-width:959.95px)' - [0, sm + 1) => [0, md)
+theme.breakpoints.down('md') // '@media (max-width:959.95px)' - [0, md)

-theme.breakpoints.between('sm', 'md') // '@media (min-width:600px) and (max-width:1279.95px)' - [sm, md + 1) => [0, lg)
+theme.breakpoints.between('sm', 'lg') // '@media (min-width:600px) and (max-width:1279.95px)' - [0, lg)

-theme.breakpoints.between('sm', 'xl') // '@media (min-width:600px)'
+theme.breakpoints.up('sm') // '@media (min-width:600px)'

使用 Hidden 组件时也要做同样的调整：

-<Hidden smDown>{...}</Hidden> // '@media (min-width:600px)'
+<Hidden mdDown>{...}</Hidden> // '@media (min-width:600px)'

断点尺寸变化

默认断点值改为更贴近常见场景与 Material Design 规范（见当时的相关 issue #21902）：

 {
   xs: 0,
   sm: 600,
-  md: 960,
+  md: 900,
-  lg: 1280,
+  lg: 1200,
-  xl: 1920,
+  xl: 1536,
 }

若倾向旧断点值，可如下配置：

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

const theme = createTheme({
  breakpoints: {
    values: {
      xs: 0,
      sm: 600,
      md: 960,
      lg: 1280,
      xl: 1920,
    },
  },
});

✅ 移除 theme.breakpoints.width 工具

theme.breakpoints.width 因冗余被移除，改用 theme.breakpoints.values：

-theme.breakpoints.width('md')
+theme.breakpoints.values.md

更新 theme.palette.augmentColor 辅助函数签名

-theme.palette.augmentColor(red);
+theme.palette.augmentColor({ color: red, name: 'brand' });

移除 theme.typography.round 辅助函数

因不再使用而被移除。如确需，可用如下等价实现：

function round(value) {
  return Math.round(value * 1e5) / 1e5;
}

@mui/types

重命名导出的 Omit 类型

@mui/types 导出的类型改名为 DistributiveOmit。此命名消除了与 TypeScript 3.5 内置 Omit 工具的混淆——内置 Omit 虽然相似，但不具分配性（non-distributive），作用于联合类型时行为有差异：

-import { Omit } from '@mui/types';
+import { DistributiveOmit } from '@mui/types';

迁移完成后的自我检查清单

完成上述改动后，建议按以下几点做整体自检：

1. 全局搜索旧 import 路径：确保 @mui/lab 下已稳定的组件（Alert、Autocomplete、Pagination、Rating、Skeleton、SpeedDial、ToggleButton 等）全部改为 @mui/material 导入，可参照 packages/mui-material/src 目录确认组件归属；
2. 核对默认值相关的显示回归：Button/Checkbox/Radio/Switch 默认色变为 primary、FormControl/Select/TextField 默认变体变为 outlined、Link 默认下划线变为 always、Tabs 默认指示色变为 primary、Menu/Snackbar 定位变化，这些"无声"变更最容易造成视觉差异；
3. 检查自定义主题的 styleOverrides key：expandIconWrapper、circular/rectangular、focusVisible、sizeSmall 等 key 是否已同步，必要时改用回调形式的 styleOverrides 做基于 ownerState 的条件覆盖；
4. 复查断点相关代码：所有 down()/between() 的 key 是否上调一档，自定义断点值是否要保留 v4 尺寸；
5. 重新运行类型检查：大量 onChange 事件类型从 React.ChangeEvent 收敛为 React.SyntheticEvent（以及 Select 的 SelectChangeEvent<T>），TS 编译器能帮你把漏改的位置全部找出来。

迁移过程中反复强调的 ✅ 项都由 packages/mui-codemod/src/v5.0.0 下的自动化脚本覆盖，先在迁移分支上跑一遍 codemod、再按本文逐项人工核对，是通往 v5 最稳妥的路径。