尧图网站建设 `、主题覆盖与全局 CSS)
Material UI 样式定制指南按层级选择sx、styled()、主题覆盖与全局 CSS【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-uiMaterial UI本仓库为 mui/material-ui为开发者提供了从「一次性微调」到「全局基线」的四层样式定制策略。本文以仓库内置的 skills/material-ui-styling/AGENTS.md 为骨架结合 How to customize、Themed components、The sx prop、styled() 等官方文档与对应可运行 Demo 源码系统梳理每一种策略的适用场景、API 细节、状态类与槽位slot命名规则。读完你将能够快速判断一个改动该落在哪一层并写出既符合设计体系、又避免样式「泄漏」到全局的 Material UI 代码。版本提示本指南对应的 Material UI 版本为 v99.0.0 10.0.0。若你使用其他主版本请以实际仓库与所安装包的 API 为准。1. 概览四种策略按作用域从小到大选择Material UI 的样式定制策略可以按作用域从窄到宽排成一条决策链一次性定制 / 局部布局→ 使用sxprop同一套覆盖在多处复用→ 用styled()包裹 MUI 组件或做一个薄封装组件某个组件所有实例的默认外观都要改变→ 使用theme.componentsstyleOverrides、variants、defaultProps原生 HTML 元素基线例如所有h1或与单个组件无关的全局样式→ 使用GlobalStyles或CssBaseline覆盖两条反向的告诫同样重要不要为了一个一次性页面就跳到全局主题覆盖反过来如果是一个被大规模重复使用的系统样式也不要只用sx到处粘贴——此时具名变体或styled()封装更清晰、更易维护。这也是 AGENTS.md 中强调「选择能解决问题的最小作用域以避免全局规则被四处打散」的原因。2. 一次性定制sxprop2.1 使用场景与能力当只需要修改单个实例或很小的内联场景且能访问到主题时首选sx。仓库中的基础示例 SxProp.js 展示了它的典型形态import Slider from mui/material/Slider; export default function SxProp() { return Slider defaultValue{30} sx{{ width: 300, color: success.main }} /; }color: success.main这类值并不是合法 CSS它是sx提供的主题感知属性color会解析为theme.palette.success.main路径width: 300会变成300px。MUI System 把所有样式函数打包进了sx这个「CSS 超集」里因此你既能写任意标准 CSS也能用主题快捷值。官方 The sx prop 中罗列了以下典型映射边框border: 1等价于border: 1px solid blackborderColor: primary.main等价于取theme.palette.primary.mainborderRadius: 2表示2 * theme.shape.borderRadius默认每个单位4px。间距margin/padding及其长写属性会把数值乘以theme.spacing默认每个单位8px并支持大量别名——m、mt、mr、mb、ml、mx、my、p、pt、pr、pb、pl、px、py。调色板color、bgcolorbackgroundColor别名接受主题调色板路径字符串。网格gap、rowGap、columnGap的数值会乘以theme.spacing。定位 / 阴影zIndex: tooltip映射到theme.zIndex.tooltipboxShadow: 1映射到theme.shadows[1]。字号排版fontWeight: fontWeightLight或省略前缀的light映射到theme.typographytypography: body1会展开theme.typography.body1的全部值。尺寸width: 1/2会转换为50%值在(0, 1]之间时按百分比处理width: 20则输出20px。此外sx还支持伪选择器、嵌套选择器、响应式对象断点与容器查询、回调与数组值。2.2 数组语法条件合并的正确姿势当需要根据条件叠加样式时用数组形式代替对象展开spreadBox sx{[ { :hover: { color: red, backgroundColor: white, }, }, foo { :hover: { backgroundColor: grey }, }, bar { :hover: { backgroundColor: yellow }, }, ]} /规则是数组按顺序应用falsy 条目会被跳过同一属性上索引越大优先级越高——因此上例中即使foo为真只要bar为真backgroundColor就是yellow。每个索引既可以是一个样式对象也可以是一个接收theme的回调sx{[ { mr: 2, color: red }, (theme) ({ :hover: { color: theme.palette.primary.main, }, }), ]}注意回调应作为整个sx值使用sx{(theme) ({...})}属性值位置的回调形式已废弃。TypeScript 下把样式对象单独声明时需要as const以避免字面量类型被拓宽为string导致类型不匹配。2.3 覆盖组件内部槽位slots要修改组件的某个内部子结构可以在sx里用全局类名片段定位槽位例如把Slider的滑块 thumb 改成方形import Slider from mui/material/Slider; export default function DevTools() { return ( Slider defaultValue{30} sx{{ width: 300, color: success.main, .MuiSlider-thumb: { borderRadius: 1px, }, }} / ); }完整 Demo 见 DevTools.js。这里的思路是先在浏览器 DevTools 里找到目标槽位的类名。Material UI 注入的类名遵循固定模式[hash]-Mui[组件名]-[槽位名]例如.css-ae2u5c-MuiSlider-thumb——但 hash 部分不稳定绝不能拿来写选择器只能依赖稳定的Mui[Component]-[slot]片段如.MuiSlider-thumb。该命名规范与更完整的槽位说明参见 reference.md。2.4 状态类state classes与特异性hover、focus、disabled、selected这类状态在 Material UI 里用高特异性样式表达。能使用原生伪类的状态如:disabled优先使用伪类但像selected这类 Web 规范中不存在对应伪类的状态Material UI 提供了状态类全局类名其特异性与 CSS 伪类相当。覆盖它们时必须提高特异性永远不要把状态类当裸全局选择器使用/* ❌ 错误会污染所有使用 .Mui-error 的组件 */ .Mui-error { color: red; } /* ✅ 正确限定到 OutlinedInput 的根元素上 */ .MuiOutlinedInput-root.Mui-error { color: red; }对完整状态类清单与规则见 How to customize 的 State classes 小节及下方的状态类速查表。2.5className接入外部 CSS / CSS Modules当需要与外部样式库或 CSS Modules 协作时使用组件自带的classNameprop并按同样的「槽位 状态类」规则组合选择器例如classNameButton配合.Button:disabled提权。各样式库的完整接入方式见仓库的 interoperability 相关示例。3. 可复用styled()3.1 何时使用当同一个自定义组件要出现在多个位置、且值得拥有一个具名组件时把styled()作为首选import { styled } from mui/material/styles;使用 Material UI 时应优先从mui/material/styles导入这样在应用没有通过ThemeProvider提供主题时会用与其余应用一致的默认主题兜底而mui/system版本的styled使用另一套默认主题。仓库中的可运行对照例子是 StyledCustomization.jsimport Slider from mui/material/Slider; import { alpha, styled } from mui/material/styles; const SuccessSlider styled(Slider)(({ theme }) ({ width: 300, color: theme.palette.success.main, .MuiSlider-thumb: { :hover, .Mui-focusVisible: { boxShadow: 0px 0px 0px 8px ${alpha(theme.palette.success.main, 0.16)}, }, .Mui-active: { boxShadow: 0px 0px 0px 14px ${alpha(theme.palette.success.main, 0.16)}, }, }, })); export default function StyledCustomization() { return SuccessSlider defaultValue{30} /; }相比底层样式库Emotion / styled-components的styled()Material UI 版本额外提供了四个能力见 styled() 文档无主题上下文时使用默认主题支持通过options.name关联theme.components[name]下的styleOverrides与variants生成的组件自带sxprop可用options.skipSx关闭默认内置shouldForwardProp处理避免把ownerState、theme、sx、as等透传到 DOM。3.2 options 参数速览styled(Component, options)(styles)中可用的关键 optionsshouldForwardProp(prop: string) bool决定某个 prop 是否继续传递给底层组件nametheme.components下用于查找styleOverrides/variants的键同时也用于生成调试用 labelslot通常为Root为Root时自动应用主题里该组件的variantsoverridesResolver自定义如何根据 props 解析theme.components[name].styleOverridesskipVariantsResolver设为true可关闭对theme.components[name].variants的自动解析skipSx设为true可关闭结果组件上的sx支持。3.3 自定义 props 与动态样式为自定义组件新增 props 时务必使用shouldForwardProp把非 DOM 属性拦下来避免 React 把无效属性渲染到 DOM 上TypeScript 侧则通过继承组件 props 类型并做接口扩展。仓库 DynamicCSS.js 演示了标准写法const StyledSlider styled(Slider, { shouldForwardProp: (prop) prop ! success, })(({ theme }) ({ width: 300, variants: [ { props: ({ success }) success, style: { color: theme.palette.success.main, .MuiSlider-thumb: { :hover, .Mui-focusVisible: { boxShadow: 0px 0px 0px 8px ${alpha(theme.palette.success.main, 0.16)}, }, .Mui-active: { boxShadow: 0px 0px 0px 14px ${alpha(theme.palette.success.main, 0.16)}, }, }, }, }, ], }));动态样式的两条实现路径建议首选 CSS 变量或样式回调中的条件样式对象把「按 props 分支」收敛在一个顶层函数里可读性最好不要在样式对象内部给每个字段单独写(props) ...形式的函数。需要随高频变化值如颜色选择器实时预览改样式时优先用内联 CSS 变量而不是每帧传入新对象避免不断向 DOM 插入无谓的style标签而引发性能问题参见 The sx prop—Dynamic values。4. 全站一致createTheme({ components })4.1 何时使用当希望Button、TextField等组件默认外观在全应用范围内统一变化时使用主题的components键。它的三个子键分工明确defaultProps改默认 props、styleOverrides改槽位样式、variants按 props 映射附加样式。完整的组件键与槽位名需要查阅对应组件的 Customization 文档小节键名与组件内部名一致如MuiButton、MuiTextField。关键告诫主题是不可 tree-shaking 的见 theme-components.md。如果某个定制很重却只用在一两处新建一个组件通常比把主题越撑越大更好。4.2defaultProps修改默认 propsconst theme createTheme({ components: { // 组件名 MuiButtonBase: { defaultProps: { // 要修改默认值的 props disableRipple: true, // 全应用关闭涟漪效果 }, }, }, });4.3styleOverrides按槽位覆盖样式styleOverrides以槽位名为键root表示最外层元素值为 CSS-in-JS 样式对象也支持嵌套选择器const theme createTheme({ components: { MuiButton: { styleOverrides: { // 槽位名 root: { // CSS 属性 fontSize: 1rem, }, }, }, }, });当需要依据组件已解析的 propsownerState或主题值分支时可把某槽位值写成回调形式例如root: ({ ownerState, theme }) ({ ... })。需要注意仓库内 Themed components 文档指出以回调访问槽位ownerState的形式已被标记为废弃deprecated官方建议改用variants表达按 props 分支的样式const theme createTheme({ components: { MuiButton: { styleOverrides: { - root: ({ ownerState, theme }) ({ ... }), root: { variants: [...], }, }, }, }, });4.4variants把 props 映射成样式variants定义在具体槽位下是{ props, style }对象构成的数组。当组件 props 与props匹配时应用style需要优先的样式要放在数组后面。针对既有 props 增加样式例如加粗outlined类型的 Card 边框const theme createTheme({ components: { MuiCard: { styleOverrides: { root: { variants: [ { props: { variant: outlined }, style: { borderWidth: 3px, }, }, ], }, }, }, }, });为 Button 增加全新变体dashed取值名可自定义const theme createTheme({ components: { MuiButton: { styleOverrides: { root: { variants: [ { props: { variant: dashed }, style: { textTransform: none, border: 2px dashed ${blue[500]}, }, }, ], }, }, }, }, });也可以同时匹配既有与新增 props甚至把props写成回调来处理「属性不等于某值」这类条件例如variant dashed color ! secondary。若在 TypeScript 中使用新增变体需要通过[模块增强]声明ButtonPropsVariantOverridesdeclare module mui/material/Button { interface ButtonPropsVariantOverrides { dashed: true; } }仓库还用类型测试锁定了这一用法见packages/mui-material/test/typescript/augmentation/下的组件主题相关 spec。4.5 在主题里使用sx语法实验性sx在组件上自 v5 起就是稳定特性但在主题对象内部直接使用仍属实验性。若你已经在用sx可以用同样的语法快速迁移样式到主题const finalTheme createTheme({ components: { MuiChip: { styleOverrides: { root: ({ theme }) theme.unstable_sx({ px: 1, py: 0.25, borderRadius: 1, }), label: { padding: initial, }, icon: ({ theme }) theme.unstable_sx({ mr: 0.5, ml: -2px, }), }, }, }, });由于sx的 CSS 特异性高于主题覆盖即便在主题中用了这套语法仍可继续在组件上通过sx覆盖它。5. 全局 CSSGlobalStyles与CssBaseline5.1 何时使用当要样式化原生 HTML 元素例如所有h1或编写不绑定到某个 MUI 组件实例的全应用级代码片段时使用。5.2GlobalStyles基本用法import * as React from react; import GlobalStyles from mui/material/GlobalStyles; export default function GlobalCssOverride() { return ( React.Fragment GlobalStyles styles{{ h1: { color: grey } }} / h1Grey h1 element/h1 /React.Fragment ); }完整示例见 GlobalCssOverride.js。当需要访问主题时把styles写成回调即可GlobalStyles styles{(theme) ({ h1: { color: theme.palette.primary.main }, })} /见 GlobalCssOverrideTheme.js。性能建议把GlobalStyles /提升为模块级常量再复用避免每次渲染都重新计算style标签、造成重复的样式计算import * as React from react; import GlobalStyles from mui/material/GlobalStyles; const inputGlobalStyles GlobalStyles styles{...} /; function Input(props) { return ( React.Fragment - GlobalStyles styles{...} / {inputGlobalStyles} input {...props} / /React.Fragment ); }5.3 通过MuiCssBaseline扩展全局基线CssBaseline用于为应用提供统一的 HTML 基线去除 body 默认 margin、应用theme.palette.background.default背景、全局border-box、滚动条与color-scheme等详见 CSS Baseline。如果你已经在用CssBaseline与其再叠加一个GlobalStyles不如直接扩展MuiCssBaseline的styleOverridesimport CssBaseline from mui/material/CssBaseline; import { ThemeProvider, createTheme } from mui/material/styles; const theme createTheme({ components: { MuiCssBaseline: { styleOverrides: h1 { color: grey; } , }, }, }); export default function OverrideCssBaseline() { return ( ThemeProvider theme{theme} CssBaseline / h1Grey h1 element/h1 /ThemeProvider ); }MuiCssBaseline的styleOverrides同样支持回调形式以访问主题参考 OverrideCssBaseline.js 及配套的 callback 示例。若只是渐进式迁移某块局部区域而不想全局重置可以考虑ScopedCssBaseline把基线限定在其子节点内。6.sxvsstyled()Agent 与开发者都应知道的差异两者经常被混淆Material UI 官方文档与 AGENTS.md 都专门列出一张差异对照表主题sxstyled()样式对象主题间距简写m、p、gap等✅ 支持❌ 不支持。需在回调中用theme.spacing()或写普通 CSS 值数字 padding如1的含义主题间距单位theme.spacing(1)像素1px不是theme.spacing(1)主题调色板字符串如primary.main✅ 支持需在回调中使用theme取值由此可总结出三条最容易踩的「坑」styled(button)({ mx: 1 })是错误用法——mx这类系统布局简写只在sx中可用styled()的样式对象是纯 CSS必须写margin-left: theme.spacing(1)。styled(button)({ padding: 1 })中的1代表1px而sx{{ padding: 1 }}中的1代表theme.spacing(1)。语义完全不同。想在styled()里复用一套sx逻辑时可借助主题的unstable_sx写法参考上文 4.5 节细节见 styled()—Difference with the sx prop。7. 导入与一致性约定为了让代码整洁且利于打包仓库内的 AGENTS.md 给出了两条应用层约定优先使用包的一级导入例如mui/material/Button避免通过桶文件barrel把整个mui/material拉进产物系统布局简写p、gap、mt等用sx表达行为相关的、由组件文档定义的 props 用组件 props 表达——不要把布局语义塞进variant之类的行为性 props 里。示例 Demo 基本都遵循这一约定例如 SxProp.js 从mui/material/Slider单路径导入组件而样式靠sx完成。8. 附录状态类与类名速查以下状态类与命名规范在 AGENTS.md 的配套文件 reference.md 以及 How to customize 中均有完整记载使用时务必与组件或限定作用域的选择器组合绝不单独出现。8.1 全局状态类状态全局类名active.Mui-activechecked.Mui-checkedcompleted.Mui-completeddisabled.Mui-disablederror.Mui-errorexpanded.Mui-expandedfocus visible.Mui-focusVisiblefocused.Mui-focusedreadOnly.Mui-readOnlyrequired.Mui-requiredselected.Mui-selected8.2 槽位类名模式注入的类名遵循[hash]-Mui[组件名]-[槽位名]。写选择器时只用稳定片段Mui[组件名]-[槽位名]如.MuiSlider-thumb禁止使用含 hash 的完整类名因为 hash 不稳定。8.3 主题组件键通过createTheme({ components: { MuiButton: { ... } } })覆盖组件。键名与组件内部名一致例如MuiButton、MuiTextField具体槽位名和可用的主题键请查阅对应组件文档的 Customization 小节。9. 进一步阅读主题仓库内文档策略总览与决策How to customizesx参考The sx propstyled()APIstyled()组件级主题Themed componentsCSS 基线CSS Baseline状态 / 类名速查reference.md在动手前可以再核对一遍 AGENTS.md 中的决策清单先问「是单实例还是局部布局」→ 用sx再问「同一覆盖是否多处复用」→ 用styled()接着问「是否所有实例默认外观都要变」→ 用theme.components最后才考虑「是否是原生元素基线或非组件全局 CSS」→ 用GlobalStyles/CssBaseline。按此顺序从最小作用域开始你就能始终把定制放在最合适、最不易产生副作用的那一层。【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Material UI 样式定制指南：按层级选择 `sx`、`styled()`、主题覆盖与全局 CSS
Material UI 样式定制指南按层级选择sx、styled()、主题覆盖与全局 CSS【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-uiMaterial UI本仓库为 mui/material-ui为开发者提供了从「一次性微调」到「全局基线」的四层样式定制策略。本文以仓库内置的 skills/material-ui-styling/AGENTS.md 为骨架结合 How to customize、Themed components、The sx prop、styled() 等官方文档与对应可运行 Demo 源码系统梳理每一种策略的适用场景、API 细节、状态类与槽位slot命名规则。读完你将能够快速判断一个改动该落在哪一层并写出既符合设计体系、又避免样式「泄漏」到全局的 Material UI 代码。版本提示本指南对应的 Material UI 版本为 v99.0.0 10.0.0。若你使用其他主版本请以实际仓库与所安装包的 API 为准。1. 概览四种策略按作用域从小到大选择Material UI 的样式定制策略可以按作用域从窄到宽排成一条决策链一次性定制 / 局部布局→ 使用sxprop同一套覆盖在多处复用→ 用styled()包裹 MUI 组件或做一个薄封装组件某个组件所有实例的默认外观都要改变→ 使用theme.componentsstyleOverrides、variants、defaultProps原生 HTML 元素基线例如所有h1或与单个组件无关的全局样式→ 使用GlobalStyles或CssBaseline覆盖两条反向的告诫同样重要不要为了一个一次性页面就跳到全局主题覆盖反过来如果是一个被大规模重复使用的系统样式也不要只用sx到处粘贴——此时具名变体或styled()封装更清晰、更易维护。这也是 AGENTS.md 中强调「选择能解决问题的最小作用域以避免全局规则被四处打散」的原因。2. 一次性定制sxprop2.1 使用场景与能力当只需要修改单个实例或很小的内联场景且能访问到主题时首选sx。仓库中的基础示例 SxProp.js 展示了它的典型形态import Slider from mui/material/Slider; export default function SxProp() { return Slider defaultValue{30} sx{{ width: 300, color: success.main }} /; }color: success.main这类值并不是合法 CSS它是sx提供的主题感知属性color会解析为theme.palette.success.main路径width: 300会变成300px。MUI System 把所有样式函数打包进了sx这个「CSS 超集」里因此你既能写任意标准 CSS也能用主题快捷值。官方 The sx prop 中罗列了以下典型映射边框border: 1等价于border: 1px solid blackborderColor: primary.main等价于取theme.palette.primary.mainborderRadius: 2表示2 * theme.shape.borderRadius默认每个单位4px。间距margin/padding及其长写属性会把数值乘以theme.spacing默认每个单位8px并支持大量别名——m、mt、mr、mb、ml、mx、my、p、pt、pr、pb、pl、px、py。调色板color、bgcolorbackgroundColor别名接受主题调色板路径字符串。网格gap、rowGap、columnGap的数值会乘以theme.spacing。定位 / 阴影zIndex: tooltip映射到theme.zIndex.tooltipboxShadow: 1映射到theme.shadows[1]。字号排版fontWeight: fontWeightLight或省略前缀的light映射到theme.typographytypography: body1会展开theme.typography.body1的全部值。尺寸width: 1/2会转换为50%值在(0, 1]之间时按百分比处理width: 20则输出20px。此外sx还支持伪选择器、嵌套选择器、响应式对象断点与容器查询、回调与数组值。2.2 数组语法条件合并的正确姿势当需要根据条件叠加样式时用数组形式代替对象展开spreadBox sx{[ { :hover: { color: red, backgroundColor: white, }, }, foo { :hover: { backgroundColor: grey }, }, bar { :hover: { backgroundColor: yellow }, }, ]} /规则是数组按顺序应用falsy 条目会被跳过同一属性上索引越大优先级越高——因此上例中即使foo为真只要bar为真backgroundColor就是yellow。每个索引既可以是一个样式对象也可以是一个接收theme的回调sx{[ { mr: 2, color: red }, (theme) ({ :hover: { color: theme.palette.primary.main, }, }), ]}注意回调应作为整个sx值使用sx{(theme) ({...})}属性值位置的回调形式已废弃。TypeScript 下把样式对象单独声明时需要as const以避免字面量类型被拓宽为string导致类型不匹配。2.3 覆盖组件内部槽位slots要修改组件的某个内部子结构可以在sx里用全局类名片段定位槽位例如把Slider的滑块 thumb 改成方形import Slider from mui/material/Slider; export default function DevTools() { return ( Slider defaultValue{30} sx{{ width: 300, color: success.main, .MuiSlider-thumb: { borderRadius: 1px, }, }} / ); }完整 Demo 见 DevTools.js。这里的思路是先在浏览器 DevTools 里找到目标槽位的类名。Material UI 注入的类名遵循固定模式[hash]-Mui[组件名]-[槽位名]例如.css-ae2u5c-MuiSlider-thumb——但 hash 部分不稳定绝不能拿来写选择器只能依赖稳定的Mui[Component]-[slot]片段如.MuiSlider-thumb。该命名规范与更完整的槽位说明参见 reference.md。2.4 状态类state classes与特异性hover、focus、disabled、selected这类状态在 Material UI 里用高特异性样式表达。能使用原生伪类的状态如:disabled优先使用伪类但像selected这类 Web 规范中不存在对应伪类的状态Material UI 提供了状态类全局类名其特异性与 CSS 伪类相当。覆盖它们时必须提高特异性永远不要把状态类当裸全局选择器使用/* ❌ 错误会污染所有使用 .Mui-error 的组件 */ .Mui-error { color: red; } /* ✅ 正确限定到 OutlinedInput 的根元素上 */ .MuiOutlinedInput-root.Mui-error { color: red; }对完整状态类清单与规则见 How to customize 的 State classes 小节及下方的状态类速查表。2.5className接入外部 CSS / CSS Modules当需要与外部样式库或 CSS Modules 协作时使用组件自带的classNameprop并按同样的「槽位 状态类」规则组合选择器例如classNameButton配合.Button:disabled提权。各样式库的完整接入方式见仓库的 interoperability 相关示例。3. 可复用styled()3.1 何时使用当同一个自定义组件要出现在多个位置、且值得拥有一个具名组件时把styled()作为首选import { styled } from mui/material/styles;使用 Material UI 时应优先从mui/material/styles导入这样在应用没有通过ThemeProvider提供主题时会用与其余应用一致的默认主题兜底而mui/system版本的styled使用另一套默认主题。仓库中的可运行对照例子是 StyledCustomization.jsimport Slider from mui/material/Slider; import { alpha, styled } from mui/material/styles; const SuccessSlider styled(Slider)(({ theme }) ({ width: 300, color: theme.palette.success.main, .MuiSlider-thumb: { :hover, .Mui-focusVisible: { boxShadow: 0px 0px 0px 8px ${alpha(theme.palette.success.main, 0.16)}, }, .Mui-active: { boxShadow: 0px 0px 0px 14px ${alpha(theme.palette.success.main, 0.16)}, }, }, })); export default function StyledCustomization() { return SuccessSlider defaultValue{30} /; }相比底层样式库Emotion / styled-components的styled()Material UI 版本额外提供了四个能力见 styled() 文档无主题上下文时使用默认主题支持通过options.name关联theme.components[name]下的styleOverrides与variants生成的组件自带sxprop可用options.skipSx关闭默认内置shouldForwardProp处理避免把ownerState、theme、sx、as等透传到 DOM。3.2 options 参数速览styled(Component, options)(styles)中可用的关键 optionsshouldForwardProp(prop: string) bool决定某个 prop 是否继续传递给底层组件nametheme.components下用于查找styleOverrides/variants的键同时也用于生成调试用 labelslot通常为Root为Root时自动应用主题里该组件的variantsoverridesResolver自定义如何根据 props 解析theme.components[name].styleOverridesskipVariantsResolver设为true可关闭对theme.components[name].variants的自动解析skipSx设为true可关闭结果组件上的sx支持。3.3 自定义 props 与动态样式为自定义组件新增 props 时务必使用shouldForwardProp把非 DOM 属性拦下来避免 React 把无效属性渲染到 DOM 上TypeScript 侧则通过继承组件 props 类型并做接口扩展。仓库 DynamicCSS.js 演示了标准写法const StyledSlider styled(Slider, { shouldForwardProp: (prop) prop ! success, })(({ theme }) ({ width: 300, variants: [ { props: ({ success }) success, style: { color: theme.palette.success.main, .MuiSlider-thumb: { :hover, .Mui-focusVisible: { boxShadow: 0px 0px 0px 8px ${alpha(theme.palette.success.main, 0.16)}, }, .Mui-active: { boxShadow: 0px 0px 0px 14px ${alpha(theme.palette.success.main, 0.16)}, }, }, }, }, ], }));动态样式的两条实现路径建议首选 CSS 变量或样式回调中的条件样式对象把「按 props 分支」收敛在一个顶层函数里可读性最好不要在样式对象内部给每个字段单独写(props) ...形式的函数。需要随高频变化值如颜色选择器实时预览改样式时优先用内联 CSS 变量而不是每帧传入新对象避免不断向 DOM 插入无谓的style标签而引发性能问题参见 The sx prop—Dynamic values。4. 全站一致createTheme({ components })4.1 何时使用当希望Button、TextField等组件默认外观在全应用范围内统一变化时使用主题的components键。它的三个子键分工明确defaultProps改默认 props、styleOverrides改槽位样式、variants按 props 映射附加样式。完整的组件键与槽位名需要查阅对应组件的 Customization 文档小节键名与组件内部名一致如MuiButton、MuiTextField。关键告诫主题是不可 tree-shaking 的见 theme-components.md。如果某个定制很重却只用在一两处新建一个组件通常比把主题越撑越大更好。4.2defaultProps修改默认 propsconst theme createTheme({ components: { // 组件名 MuiButtonBase: { defaultProps: { // 要修改默认值的 props disableRipple: true, // 全应用关闭涟漪效果 }, }, }, });4.3styleOverrides按槽位覆盖样式styleOverrides以槽位名为键root表示最外层元素值为 CSS-in-JS 样式对象也支持嵌套选择器const theme createTheme({ components: { MuiButton: { styleOverrides: { // 槽位名 root: { // CSS 属性 fontSize: 1rem, }, }, }, }, });当需要依据组件已解析的 propsownerState或主题值分支时可把某槽位值写成回调形式例如root: ({ ownerState, theme }) ({ ... })。需要注意仓库内 Themed components 文档指出以回调访问槽位ownerState的形式已被标记为废弃deprecated官方建议改用variants表达按 props 分支的样式const theme createTheme({ components: { MuiButton: { styleOverrides: { - root: ({ ownerState, theme }) ({ ... }), root: { variants: [...], }, }, }, }, });4.4variants把 props 映射成样式variants定义在具体槽位下是{ props, style }对象构成的数组。当组件 props 与props匹配时应用style需要优先的样式要放在数组后面。针对既有 props 增加样式例如加粗outlined类型的 Card 边框const theme createTheme({ components: { MuiCard: { styleOverrides: { root: { variants: [ { props: { variant: outlined }, style: { borderWidth: 3px, }, }, ], }, }, }, }, });为 Button 增加全新变体dashed取值名可自定义const theme createTheme({ components: { MuiButton: { styleOverrides: { root: { variants: [ { props: { variant: dashed }, style: { textTransform: none, border: 2px dashed ${blue[500]}, }, }, ], }, }, }, }, });也可以同时匹配既有与新增 props甚至把props写成回调来处理「属性不等于某值」这类条件例如variant dashed color ! secondary。若在 TypeScript 中使用新增变体需要通过[模块增强]声明ButtonPropsVariantOverridesdeclare module mui/material/Button { interface ButtonPropsVariantOverrides { dashed: true; } }仓库还用类型测试锁定了这一用法见packages/mui-material/test/typescript/augmentation/下的组件主题相关 spec。4.5 在主题里使用sx语法实验性sx在组件上自 v5 起就是稳定特性但在主题对象内部直接使用仍属实验性。若你已经在用sx可以用同样的语法快速迁移样式到主题const finalTheme createTheme({ components: { MuiChip: { styleOverrides: { root: ({ theme }) theme.unstable_sx({ px: 1, py: 0.25, borderRadius: 1, }), label: { padding: initial, }, icon: ({ theme }) theme.unstable_sx({ mr: 0.5, ml: -2px, }), }, }, }, });由于sx的 CSS 特异性高于主题覆盖即便在主题中用了这套语法仍可继续在组件上通过sx覆盖它。5. 全局 CSSGlobalStyles与CssBaseline5.1 何时使用当要样式化原生 HTML 元素例如所有h1或编写不绑定到某个 MUI 组件实例的全应用级代码片段时使用。5.2GlobalStyles基本用法import * as React from react; import GlobalStyles from mui/material/GlobalStyles; export default function GlobalCssOverride() { return ( React.Fragment GlobalStyles styles{{ h1: { color: grey } }} / h1Grey h1 element/h1 /React.Fragment ); }完整示例见 GlobalCssOverride.js。当需要访问主题时把styles写成回调即可GlobalStyles styles{(theme) ({ h1: { color: theme.palette.primary.main }, })} /见 GlobalCssOverrideTheme.js。性能建议把GlobalStyles /提升为模块级常量再复用避免每次渲染都重新计算style标签、造成重复的样式计算import * as React from react; import GlobalStyles from mui/material/GlobalStyles; const inputGlobalStyles GlobalStyles styles{...} /; function Input(props) { return ( React.Fragment - GlobalStyles styles{...} / {inputGlobalStyles} input {...props} / /React.Fragment ); }5.3 通过MuiCssBaseline扩展全局基线CssBaseline用于为应用提供统一的 HTML 基线去除 body 默认 margin、应用theme.palette.background.default背景、全局border-box、滚动条与color-scheme等详见 CSS Baseline。如果你已经在用CssBaseline与其再叠加一个GlobalStyles不如直接扩展MuiCssBaseline的styleOverridesimport CssBaseline from mui/material/CssBaseline; import { ThemeProvider, createTheme } from mui/material/styles; const theme createTheme({ components: { MuiCssBaseline: { styleOverrides: h1 { color: grey; } , }, }, }); export default function OverrideCssBaseline() { return ( ThemeProvider theme{theme} CssBaseline / h1Grey h1 element/h1 /ThemeProvider ); }MuiCssBaseline的styleOverrides同样支持回调形式以访问主题参考 OverrideCssBaseline.js 及配套的 callback 示例。若只是渐进式迁移某块局部区域而不想全局重置可以考虑ScopedCssBaseline把基线限定在其子节点内。6.sxvsstyled()Agent 与开发者都应知道的差异两者经常被混淆Material UI 官方文档与 AGENTS.md 都专门列出一张差异对照表主题sxstyled()样式对象主题间距简写m、p、gap等✅ 支持❌ 不支持。需在回调中用theme.spacing()或写普通 CSS 值数字 padding如1的含义主题间距单位theme.spacing(1)像素1px不是theme.spacing(1)主题调色板字符串如primary.main✅ 支持需在回调中使用theme取值由此可总结出三条最容易踩的「坑」styled(button)({ mx: 1 })是错误用法——mx这类系统布局简写只在sx中可用styled()的样式对象是纯 CSS必须写margin-left: theme.spacing(1)。styled(button)({ padding: 1 })中的1代表1px而sx{{ padding: 1 }}中的1代表theme.spacing(1)。语义完全不同。想在styled()里复用一套sx逻辑时可借助主题的unstable_sx写法参考上文 4.5 节细节见 styled()—Difference with the sx prop。7. 导入与一致性约定为了让代码整洁且利于打包仓库内的 AGENTS.md 给出了两条应用层约定优先使用包的一级导入例如mui/material/Button避免通过桶文件barrel把整个mui/material拉进产物系统布局简写p、gap、mt等用sx表达行为相关的、由组件文档定义的 props 用组件 props 表达——不要把布局语义塞进variant之类的行为性 props 里。示例 Demo 基本都遵循这一约定例如 SxProp.js 从mui/material/Slider单路径导入组件而样式靠sx完成。8. 附录状态类与类名速查以下状态类与命名规范在 AGENTS.md 的配套文件 reference.md 以及 How to customize 中均有完整记载使用时务必与组件或限定作用域的选择器组合绝不单独出现。8.1 全局状态类状态全局类名active.Mui-activechecked.Mui-checkedcompleted.Mui-completeddisabled.Mui-disablederror.Mui-errorexpanded.Mui-expandedfocus visible.Mui-focusVisiblefocused.Mui-focusedreadOnly.Mui-readOnlyrequired.Mui-requiredselected.Mui-selected8.2 槽位类名模式注入的类名遵循[hash]-Mui[组件名]-[槽位名]。写选择器时只用稳定片段Mui[组件名]-[槽位名]如.MuiSlider-thumb禁止使用含 hash 的完整类名因为 hash 不稳定。8.3 主题组件键通过createTheme({ components: { MuiButton: { ... } } })覆盖组件。键名与组件内部名一致例如MuiButton、MuiTextField具体槽位名和可用的主题键请查阅对应组件文档的 Customization 小节。9. 进一步阅读主题仓库内文档策略总览与决策How to customizesx参考The sx propstyled()APIstyled()组件级主题Themed componentsCSS 基线CSS Baseline状态 / 类名速查reference.md在动手前可以再核对一遍 AGENTS.md 中的决策清单先问「是单实例还是局部布局」→ 用sx再问「同一覆盖是否多处复用」→ 用styled()接着问「是否所有实例默认外观都要变」→ 用theme.components最后才考虑「是否是原生元素基线或非组件全局 CSS」→ 用GlobalStyles/CssBaseline。按此顺序从最小作用域开始你就能始终把定制放在最合适、最不易产生副作用的那一层。【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考