MUI System v7 到 v9 升级完全指南：废弃 system 属性迁入 sx 与 Grid 方向限制的实战落地

MUI System v7 到 v9 升级完全指南废弃 system 属性迁入 sx 与 Grid 方向限制的实战落地【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui输出文章结束标记仅为占位正文见下导读本文以 MUI System v7 升级到 v9 官方迁移文档为骨架系统梳理本次大版本中最影响日常写码的两类破坏性变更从Box、Grid、Stack等组件上移除废弃的 system 快捷属性统一收敛到sx以及Grid不再支持directioncolumn改由Stack承担纵向布局。读完你会拿到可直接执行的 codemod 迁移命令、逐行的改码对照以及本仓库 codemod 源码与Grid类型定义层面的底层证据能够安全地把项目从 v7 迁到 v9。说明本文聚焦 MUI Systemmui/system。如果你的项目同时使用了 Material UI 组件库其 v9 变更覆盖面更广可另见 Material UI v7 到 v9 升级指南。为什么值得升级到 MUI System v9官方文档在 upgrade-to-v9.md 中给出了两个核心理由它们共同指向更少 API 面、更一致行为的设计方向。更一致的样式 APIsystem props 退场sx统一收口v9 从组件上移除了那些已被废弃多年的 system 快捷属性强制把样式表达收敛到sxprop 上。收益是三层API 表面积更小布局类组件不再同时暴露mt、p、display等几十个透传属性行为更一致不同组件之间不再存在有的属性走了样式系统、有的被透传给了 DOM的分裂避免属性冲突这正是文档特别点出的一点——此前像color这类属性可能被组件截胡消费而不是透传给通过componentprop 渲染的底层元素。更清晰的布局原语Grid 管二维Stack 管纵向v9 让Grid回归把二维布局切分为列的本职不再被用作纵向堆叠容器纵向布局统一交给Stack。职责边界越清晰API 就越容易推理也越贴合各自的设计意图。这一方向在仓库中同样有明确呈现见下文 Grid 方向限制。升级前的整体判断与版本配套v9 是一次新的主版本major release必然伴随公开 API 的破坏性变更。进行升级时请注意你需要把mui/system及其配套依赖提升到9.0.0及兼容版本若同仓使用 Material UImui/icons-material、mui/material-nextjs、mui/styled-engine、mui/styled-engine-sc、mui/utils等也需同步到9.0.0mui/lab升级到最新的 v9 beta版本清单见 Material UI v9 升级文档升级前建议先提交干净的基线逐条应用下文变更并跑一遍类型检查tsc与测试便于定位回归。Breaking change 一废弃的 system 属性被移除受影响组件官方文档明确点名了三个组件Box、Grid、Stack。需要说明的是文档示例使用的是mui/system下的这几个组件而仓库中 codemod 的默认组件清单实际覆盖得更广。查看 codemod 源码 removeSystemProps.js 中的components常量处理对象还包括 Material UI 中继承/复用了 system 能力的Typography、Link、Grid2、DialogContentText、TimelineContent、TimelineOppositeContent。也就是说凡是在这些组件上直接写mt、p、color等快捷属性的代码都属于本次清扫范围。推荐的自动化迁移命令文档给出的迁移方式是用官方 codemod 一次性改写命令如下npx mui/codemodlatest v9.0.0/system-props path/to/folder其中path/to/folder替换为你希望递归处理的源码目录例如src/。codemod 的实现在仓库中的位置是 packages/mui-codemod/src/v9.0.0/system-props/removeSystemProps.js。手工迁移的代码对照文档给出了逐组件的最小 diff务必完整核对-Box mt{2} colorprimary.main / Box sx{{ mt: 2, color: primary.main }} / -Grid mt{2} mr{1} / Grid sx{{ mt: 2, mr: 1 }} / -Stack mt{2} alignItemscenter / Stack sx{{ mt: 2, alignItems: center }} /迁移的同时也顺带修复了文档提到的历史问题像color这样的属性此前可能被组件自身消费掉而现在它作为sx内容被正确应用到componentprop 渲染出的底层元素上。深入 codemod它到底改了什么从源码看removeSystemProps的转换策略非常值得理解因为它决定了你 review diff 时该看什么属性白名单来自defaultSxConfig。源码第一行注释写明其属性集合取自 packages/mui-system/src/styleFunctionSx 下的defaultSxConfig.js涵盖 bordersborder、borderRadius、borderColor…、spacingp/px/py、m/mx/my及 margin/padding 全拼、displaydisplay、overflow、whiteSpace…、flexbox、gridgap、gridTemplateColumns…、positionsposition、zIndex…、shadowsboxShadow、sizingwidth、height…、typographyfontSize、fontWeight…等全部可被sx消化的键。JSX 属性搬移 合并。它只把属于白名单、且当前组件受影响的 JSX 属性从元素上剥离并收进新生成的sx对象若元素原本已有sx对象、数组或标识符形式会按类型智能合并已有sx永远保留优先级。处理展开属性spread。当组件存在{...restProps}这类展开时codemod 会追加一个基于restProps.sx的展开合并逻辑配合Array.isArray判断尽可能避免丢失运行期传入的样式。特殊组件有例外规则。对Typography及其派生的DialogContentText、TimelineContent、TimelineOppositeContentcolor只有在取inherit、含.主题色如primary.main、divider、#hex或函数调用时才搬进sx其余取值会被保留在组件 prop 上以免误伤文本默认色逻辑Link类似但colorinherit会被保留因为它在Link上还承担着控制下划线行为的语义。仅处理mui开头的导入来源避免误伤其它库同时跳过.json与.d.ts文件。这些行为都有配套测试锁定见 removeSystemProps.test.js测试覆盖了标准转换、幂等性对转换结果再跑一次应保持输出不变、packageName选项支持把 codemod 用于内部封装的acme/ui这类自定义包以及jsx选项显式声明自动引入、无法通过 import 识别来源的组件名如Box,Typography,Stack,Link或任意自定义名。对使用该 codemod 的实践启示推荐先对目录跑一次随后用git diff逐块核对尤其留意Typography/Link的color是否被正确处理若你的代码把组件从自定义封装里再导出、import 分析识别不到可通过--jsx类选项补充组件名详见 packages/mui-codemod/README.md 对 v9.0.0/system-props 的说明codemod 是幂等的可以在 review 后放心重跑同一目录而不必担心二次污染。Breaking change 二Grid 不再支持directioncolumn变更说明Grid组件不再接受directioncolumn与directioncolumn-reverse。文档给出的理由是Grid的定位是把布局切分为列columns的二维网格而不是做纵向堆叠纵向布局应当使用Stack。这一点在源码中有双重印证类型层面GridProps.ts 中GridDirection已被收窄为type GridDirection row | row-reverse组件注释层面Grid.tsx 与GridProps.ts的 JSDoc 均明确写着只有row和row-reverse被支持column/column-reverse不受支持因为Grid是被设计来把布局细分为列而非行的。Material UI 侧的 v9 文档补充了一个重要背景这两个取值在此前版本中实际上就并未被真正支持本次只是把它们从 TypeScript 类型与 prop 校验中正式剔除。如果你仍需要横向的列细分请继续使用默认的directionrow或directionrow-reverse。迁移示例纵向布局改用 Stack文档给出了完整的前后对照-import Grid from mui/system/Grid; import Stack from mui/system/Stack; -Grid container directioncolumn spacing{2} - GridFirst item/Grid - GridSecond item/Grid -/Grid Stack spacing{2} divFirst item/div divSecond item/div /Stack要点拆解Grid container directioncolumn spacing{2}整体替换为一个Stack spacing{2}——spacing语义在Stack上原样保留原先每个Grid子项即逻辑上的一行替换为普通元素文档用div如果子项内部还需要做水平细分可以继续在子项内嵌套Grid即外层 Stack 负责纵向、内层 Grid 负责横向的组合Material UI 侧文档称之为inside a Grid item when needed若你是从mui/system之外的入口如mui/material/Grid导入同样适用——纵向堆叠交给Stack对应入口为mui/material/Stack。一份可对照执行的升级清单把上述两类变更落到项目里推荐按如下顺序操作锁版本在package.json中把mui/system及配套依赖提升到 v9 兼容版本重新安装依赖。跑 codemod 清扫 system 属性npx mui/codemodlatest v9.0.0/system-props src/若还使用了Typography、Link等派生组件确认它们也在处理范围内自定义封装场景参考 README 补充选项。处理 Grid 方向全局搜索directioncolumn含column-reverse逐个按上文 diff 改写为Stack必要时在Stack子项里保留Grid做水平列细分。检查颜色与透传重点 review 原先依赖color等属性被组件消费的写法确认迁移后样式经sx落到了component指定的元素上。验证运行类型检查与组件测试。由于 codemod 输出可预测且幂等git diff应该清晰可审本仓库的 codemod 测试幂等、自定义包名、jsx 组件名等用例可作为你验收改写的参考口径。参考与进一步阅读本文依据的官方指南docs/data/system/migration/upgrade-to-v9/upgrade-to-v9.md上一代升级文档v6 → v7含早期 deprecated 属性背景docs/data/system/migration/upgrade-to-v7/upgrade-to-v7.mdcodemod 源码与测试removeSystemProps.js、removeSystemProps.test.js历史版本v6.0.0对应的 system-props codemodpackages/mui-codemod/src/v6.0.0/system-props/removeSystemProps.js可用于对比两代迁移逻辑差异Grid 类型与实现GridProps.ts、Grid.tsx、createGrid.tsxMaterial UI 组件库侧对应的 v9 升级范围docs/data/material/migration/upgrade-to-v9/upgrade-to-v9.md【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考