跳转到内容
编辑此页面

迁移到v5：开始

本指南解释了如何以及为什么要从Material UI v4迁移到v5。

Material UI v5的迁移

  1. 着手进行 👈 你在这里
  2. 突破性变化第一部分：样式和主题
  3. 突破性变化第二部分：组件
  4. 从JSS迁移
  5. 故障排除

简介

这是一个由多部分组成的系列文件中的第一份文件，指导你将你的应用程序从Material UI v4升级到v5。

我们强烈建议运行我们的codemods以提高效率--这些将自动解决v5中引入的许多破坏性变化。

V5最大的变化之一是将JSS替换为Emotion作为默认的样式解决方案。

请注意，你可以继续使用JSS为组件添加重写（例如makeStyles, withStyles），即使在迁移到v5之后。 一旦你完成了v5升级的其余部分，我们建议逐步转移到新的样式引擎上。

这个过程在从JSS迁移中有所涉及。

如果你正在使用Next.js，并且不确定如何配置SSR以与Emotion 和 JSS一起工作，请看这个例子项目

支持的浏览器和Node版本

默认捆绑包在v5中已经改变。

The exact versions will be pinned on release from the browserslist query "> 0.5%, last 2 versions, Firefox ESR, not dead, not IE 11, maintained node versions".

默认捆绑包支持以下最小版本:

  • Node 12 (up from 8)
  • Chrome 90 (up from 49)
  • Edge 91 (up from 14)
  • Firefox 78 (up from 52)
  • Safari 14 (macOS) and 12.5 (iOS) (up from 10)
  • 以及更多（见.browserslistrc（稳定条目））。

Material UI不再支持IE 11。 如果你需要支持IE 11，请查看我们的遗留捆绑包。

更新React和TypeScript版本

React的最低支持版本已经从v16.8.0提高到v17.0.0。

TypeScript的最小支持版本已经从v3.2提高到v3.5。

如果你的项目包括这些软件包，你需要将它们更新到最新版本。

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

设置ThemeProvider

在升级到v5之前，请确保ThemeProvider被定义在你的应用程序的根部和测试中--即使你使用的是默认主题--并且useStyles_没有_在ThemeProvider之前被调用。

最终你可能想从JSS迁移到Emotion，但同时你可以继续使用JSS与@mui/styles包。 这个软件包需要ThemeProvider。

你的应用程序的根看起来应该是这样的:

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>;
}

更新MUI软件包

Material UI v5 and @mui/styles

安装Material UI v5软件包。

With npm:

npm install @mui/material @mui/styles

With yarn:

yarn add @mui/material @mui/styles

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

@material-ui/lab

With npm:

npm install @mui/lab

With yarn:

yarn add @mui/lab

@material-ui/icons

With npm:

npm install @mui/icons-material

With yarn:

yarn add @mui/icons-material

日期和时间选择器

日期和时间选择器组件已被移至MUI X。 如果你正在使用@material-ui/date-pickers或@mui/lab软件包中的挑选器，你将需要迁移到@mui/x-date-pickers。 详见从实验室迁移。

对等依赖关系

接下来，添加Emotion软件包。

With npm:

npm install @emotion/react @emotion/styled

With yarn:

yarn add @emotion/react @emotion/styled

styleled-components (可选)

如果你想使用Material UI v5的样式化组件而不是Emotion，请查看Material UI安装指南。

请注意，如果你的应用程序使用服务器端渲染（SSR），那么Babel插件的样式化组件有一个已知的错误，它使@mui/styled-engine-sc（样式化组件的适配器）无法被使用。

我们强烈建议使用Emotion的默认设置来代替。

Replace all imports

随着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

以下代码模型将自动调整你的大部分代码，以考虑到v5中的突破性变化。

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

preset-safe

This codemod contains most of the transformers that are necessary for migration. 它应该只在每个文件夹中应用一次。

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

variant-prop

如果没有定义变量，这个codemod通过应用variant="standard "来转换<TextField/>、<FormControl/>、和<Select/>组件--默认的变量已经从v4的 "standard "变成了v5的 "outline"。

如果你已经在主题中定义了变量："outlined "作为默认值，你就_不应该_使用这个codemod。

// 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 v5.0.0/link-underline-hover <path>

更多细节，请查看link-underline-hover codemod README。

关于重大变更

codemods处理了许多破坏性的变化，但其他的必须手动处理。

无论你是否选择使用codemods，你现在已经准备好进入两个突破性变化文档中的第一个。