Material UI v9 主题与设计令牌实战指南从 createTheme 到 CSS 变量与 Windows 高对比模式【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui适用版本说明本文所述 API 面向 Material UI v9版本范围9.0.0 10.0.0。该技能指南以 AGENTS.md 为纲技术细节扎根于仓库docs/data/material/customization/theming、palette、dark-mode、css-theme-variables、typography、spacing、shape与packages/mui-material/src/styles/下的源码实现。若你正在使用其他大版本请先核对本文 API 细节再行套用。Material UI 的主题机制本质上是一份设计令牌对象palette、typography、spacing、shape、breakpoints、zIndex、transitions 等再加上可选的按组件默认值theme.components。要建立一套可切换明暗、可配合服务端渲染、甚至能适配 Windows 高对比模式的统一视觉体系你需要掌握createTheme/ThemeProvider的基础用法、colorSchemes与cssVariables的取舍以及自定义品牌令牌时对应的 TypeScript 类型增强方法。读完本文你将能够在 Material UI v9 项目中独立搭建并扩展一套生产级主题并理解其背后的源码原理。一、主题的核心心智模型一份对象 一次注入 三处读取先用一句话概括 Material UI 主题化的工作方式一个 theme 就是一个包含设计令牌design tokens和可选组件级默认值的 JavaScript 对象应用通常在启动阶段调用一次createTheme或分步组合把结果通过靠近根节点的ThemeProvider注入 React context组件再通过useTheme、sx或styled读取令牌值。以createTheme为分水岭可以把它拆成三层来理解令牌层palette、typography、spacing、shape、breakpoints、zIndex、transitions它们描述设计上应该长什么样行为层theme.components按Mui*组件键注入defaultProps、styleOverrides、variants让某个组件在全局范围内有一致的默认外观注入层ThemeProvider把 theme 对象放进 React context任何子孙组件都能拿到。这套模型的源码起点位于 createTheme.ts从源码结构看当cssVariables未开启默认false时它内部走createThemeNoVars路径其注释明确写着Behaves exactly as v5而当开启 CSS 变量或colorSchemes时则会进入带 vars 的处理管线。这与下文CSS 变量是可选项的说法一致——不使用 CSS 变量时你的主题行为完全等价于经典的 v5 语义。二、核心起步createTheme ThemeProvider CssBaseline基础三段式代码如下import { createTheme, ThemeProvider } from mui/material/styles; const theme createTheme({ palette: { primary: { main: #1976d2 }, }, }); function App() { return ( ThemeProvider theme{theme} {/* 应用内容 */} /ThemeProvider ); }要点说明主题构建入口统一从mui/material/styles导入createTheme产出 Material UI 默认主题语义。用createTheme({ ... })构建主题对象后用ThemeProvider theme{theme}包裹应用使所有后代组件都能通过 context 拿到主题。在 Provider 内部放置CssBaseline /以获得基准元素样式与正确的暗色背景行为细节见 Dark mode。组件内读取主题的官方入口同样是mui/material/styles下的useTheme()import { useTheme } from mui/material/styles; function MyComponent() { const theme useTheme(); return div style{{ color: theme.palette.primary.main }} /; }除useTheme之外更推荐的方式是通过sx或styled的插值函数取令牌例如sx{{ color: primary.main }}与styled(div)(({ theme }) ({ color: theme.palette.primary.main }))——它们会自动把语义色名解析为主题值。三、设计令牌全景图Design Token Map下表来自该指南的核心表格罗列了令牌存放的各个区域及其角色区域作用参考文档palette语义色primary、secondary、error…、文字、背景、分割线、action 色docs/data/material/customization/palette/typographyfontFamily、fontSize、字体变体h1~body2、button…docs/data/material/customization/typography/spacingtheme.spacing(n)间距标尺默认每单位 8pxdocs/data/material/customization/spacing/shapeborderRadius默认 4新增额外圆角需做 TypeScript 类型增强docs/data/material/customization/shape/breakpoints供sx/ 媒体查询使用的响应式键docs/data/material/customization/breakpoints/zIndex层级令牌docs/data/material/customization/z-index/transitions时长 / 缓动函数辅助docs/data/material/customization/transitions/components按Mui*键配置defaultProps、styleOverrides、variantsdocs/data/material/customization/theme-components/完整的默认值明细可参考仓库中docs/data/material/customization/default-theme/下的默认主题文档Default theme explorer它逐项列出每个令牌在生产主题里的默认值适合作为调试这个值为什么是这个颜色的对照表。从源码结构看令牌在生产主题中并非全部原样暴露例如 createTheme.ts 会通过createMixins、createTypography、createPalette等工厂函数把简写输入如只给palette.primary.main展开成包含light/dark/contrastText等派生字段的完整结构这也是只给main也能跑的底层原因。四、Palette 速查三个高频事实使用 palette 时应记住以下三点每个 palette 颜色通常包含main、light、dark、contrastText四个字段。多数情况下只需提供maincreateTheme会根据亮度算法自动推导其余字段与对比度文字色。这条规则同样适用于primary、secondary这类语义色键之外的自定义键status.danger之类。构建调色板时优先复用mui/material/colors例如import { purple } from mui/material/colors后取purple[500]以获得符合 Material Design 规范的现成色阶而不是手写难以对齐的十六进制色。palette.mode: dark会把整套主题强制切换成暗色调色板。注意如果使用全自定义调色板并配合暗色模式务必保证自定义色值与当前 mode 的语义相符——例如暗色下背景应使用深色系否则可能出现深底浅字之外的错乱观感。详见 Dark mode。五、colorSchemes vs palette-only 暗色系统级明暗方案的正确姿势如果你需要跟随系统偏好、跨标签页同步、切换时可关闭过渡动画、兼容 SSR这类完整的明暗切换体验指南明确建议使用colorSchemes而非旧的、能力较窄的仅设palette.mode方案。import { createTheme } from mui/material/styles; // 内置 light dark 两套 scheme const theme createTheme({ colorSchemes: { dark: true }, });几个必须牢记的判定规则colorSchemes与palette同时存在时palette优先。避免无意中覆盖。这一点在源码中有直接体现createTheme 内部会把传入的palette通过attachColorScheme逻辑合并进对应 schemecreateTheme.ts 附近的attachColorScheme会以palette为准重建 scheme 的palette。defaultColorScheme默认取palette?.mode从 createTheme.ts 可见未显式声明palette时默认colorSchemes { light: true }默认 scheme 在未指定palette.mode时回落到light。也就是说palette.mode: dark依然可以表达默认就是暗色只是它不再被当作独立的运行时切换机制。用useColorScheme读取 / 更新当前 mode 以实现切换。注意首次渲染时mode可能是undefined系统偏好尚未确定 / SSR 尚未水合代码需显式处理该分支避免水合hydration不一致。ThemeProvider上支持storageManager、disableTransitionOnChange、noSsr等属性用于定制持久化存储、切换 scheme 时关闭过渡动画以及控制 SSR 期间的颜色方案行为。这些细节都收录在 Dark mode 文档中。如果你已经用 v5 时代的静态palette.mode 两个 theme 手动切换方案工作了很久迁移到colorSchemes的核心收益在于系统偏好监听、多标签页同步、以及 scheme 切换时避免整页重挂载的体验都可以交给框架层处理。六、开启 CSS 主题变量cssVariables: true 与 theme.vars当需要更清晰的调试、暗色局部区域的更少主题嵌套、以及切换时更少的 JS 计算时可以在createTheme中开启cssVariables: trueimport { createTheme } from mui/material/styles; const theme createTheme({ cssVariables: true, colorSchemes: { light: true, dark: true }, });开启后组件的样式将使用var(--mui-...)形式的 CSS 变量对应地在样式回调中应优先使用theme.vars它把 palette / typography 等令牌镜像成指向 CSS 变量的引用而不是直接读theme.palette.*的静态值。用法细节见 Usage。关于cssVariables的选项形态从 createTheme.ts 的类型定义可以看出它既可以传boolean也可以传PickCssVarsThemeOptions, CssVarsConfigList对象做更细粒度的配置例如通过colorSchemeSelector控制选择器形态。四个高频注意事项不要向createTheme传自定义的vars键。该键为 CSS 变量功能保留由框架自动生成手动传入会与自动生成逻辑冲突。CSS 变量下的暗色专属样式用theme.applyStyles(dark, { ... })而不要用基于theme.palette.mode的分支写法——后一种方式在方案切换时容易造成闪烁。官方在 Usage 与 Configuration 中均有明确警告。防首帧闪烁脚本的位置InitColorSchemeScript必须放在任何渲染内容之前以阻止初始 color-scheme 的闪烁。具体到路由框架App Router放在app/layout.tsx的body内、{children}之前Pages Router放在_document.tsx中、Main /之前。权衡取舍开启后 HTML 体积会变大同时输出明暗两套方案的变量可能影响 FCP收益是切换 scheme 时更少的 JS 工作量与更好的 SSR 暗色体验。综述见 Overview。此外老版本的CssVarsProvider已被具备同等能力的ThemeProvider取代——v9 中统一使用ThemeProvider配合cssVariables与colorSchemes选项即可。关于theme.vars的类型theme.vars的类型默认并未启用。若要在 TypeScript 中使用需要参照 Usage 中的 TypeScript 章节开启相关类型声明见 reference.md。当组件可能运行在ThemeProvider之外时推荐使用兼容两种形态的兜底写法backgroundColor: (theme.vars || theme).palette.primary.main;这段代码同时覆盖开启了 cssVariables有theme.vars与未开启只有theme.palette两种运行时是 reference.md 提供的官方推荐 fallback 写法。七、Typography 与 Spacing两个最容易踩坑的度量体系排版Material UI 的排版使用rem单位默认根字号语义与设计规范见 Typography 文档。可通过调整typography.fontSize修改基准字号或逐个字体变体h1~body2、button等的fontSize来覆盖。若希望排版随断点整体缩放用responsiveFontSizes(theme)包装一次即可它位于mui/material/styles与enhanceHighContrast属于同一类主题增强器模式import { createTheme, responsiveFontSizes } from mui/material/styles; let theme createTheme(); theme responsiveFontSizes(theme);间距theme.spacing(n)遵循配置好的间距标尺默认每单位 8pxspacing(2)即 16pxsx里的间距简写如p: 2、gap: 1走同一套系统因此sx与theme.spacing语义天然一致。数组形式的spacing配置存在表达力限制对负数、小数、auto支持不完整。需要完整表达力时在主题中把spacing配成函数形式而不是数组。八、主题的组合与合并分步 createTheme 与 deepmerge现实项目中经常出现某个令牌要由另一个令牌推导而来的需求。官方推荐的分步构建法import { createTheme } from mui/material/styles; // 第一步用基础选项产出完整主题 const baseTheme createTheme({ palette: { primary: { main: #1976d2 } }, }); // 第二步把第一步的成果当作输入再派生新主题 const derivedTheme createTheme(baseTheme, { typography: { h1: { color: baseTheme.palette.primary.main }, }, });这等价于官方文档 Using theme options to define other options主题组合章节的推荐实践。要点在 Theming 文档 中亦有展开。两条硬性规则不要把多个参数当作自动深合并来依赖——createTheme只会正式处理第一个参数对应官方 createTheme(options, ...args) 的说明。也就是说createTheme(a, b)里的b不会被规范地深合并进结果。自行完成深合并后再一次性传入。可以借助mui/utils的deepmergeimport { deepmerge } from mui/utils; import { createTheme } from mui/material/styles; const theme createTheme(deepmerge(baseOptions, partialOverrides));这种显式深合并 单对象传入的写法能保证前向兼容也不会对参数处理次序产生隐式依赖。九、嵌套 ThemeProvider局部覆盖外层主题ThemeProvider支持嵌套内层 Provider 覆盖外层import { createTheme, ThemeProvider } from mui/material/styles; const outer createTheme({ palette: { primary: { main: #1976d2 } } }); const inner createTheme({ palette: { primary: { main: #9c27b0 } } }); ThemeProvider theme{outer} App / ThemeProvider theme{inner} IsolatedSection / {/* 此处用紫色 primary */} /ThemeProvider /ThemeProvider只有当你有意在父主题基础上扩展时才使用函数式写法theme{(outerTheme) createTheme({ ...outerTheme, ...overrides })}——此时outerTheme是已完成解析的完整主题对象{ ...outerTheme }会把外层全部令牌带进新主题。注意函数式写法要求拿到的是已解析主题而非原始 options所以它适合在 Provider 层级做基于父主题的增量定制而不是用来替代createTheme的一次性组合。十、自定义品牌设计令牌与 TypeScript 类型增强当你需要承载品牌专属的设计键时例如status.danger分两步走第 1 步在createTheme中挂载自定义键import { createTheme } from mui/material/styles; const theme createTheme({ status: { danger: #e53e3e }, palette: { primary: { main: #1976d2 }, // 需要新增调色板字段时参照 palette 文档的增强模式 }, });第 2 步同时增强Theme与ThemeOptions两个接口完整模板见 reference.mddeclare module mui/material/styles { interface Theme { status: { danger: string }; } interface ThemeOptions { status?: { danger?: string }; } }必须同时增强两者是因为Theme描述的是已解析主题的形态而ThemeOptions描述的是createTheme入参的形态——只增强其一要么是入参时类型报错要么是消费时读不到类型。三条相关的扩展守则扩展shape新增圆角键时必须同时增强Shape与ShapeOptions两个接口参考 reference.md 中的说明这是shape类型体系的特殊要求。扩展 palette往 palette 加业务字段时遵循 palette 文档中的 TypeScript 增强模式同样要保证Palette/PaletteOptions两侧类型一致。严禁把theme.vars用作自定义属性名它是 CSS 变量支持功能的私有字段AGENTS.md 与 reference.md 均明确警示占用它会与框架自动生成的 vars 结构冲突。十一、Windows 高对比模式enhanceHighContrast 主题增强器enhanceHighContrast是 Material UI v9 提供的一个主题增强器与responsiveFontSizes属于同一设计模式作用是为 MUI 组件追加media (forced-colors: active)覆盖从而在 Windows 高对比 / 强制颜色Forced Colors模式下保持良好的可读性。最小用法import { createTheme, enhanceHighContrast } from mui/material/styles; const theme enhanceHighContrast(createTheme());三个关键事实均有源码佐证实现见 enhanceHighContrast.ts它接收一个已完全创建的 theme返回增强后的副本——务必在createTheme之后调用绝不能包在createTheme内部。默认使用 CSS 系统颜色关键字Highlight、HighlightText、ButtonBorder等而非项目色板中的具体色值。默认 token 全集如下表摘自 enhanceHighContrast.ts 的defaultHcTokensToken默认系统色关键字用途disabledGrayText禁用元素颜色errorActiveText错误状态色selectedBackgroundSelectedItem选中项背景selectedTextSelectedItemText选中项文字activeBackgroundHighlight激活/选中toggled控件背景activeTextHighlightText激活/选中控件文字buttonBorderButtonBorder交互控件边框buttonTextButtonText按钮文字/图标canvasCanvas页面/画布背景需要对齐品牌色时可传第二个参数覆盖个别 tokenconst theme enhanceHighContrast(createTheme(), { activeBackground: SelectedItem, // 例切换/激活控件背景 activeText: SelectedItemText, });约束token 值只能传 CSS 系统颜色关键字——因为只有这些关键字是浏览器能保证与配对的 token 稳定保持对比度的值CSS Color 4 规范定义的 system colors。传入项目十六进制色既可能破坏高对比语义也可能因用户系统主题不同而失效。从源码还可以看到两个值得注意的实现细节enhanceHighContrast.ts函数内部把所有 HCM 覆盖合并进theme.components的styleOverrides覆盖组件涵盖MuiAccordionSummary、MuiAutocomplete、MuiCheckbox、MuiFilledInput、MuiFormControlLabel、MuiFormHelperText、MuiFormLabel、MuiInput、MuiLinearProgress、MuiInputBase、MuiMenuItem、MuiListItemIcon、MuiListItemButton、MuiNativeSelect、MuiOutlinedInput、MuiRadio、MuiSlider、MuiSwitch、MuiButtonBase、MuiTooltip、MuiToggleButton等常用表单与导航组件它刻意用数组形式合并styleOverrides使每个条目作为独立 CSS 规则输出让浏览器级联而非 JS 对象合并来裁决优先级——这对forced-colors覆盖与原主题样式共存是必要的。由于对MuiSlider、MuiSwitch这类track / thumb 子元素拿不到 disabled class的组件源码改用ownerState回调判断禁用态enhanceHighContrast.ts这也提醒你当自定义 styleOverrides 需要感知禁用态时优先依赖ownerState而不是 DOM class。相关测试见 enhanceHighContrast.test.ts可当作验证函数行为与回归边界的参考。十二、进一步阅读仓库内一手资料索引主题仓库内一手资料Theming 概览与 API组合、嵌套、自定义变量theming.md暗色模式与切换colorSchemes、storage、SSRdark-mode.mdCSS 主题变量综述overview.mdCSS 主题变量用法theme.vars、applyStylesusage.mdCSS 主题变量配置InitColorSchemeScript、SSR 防闪烁configuration.mdWindows 高对比模式 token 全集与示例docs/data/material/customization/palette/Palette 文档 High Contrast 章节色板 / 品牌色阶工具docs/data/material/customization/color/TypeScript 主题定制Theme / ThemeOptions 增强theming.md 与 reference.md最后强调一遍最容易犯的三个错误对照自查一是把palette与colorSchemes混用导致误覆盖前者优先二是直接读写保留字段vars三是在 cssVariables 场景下用theme.palette.mode分支编写暗色样式而非theme.applyStyles。避开这三点你的主题体系就能同时稳定服务于明暗切换、SSR 渲染与无障碍高对比场景。【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考