跳到内容
🚀 影响 Material UI 2025 年路线图！参与最新的开发者调查
+

升级到 v6

本指南解释了为何以及如何从 Material UI v5 升级到 v6。

为何您应该升级到 Material UI v6

React Server Component 支持

Material UI v6 引入了 Pigment CSS，这是一种零运行时 CSS-in-JS 样式引擎，旨在取代 Emotion 和 styled-components，成为在 React 19 及更高版本中编写样式的更具前瞻性的解决方案。借助 Pigment CSS，样式在构建时而不是运行时提取，避免了客户端重新计算，并解锁了 React Server Component (RSC) 兼容性。这也显著减小了 Material UI 应用的捆绑包大小。

在 v6 中，Pigment CSS 是可选的。 Material UI 未来的主要版本可能会使用 Pigment CSS 作为默认样式解决方案。尽管是可选的，但仍鼓励在您的 Material UI 应用中试用 Pigment CSS。如果您希望这样做，请在完成升级到 Material UI v6 后，参考迁移到 Pigment CSS指南。

生活质量改进

Material UI v6 具有其他几项生活质量改进，包括

  • ThemeProvider 现在支持 CssVarsProvider 的所有功能
  • 支持容器查询
  • 一个新的主题实用程序，用于向特定颜色模式添加样式

如果您正在使用任何这些软件包，您也可以将其版本更改为 "6.0.0"

  • @mui/icons-material
  • @mui/system
  • @mui/lab
  • @mui/material-nextjs
  • @mui/styled-engine-sc
  • @mui/utils

请注意，MUI X 软件包不遵循与 Material UI 相同的版本控制策略。如果您正在使用以下任何软件包，则在升级过程中应保持不变

  • @mui/x-data-grid
  • @mui/x-data-grid-pro
  • @mui/x-data-grid-premium
  • @mui/x-date-pickers
  • @mui/x-date-pickers-pro
  • @mui/x-charts
  • @mui/x-tree-view
  • @mui/x-tree-view-pro

支持的浏览器和版本

v6 中默认捆绑包目标已更改。

确切的版本将在从 browserslist 查询发布的版本上固定："> 0.5%, last 2 versions, Firefox ESR, not dead, safari >= 15.4, iOS >= 15.4"。

  • Node.js 14（从 12 升级）
  • Chrome 109（从 90 升级）
  • Edge 121（从 91 升级）
  • Firefox 115（从 78 升级）
  • macOS 和 iOS 中的 Safari 15.4（从 macOS 中的 14 和 iOS 中的 12.5 升级）
  • 以及更多（请参阅 .browserslistrc stable 条目）

移除对 IE 11 的支持

v6 中已完全移除对 IE 11 的支持——旧版捆绑包和所有与 IE 11 相关的代码。这减小了 Material UI 的捆绑包大小，并简化了未来的开发。

如果您需要支持 IE 11，可以使用 v5 的旧版捆绑包。请注意，它在未来不会收到更新或错误修复。

最低 React 版本

React 的最低支持版本为 v17.0.0（与 v5 相同）。使用以下代码片段更新您的项目（将 <version> 替换为您想要的版本）

npm install react@<version> react-dom@<version>

最低 TypeScript 版本

TypeScript 的最低支持版本已从 v3.5 提高到 4.7。

如果您的项目包含这些软件包，您需要更新它们

  • @types/react
  • @types/react-dom

重大更改

Material UI v6 旨在在从 v5 升级时引入最少的重大更改。这些包括浏览器支持更新、Node.js 版本升级以及移除 UMD 捆绑包。这些更新使 Material UI 包大小减少了 2.5MB，几乎占 v5 中总大小的 25%。

提供了 Codemod 来处理大多数这些重大更改。

UMD 捆绑包已移除

为了与 React 19 移除 UMD 构建保持一致，Material UI 也移除了其 UMD 捆绑包。这导致 @mui/material 包大小减少了 2.5MB，占总包大小的 25%。有关更多详细信息，请参阅 Package Phobia。

相反，我们建议使用基于 ESM 的 CDN，例如 esm.sh。有关替代安装方法，请参阅CDN 文档。

Accordion（手风琴）

摘要包裹在标题中

为了符合 W3C Accordion Pattern 标准，Accordion Summary 现在默认使用 <h3> 标题元素包裹。此更改可能会影响依赖于先前 DOM 结构和 CSS 特异性的自定义项。此外，默认标题元素可能会与页面上现有的标题结构冲突。

如果您的样式或 DOM 操作依赖于旧结构，您将需要更新它们以适应新的标题元素。如果默认标题元素与您现有的结构冲突，您可以使用 slotProps.heading.component 属性更改标题元素。

<Accordion slotProps={{ heading: { component: 'h4' } }}>
  <AccordionSummary
    expandIcon={<ExpandMoreIcon />}
    aria-controls="panel1-content"
    id="panel1-header"
  >
    Accordion
  </AccordionSummary>
  <AccordionDetails>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse malesuada
    lacus ex, sit amet blandit leo lobortis eget.
  </AccordionDetails>
</Accordion>

摘要作为按钮（从 v6.3.0 开始）

  • Accordion Summary HTML 结构已更新，以修复因使用上面显示的标题包裹而引入的无效 HTML
    • 根元素现在是 button。
    • 摘要内容和图标包装器呈现为 span。
  • 在 AccordionSummary 中使用先前的 div 元素进行样式的开发人员应更新其样式。此外，那些使用 Typography 进行文本（默认渲染 p 标签）的人员应将其替换为 span。您可以使用 component 属性替换 HTML 标签（<Typography component="span" />），如Accordion 演示中所示。

Autocomplete（自动完成）

在 Autocomplete 组件的 onInputChange 回调中的 reason 参数中引入了三个新值。这些值为先前由 "reset" 涵盖的三个特定用例提供了更精细的选项

  • "blur"：类似于 "reset"，但在焦点从输入移开时触发。clearOnBlur 必须为 true。
  • "selectOption"：在选择选项后输入值更改时触发。
  • "removeOption"：在多选模式下，当芯片因其对应的选项被选中而被移除时触发。

除了现有的 "input"、"reset" 和 "clear" 值之外，这些值也可用。

Chip（纸片）

在早期版本中，当用户按下 esc 键时，Chip 组件会失去焦点，这与其他类似按钮的组件的工作方式不同。在 v6 中，Chip 现在按预期保留焦点。

要保留以前的行为，请添加自定义 onKeyUp 处理程序，如下所示

import * as React from 'react';
import Chip from '@mui/material/Chip';

export default function ChipExample() {
  const chipRef = React.useRef(null);
  const keyUpHandler = (event) => {
    if (event.key === 'Escape' && chipRef.current) {
      chipRef.current.blur();
    }
  };
  return (
    <Chip
      label="Chip Outlined"
      variant="outlined"
      ref={chipRef}
      onKeyUp={keyUpHandler}
    />
  );
}

Divider（分隔符）

当使用垂直方向时，Divider 现在渲染一个带有相应可访问性属性的 <div> 而不是 <hr>，以遵守 WAI-ARIA 规范。如果您在 CSS 中定位 hr 标签，您可能需要相应地调整您的样式。

-import Divider from '@mui/material/Divider';
+import Divider, { dividerClasses } from '@mui/material/Divider';

 const Main = styled.main({
-  '& hr': {
+  [`& .${dividerClasses.root}`]: {
     marginTop: '16px',
   },
 });

Grid2

Grid2（以前的 Unstable_Grid2）已更新并稳定

  • 以前的大小（xs、sm、md、...）和偏移量（xsOffset、smOffset、mdOffset、...）属性，它们以主题的断点命名，已被 size 和 offset 属性替换。
  • 间距机制已重新设计为使用 gap CSS 属性。

这带来了一些重大更改，将在以下部分中描述。

移除了 Unstable 前缀

Grid2 组件 API 已稳定，因此其导入不再包含 Unstable_ 前缀

-import { Unstable_Grid2 as Grid2 } from '@mui/material';
+import { Grid2 } from '@mui/material';

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

大小和偏移量属性已重命名

在 v5 中，大小和偏移量属性被命名为与主题的断点相对应。对于默认主题，这些是

  • 大小：xs、sm、md、lg、xl
  • 偏移量：xsOffset、smOffset、mdOffset、lgOffset、xlOffset

在 v6 中，这些属性被重命名为 size 和 offset

 <Grid
-  xs={12}
-  sm={6}
-  xsOffset={2}
-  smOffset={3}
+  size={{ xs: 12, sm: 6 }}
+  offset={{ xs: 2, sm: 3 }}
 >

如果所有断点的大小或偏移量都相同，则可以使用单个值

-<Grid xs={6} xsOffset={2}>
+<Grid size={6} offset={2}>

此外，size 属性的 true 值已重命名为 "grow"

-<Grid xs>
+<Grid size="grow">

使用此 codemod 将您的项目迁移到新的 size 和 offset 属性

npx @mui/codemod@latest v6.0.0/grid-v2-props <path/to/folder>
使用自定义断点

上面描述的用法也适用于自定义断点

-<Grid mobile={12} mobileOffset={2} desktop={6} desktopOffset={4}>
+<Grid size={{ mobile: 12, desktop: 6 }} offset={{ mobile: 2, desktop: 4 }}>

您可以通过提供断点作为参数，将相同的 codemod 用于自定义断点

npx @mui/codemod@latest v6.0.0/grid-v2-props <path/to/folder> --jscodeshift='--muiBreakpoints=mobile,desktop'

移除了 disableEqualOverflow 属性

在 v5 中，Grid 会溢出其父元素。在 v6 中，Grid 正确地包含在其父元素的内边距内

Before and after of the Grid no longer overflowing its parent in v6.

这消除了对 disableEqualOverflow 属性的需求

-<Grid disableEqualOverflow>
+<Grid>

Grid item 间距更改

在 v5 中，Grid item 在其框中包含间距。在 v6 中，Grid item 不再在其框中包含间距，而是使用 CSS gap 属性。

请注意，item 位置不会更改。

Before and after of the Grid items no longer including spacing in their boxes.

ListItem（列表项）

ListItem 的属性 autoFocus、button、disabled 和 selected 在 v5 中已弃用，现已移除。要替换 button 属性，请改用 ListItemButton。其他移除的属性在 ListItemButton 组件中也可用。

-<ListItem button />
+<ListItemButton />

使用此 codemod 将您的项目迁移到 ListItemButton 组件

npx @mui/codemod@latest v6.0.0/list-item-button-prop <path/to/folder>

由于 ListItem 不再支持这些属性，因此移除了与这些属性相关的类名。您应该改用 listItemButtonClasses 对象。

-import { listItemClasses } from '@mui/material/ListItem';
+import { listItemButtonClasses } from '@mui/material/ListItemButton';

-listItemClasses.button
+listItemButtonClasses.root

-listItemClasses.focusVisible
+listItemButtonClasses.focusVisible

-listItemClasses.disabled
+listItemButtonClasses.disabled

-listItemClasses.selected
+listItemButtonClasses.selected

Button with Loading State（带加载状态的按钮）

从 @mui/material v6.4.0 开始，Lab 中的 LoadingButton 已移除。加载功能现在是标准 Button 组件的一部分。按如下方式更新您的导入

-import { LoadingButton } from '@mui/lab';
+import { Button } from '@mui/material';

-import LoadingButton from '@mui/lab/LoadingButton';
+import Button from '@mui/material/Button';

有关更多详细信息，请参阅 Loading 部分，位于 Material UI Button 文档中。

Typography（排版）

Typography 组件中的 color 属性不再是系统属性。您可以改用 sx 属性

-<Typography color={(theme) => theme.palette.primary.main}>
+<Typography sx={{ color: (theme) => theme.palette.primary.main }}>

您仍然可以使用 color 属性直接访问某些主题颜色。请查看Typography 组件 API 页面以获取完整的颜色列表。

<Typography color="textSecondary">Secondary text</Typography>

useMediaQuery 类型

以下已弃用的类型在 v6 中已移除

  • MuiMediaQueryList：请改用 MediaQueryList（来自 lib.dom.d.ts）。
  • MuiMediaQueryListEvent：请改用 MediaQueryListEvent（来自 lib.dom.d.ts）。
  • MuiMediaQueryListListener：请改用 (event: MediaQueryListEvent) => void。

影响测试的重大更改

Ripple effect（涟漪效果）

v6 中改进了涟漪效果的性能。因此，您可能需要更新涉及具有涟漪效果的组件的测试。如果您正在使用 @testing-library/react 中的 fireEvent 来模拟用户交互，您将需要在 act 和 await 中包装这些交互，以避免 React 警告

- fireEvent.click(button);
+ await act(async () => fireEvent.mouseDown(button));

受此更改影响的组件包括

  • 所有按钮
  • Checkbox（复选框）
  • Chip（纸片）
  • Radio Group（单选按钮组）
  • Switch（开关）
  • Tabs（选项卡）

影响类型的重大更改

Box（盒子）

component 属性已从 BoxOwnProps 中移除，因为它已包含在 Box 类型中。如果您将 styled 函数与 Box 组件一起使用，这可能会影响您的代码。如果是这种情况，请使用 div 元素而不是 Box

-const StyledBox = styled(Box)`
+const StyledDiv = styled('div')`
   color: white;
 `;

这将产生相同的最终结果。如果这对您不起作用，您也可以将 styled 返回的值强制转换为 typeof Box

 const StyledBox = styled(Box)`
   color: white;
-`;
+` as typeof Box;

稳定的 API

CssVarsProvider 和 extendTheme

CssVarsProvider 和 extendTheme API 现在已稳定。如果您已经在 v5 中使用它们，您现在可以删除实验性前缀

-import { experimental_extendTheme as extendTheme, Experimental_CssVarsProvider as CssVarsProvider } from '@mui/material/styles';
+import { extendTheme, CssVarsProvider } from '@mui/material/styles';

有关使用这些 API 的更多详细信息，请参阅CSS 主题变量。

颜色模式主题实用程序

Material UI v6 引入了一个新的实用程序，用于向特定颜色模式添加样式，称为 theme.applyStyles()，旨在替换在应用浅色或深色样式时的 theme.palette.mode

 const MyComponent = styled('button')(({ theme }) => ({
   padding: '0.5rem 1rem',
   border: '1px solid,
-  borderColor: theme.palette.mode === 'dark' ? '#fff' : '#000',
+  borderColor: '#000',
+  ...theme.applyStyles('dark', {
+    borderColor: '#fff',
+  })
 }))

使用这些 codemod 将您的项目迁移到 theme.applyStyles()

npx @mui/codemod@latest v6.0.0/styled <path/to/folder-or-file>
npx @mui/codemod@latest v6.0.0/sx-prop <path/to/folder-or-file>
npx @mui/codemod@latest v6.0.0/theme-v6 <path/to/theme-file>

弃用

为了使用 Material UI v6，无需立即处理弃用项。

您可以按照自己的节奏进行处理，方法是查看弃用页面。这些弃用项将在下一个主要版本中移除。

Pigment CSS 集成（可选）

完成将您的应用升级到 v6 后，您就可以开始迁移到 Pigment CSS，以获得 RSC 支持和更小的捆绑包大小。