迁移到 v5：入门指南

import { ThemeProvider, createMuiTheme, makeStyles } from '@material-ui/core/styles';

const theme = createMuiTheme();

const useStyles = makeStyles((theme) => {
  root: {
    // some CSS that accesses the theme
  }
});

function App() {
  const classes = useStyles(); // ❌ If you have this, consider moving it
  // inside of a component wrapped with <ThemeProvider />
  return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
}

更新 Material UI 包

Material UI v5 和 `@mui/styles`

安装 Material UI v5 包。

如果您正在使用 @material-ui/lab 或 @material-ui/icons，您将需要安装新的包。

`@material-ui/lab`

`@material-ui/icons`

日期和时间选择器

日期和时间选择器组件已移至 MUI X。如果您正在使用 @material-ui/date-pickers 或 @mui/lab 包中的选择器，您将需要迁移到 @mui/x-date-pickers。有关详细信息，请参阅从 lab 迁移。

对等依赖

接下来，添加 Emotion 包。

styled-components（可选）

如果您想将 Material UI v5 与 styled-components 而不是 Emotion 一起使用，请查看Material UI 安装指南。

请注意，如果您的应用程序使用服务器端渲染 (SSR)，则 styled-components 的 Babel 插件存在一个已知错误，该错误会阻止使用 @mui/styled-engine-sc（styled-components 的适配器）。

我们强烈建议使用默认设置 Emotion。

替换所有导入

随着 v5 的发布，所有相关包的名称都从 @material-ui/* 更改为 @mui/*，这是我们更新品牌的一部分。有关详细信息，请参阅这篇博客文章。

更新的包名称

@material-ui/core -> @mui/material
@material-ui/unstyled -> @mui/base
@material-ui/icons -> @mui/icons-material
@material-ui/styles -> @mui/styles
@material-ui/system -> @mui/system
@material-ui/lab -> @mui/lab
@material-ui/types -> @mui/types
@material-ui/styled-engine -> @mui/styled-engine
@material-ui/styled-engine-sc ->@mui/styled-engine-sc
@material-ui/private-theming -> @mui/private-theming
@material-ui/codemod -> @mui/codemod
@material-ui/docs -> @mui/docs
@material-ui/envinfo -> @mui/envinfo

移除旧包

一旦您安装了所有必要的包并确保您的应用程序仍然运行，您就可以通过运行 npm uninstall @material-ui/* 或 yarn remove @material-ui/* 安全地移除旧的 @material-ui/* 包。

修复 CSS 特异性（可选）

如果您想通过导入 CSS 文件将样式应用于组件，则需要提高特异性才能定位正确的组件。

考虑以下示例

import './style.css';
import Chip from '@mui/material/Chip';

const ChipWithGreenIcon = () => (
  <Chip
    classes={{ deleteIcon: 'green' }}
    label="delete icon is green"
    onDelete={() => {}}
  />
);

在此示例中，为了正确地将特定样式应用于 Chip 的删除图标，一种选择是提高 CSS 类的特异性，如下所示

.MuiChip-root .green {
  color: green;
}

相比之下，以下 CSS 代码段不会将样式应用于删除图标

.green {
  color: green;
}

运行 codemods

以下 codemods 将自动调整您的大部分代码，以解决 v5 中的重大更改。

在运行每个 codemod 后，确保您的应用程序仍然运行无误，并在继续下一步之前提交更改。

preset-safe

此 codemod 包含迁移所需的大多数转换器。它应该每个文件夹仅应用一次。

npx @mui/codemod@latest v5.0.0/preset-safe <path>

variant-prop

如果未定义 variant，此 codemod 通过应用 variant="standard" 来转换 <TextField/>、<FormControl/> 和 <Select/> 组件——默认 variant 已从 v4 中的 "standard" 更改为 v5 中的 "outlined"。

// ❌ if you have a theme setup like this, don't run this codemod.
// these default props can be removed later because `outlined` is the default value in v5
createMuiTheme({
  components: {
    MuiTextField: {
      defaultProps: {
        variant: 'outlined',
      },
    },
  },
});

如果您想在组件中保留 variant="standard"，请运行此 codemod，否则配置相应的默认主题 props。

npx @mui/codemod@latest v5.0.0/variant-prop <path>

有关更多详细信息，请查看 variant-prop codemod README。

link-underline-hover

如果未定义 underline prop，此 codemod 通过应用 underline="hover" 来转换 <Link /> 组件——默认 underline 已从 v4 中的 "hover" 更改为 v5 中的 "always"。

// if you have theme setup like this, ❌ don't run this codemod.
// this default props can be removed later because `always` is the default value in v5
createMuiTheme({
  components: {
    MuiLink: {
      defaultProps: {
        underline: 'always',
      },
    },
  },
});

如果您想保留 underline="hover"，请运行此 codemod，否则配置相应的默认主题 props。

npx @mui/codemod@latest v5.0.0/link-underline-hover <path>

有关更多详细信息，请查看 link-underline-hover codemod README。

解决重大更改

codemods 处理了许多重大更改，但其他更改必须手动解决。

无论您是否选择使用 codemods，您现在都可以继续阅读两篇重大更改文档的第一篇。