# 从 v3 迁移到 v4 版本

是的，我们已经发布了 v4 版本！

您还在找 v3 版本的文档吗？ [您可以在这里找到它们](https://material-ui.com/versions/) 。 > 此文档尚未完成。 您是否已经升级了站点并且遇到了一些并没有在此涉及的问题？ [请在 GitHub 添加您的更改](https://github.com/mui-org/material-ui/blob/master/docs/src/pages/guides/migration-v3/migration-v3.md)。 ## 简介 当您将站点从 Material-UI 的 v3 版本升级到 v4 版本时，此篇会给您提供一些参考。 您可能不会将这里所有涵盖的内容运用到你的站点上。 我们会尽我们最大的努力让文档简单易懂，并尽可能有序地介绍，这样您可以迅速对 v4 版本游刃有余。 ## 为什么您需要迁移呢 此文档介绍了*如何*从 v3 版本迁移到 v4 版本。 关于迁移的*原因*，我们则在 [Medium上发布了一篇博客](https://medium.com/material-ui/material-ui-v4-is-out-4b7587d1e701)来详细解说。 ## 更新您的依赖包 您需要做的第一件事，就是更新您的依赖包。 ### 升级 Material-UI 的版本 若想要使用最新版本的 Material-UI，您必须更新 `package.json`。 ```json "dependencies": { "@material-ui/core": "^4.0.0" } ``` 或者运行 ```sh npm install @material-ui/core 或者 yarn add @material-ui/core ``` ### 更新 React 的版本 对于 React 版本的最低要求是从 `react@^16.3.0` 升级到 `react@^16.8.0`。 这样一来我们能够依赖 [Hooks](https://reactjs.org/docs/hooks-intro.html) 的功能（我们已经不再使用 class API）。 ### 更新 Material-UI Styles 的版本 若您以前使用 v3 版本的 `@material-ui/styles`，您则需要更新 `package.json`，这样才能使用最新版本的 Material-UI Styles。 ```json "dependencies": { "@material-ui/styles": "^4.0.0" } ``` 或者运行 ```sh npm install @material-ui/styles 或者 yarn add @material-ui/styles ``` ## 处理变化带来的系统崩溃 ### Core - 每个组件会提供他们的 ref。 这是通过使用 `React.forwardRef()` 实现的。 这回影响到内部的组件树和显示的名称，进而会使得 shallow 或者 snapshot 测试崩溃。 `innerRef` 不再返回一个实例的 ref（或者当内部组件是一个函数组件时，什么都不返回），而是返回一个它根组件的 ref。 我们已经将相应的 API 文档在根组件中列出。 ### Styles（样式表单） - ⚠️ Material-UI 依赖于 JSS 的 v10 版本。 JSS v10 版本与 v9 版本不向后兼容。 请保证您的开发环境中未安装 JSS v9 版本。 （在您的 `package.json` 中删除 `react-jss` 会有所帮助）。 StylesProvider 组件替代了 JssProvider 组件。 - 请移除 `withTheme()` 中的第一个可选的参数。 （第一个参数是为从未出现的可能的未来选项的一个占位符。） 它与 [emotion 的 API](https://emotion.sh/docs/introduction) 以及 [styled-components 的 API ](https://www.styled-components.com) 相匹配。 ```diff -const DeepChild = withTheme()(DeepChildRaw); +const DeepChild = withTheme(DeepChildRaw); ``` - 将 `convertHexToRGB` 重命名为 `hexToRgb`。 ```diff -import { convertHexToRgb } from '@material-ui/core/styles/colorManipulator'; +import { hexToRgb } from '@material-ui/core/styles'; ``` - 限制其范围 [keyframes API] (https://cssinjs.org/jss-syntax/#keyframes-animation)。 您应该在您的代码中做出以下改变。 这对分离动画的逻辑有所帮助： ```diff rippleVisible: { opacity: 0.3, - animation: 'mui-ripple-enter 100ms cubic-bezier(0.4, 0, 0.2, 1)', + animation: '$mui-ripple-enter 100ms cubic-bezier(0.4, 0, 0.2, 1)', }, '@keyframes mui-ripple-enter': { '0%': { opacity: 0.1, }, '100%': { opacity: 0.3, }, }, ``` 若想要正确地使用它，您必须使用其返回值。 ```diff -const background = { main: color }; -theme.palette.augmentColor(background); +const background = theme.palette.augmentColor({ main: color }); console.log({ background }); ``` —您可以从主题创建中安全地移除下一个变体： ```diff typography: { - useNextVariants: true, }, ``` —我们已经不再使用`theme.spacing.unit`，请参照新的 API： 您可以在项目中使用 [迁移小帮手](https://github.com/mui-org/material-ui/tree/master/packages/material-ui-codemod/README.md#theme-spacing-api) 来让您的迁移流程更加顺畅。 ### Layout（布局） - [Grid] 本着支持任意间距值，并且摈弃心理上一直需要在 8 的基础上作计数的目的，我们改变了 spacing 的 API: ```diff /** * 在类别为 `item` 的组件之间定义间距。 * 它只能用于类型为 `container` 的组件。 */ - spacing: PropTypes.oneOf([0, 8, 16, 24, 32, 40]), + spacing: PropTypes.oneOf([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]), ``` 从今往后，您可以使用主题来实现 [一个自定义的网格间距变换函数](https://material-ui.com/system/spacing/#transformation)。 - [Container] 从 `@material-ui/lab` 迁移到 `@material-ui/core`。 ```diff -import Container from '@material-ui/lab/Container'; +import Container from '@material-ui/core/Container'; ``` ### TypeScript #### `value` 类型 将 input 组件的 `value` 属性的类型正常化，这样可以使用 `unknown`了。 这会影响 `InputBase`，`NativeSelect`，`OutlinedInput`，`Radio`，`RadioGroup`，`Select`，`SelectInput`，`TextArea` 和 `TextField`。 ```diff function MySelect({ children }) { - const handleChange = (event: any, value: string) => { + const handleChange = (event: any, value: unknown) => { // handle value }; return } ``` 我们在 [TypeScript 指南中](/guides/typescript/#handling-value-and-event-handlers)更详细地解释了此变更。 ### Buttons（按钮） - [Button] 删除不推荐使用的按钮变体（flat，raised 和 fab）： ```diff -