Material UI（material-ui）Breakpoints 断点系统实战：媒体查询 API、自定义断点与源码原理

Material UI（material-ui）Breakpoints 断点系统实战：媒体查询 API、自定义断点与源码原理

【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Google's Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui

本篇指南围绕 Material UI 主题系统内置的theme.breakpointsAPI 展开：先讲清默认断点取值与五类 CSS 媒体查询方法（up/down/only/not/between）的语义与区间边界，再覆盖 JavaScript 侧的useMediaQueryhook 及断点自定义配置（含 TypeScript 模块增强）；读完并结合仓库源码对照后，你可以独立完成任何响应式布局需求，并理解每个断点方法生成的媒体查询字符串背后的确切边界规则（例如step参数如何实现"独占断点"）。

为什么 Material UI 需要断点体系

Material Design 要求界面在不同屏幕宽度下自动调整布局。Material UI 对原始 Material 规格做了一套简化实现：断点值被集中定义在主题（theme）里，一方面供官方组件（如Grid）内部使用以实现响应式，另一方面暴露给开发者直接控制自己应用的布局。

断点的底层实现位于 createBreakpoints.ts，并在 createTheme.js 中被createTheme调用，因此你在任何主题对象上都能拿到theme.breakpoints。

默认断点（Default breakpoints）

每个断点由一个键（key）对应一个固定的屏幕宽度（value），默认值如下（与源码 createBreakpoints.ts#L57-L63 保持同步）：

这些值都可以通过后文的自定义断点修改。

CSS Media Queries：五个主题样式助手

CSS 媒体查询是实现响应式布局的惯用方式。主题提供五个助手方法，分别生成一段可直接使用的媒体查询字符串：

• theme.breakpoints.up(key)
• theme.breakpoints.down(key)
• theme.breakpoints.only(key)
• theme.breakpoints.not(key)
• theme.breakpoints.between(start, end)

官方文档示例中，根据屏幕宽度切换背景色（红 / 蓝 / 绿），代码示例（sx或样式函数均可）：

const styles = (theme) => ({ root: { padding: theme.spacing(1), [theme.breakpoints.down('md')]: { backgroundColor: theme.palette.secondary.main, }, [theme.breakpoints.up('md')]: { backgroundColor: theme.palette.primary.main, }, [theme.breakpoints.up('lg')]: { backgroundColor: green[500], }, }, });

仓库中对应的完整可运行演示是 MediaQuery.js，它用styled('div')复现了同样的逻辑：

import { styled } from '@mui/material/styles'; import Typography from '@mui/material/Typography'; import { red, green, blue } from '@mui/material/colors'; const Root = styled('div')(({ theme }) => ({ padding: theme.spacing(1), [theme.breakpoints.down('md')]: { backgroundColor: red[500], }, [theme.breakpoints.up('md')]: { backgroundColor: blue[500], }, [theme.breakpoints.up('lg')]: { backgroundColor: green[500], }, })); export default function MediaQuery() { return ( <Root> <Typography>down(md): red</Typography> <Typography>up(md): blue</Typography> <Typography>up(lg): green</Typography> </Root> ); }

theme.breakpoints.up(key) => media query

参数

1. key（string | number）：断点键（xs、sm等），或一个以 px 为单位的屏幕宽度数字。

返回值

media query：匹配大于等于该断点对应屏幕宽度（闭区间）的媒体查询字符串，可直接用于大多数样式方案。

示例

const styles = (theme) => ({ root: { backgroundColor: 'blue', // Match [md, ∞) // [900px, ∞) [theme.breakpoints.up('md')]: { backgroundColor: 'red', }, }, });

源码印证：在 createBreakpoints.ts#L72-L76 中，up会把断点键解析为对应数值（传数字则直接用数字），生成`@media (min-width:${value}${unit})`。测试用例 createBreakpoints.test.js#L38-L50 验证了up('xs')得到@media (min-width:0px)、up('md')得到@media (min-width:900px)。

theme.breakpoints.down(key) => media query

参数

1. key（string | number）：断点键，或屏幕宽度数字（px）。

返回值

media query：匹配小于该断点屏幕宽度（开区间，不含边界）的媒体查询字符串。

示例

const styles = (theme) => ({ root: { backgroundColor: 'blue', // Match [0, md) // [0, 900px) [theme.breakpoints.down('md')]: { backgroundColor: 'red', }, }, });

源码印证：这是理解step参数的关键。源码 createBreakpoints.ts#L78-L82 中，down生成的查询是@media (max-width:${value - step / 100}${unit})——即从断点值中减去step/100（默认5/100 = 0.05）。所以down(500)的结果是'(max-width: 499.95px)'而非500px：CSS 的@media边界是"包含"的，减去这个极小增量后，down(900)实际匹配到899.95px，从而与up('md')的900px起点之间不产生重叠，实现"独占断点"。测试用例（createBreakpoints.test.js#L52-L80）验证了down('sm')=@media (max-width:599.95px)、down('md')=@media (max-width:899.95px)；也可见down('xs')会产生@media (max-width:-0.05px)这类永不匹配的查询——从源码结构看，这是一个有意的边界行为，xs之下不存在屏幕。

theme.breakpoints.only(key) => media query

参数

1. key（string）：断点键（xs、sm等）。

返回值

media query：匹配从该断点（含）开始、到下一个断点（不含）为止的屏幕宽度区间。

示例

const styles = (theme) => ({ root: { backgroundColor: 'blue', // Match [md, md + 1) // [md, lg) // [900px, 1200px) [theme.breakpoints.only('md')]: { backgroundColor: 'red', }, }, });

源码印证：createBreakpoints.ts#L100-L106 中，only(key)本质上是between(key, 下一个键)的语法糖；特殊地，当key是最后一个断点（如xl）时，没有下一个键，直接退化为up(key)。测试验证了only('md')=@media (min-width:900px) and (max-width:1199.95px)，而only('xl')=@media (min-width:1536px)（createBreakpoints.test.js#L108-L122）。

theme.breakpoints.not(key) => media query

参数

1. key（string）：断点键（xs、sm等）。

返回值

media query：匹配"该断点区间之外"的屏幕宽度——即小于该断点（不含边界）与从下一个断点（含）到无穷大的并集。

示例

const styles = (theme) => ({ root: { backgroundColor: 'blue', // Match [xs, md) and [md + 1, ∞) // [xs, md) and [lg, ∞) // [0px, 900px) and [1200px, ∞) [theme.breakpoints.not('md')]: { backgroundColor: 'red', }, }, });

源码印证：createBreakpoints.ts#L108-L122 对首尾键做了单独处理以保证可读性：

• not('xs')（首个键）直接返回up(下一个键)，即@media (min-width:600px)；
• not('xl')（末个键）直接返回down(key)，即@media (max-width:1535.95px)；
• 中间的键则生成@media not all and (min-width:900px) and (max-width:1199.95px)形式，用 CSS 的not组合查询取反区间。

测试用例（createBreakpoints.test.js#L124-L144）对上述三种形态均逐一断言。

theme.breakpoints.between(start, end) => media query

参数

1. start（string）：断点键或屏幕宽度数字（px）。
2. end（string）：断点键或屏幕宽度数字（px）。

返回值

media query：匹配大于等于start对应宽度（含）且小于end对应宽度（不含）的区间。

示例

const styles = (theme) => ({ root: { backgroundColor: 'blue', // Match [sm, md) // [600px, 900px) [theme.breakpoints.between('sm', 'md')]: { backgroundColor: 'red', }, }, });

源码印证：createBreakpoints.ts#L84-L98 中，end的解析依赖断点键的升序排序结果（见后文sortBreakpointsValues），上界同样减去step/100。测试验证了between('sm', 'md')=@media (min-width:600px) and (max-width:899.95px)，且传数字参数between(600, 800)=@media (min-width:600px) and (max-width:799.95px)也成立。

JavaScript Media Queries：useMediaQuery

有些场景 CSS 不够用——你希望根据断点值改变 React 渲染树本身。此时使用useMediaQueryhook（其文档页有更多细节，源码位于 useMediaQuery.ts）：

const isMdUp = useMediaQuery((theme) => theme.breakpoints.up('md'));

第一个参数既可以是字符串，也可以是接收theme的函数（函数形式必须处于ThemeProvider上下文中，源码在开发模式下会对缺少 theme 的函数参数抛出 console.error 提示，见 useMediaQuery.ts#L156-L166）。

从源码实现可以看到几个关键细节：

• 自动剥离@media前缀：useMediaQuery.ts#L169 中query.replace(/^@media( ?)/m, '')，所以直接把theme.breakpoints.up('md')的完整返回值传给 hook 也不会出错；
• SSR 处理：window.matchMedia()在服务器端不可用，hook 首次挂载时返回defaultMatches（默认false），挂载后才切换为真实匹配值；
• 实现机制：在支持React.useSyncExternalStore的 React 版本中走useMediaQueryNew（useMediaQuery.ts#L79-L118），通过matchMedia(query)建立订阅并监听change事件，保证窗口尺寸跨越断点时组件自动重渲染。

UseMediaQueryOptions支持的选项（useMediaQuery.ts#L7-L31）：

另外源码对print查询有专门告警：向useMediaQuery传入print查询可能导致意外结果，官方建议改用sx属性中的displayPrint字段（useMediaQuery.ts#L171-L180）。

自定义断点（Custom breakpoints）

在主题的theme.breakpoints部分定义项目断点，三个可配置项：

对应源码 createBreakpoints.ts#L31-L43 中的BreakpointsOptions接口，unit与step的默认值'px'和5就在解构处写明。

如果修改默认断点值，需要全部重新提供：

const theme = createTheme({ breakpoints: { values: { xs: 0, sm: 600, md: 900, lg: 1200, xl: 1536, }, }, });

断点的数量与命名完全自由，可以用任意适合项目的名称：

const theme = createTheme({ breakpoints: { values: { mobile: 0, tablet: 640, laptop: 1024, desktop: 1200, }, }, });

顺序不敏感：从源码看，sortBreakpointsValues（createBreakpoints.ts#L45-L52） 会在内部把values按键值升序排序，keys数组、only/not的"下一个键"查找都基于排序结果。测试用例 createBreakpoints.test.js#L15-L36 明确验证了：乱序声明的values与有序声明产生完全相同的keys与values。

TypeScript 项目的模块增强

如果你使用 TypeScript，需要借助**模块增强（module augmentation）**才能让类型系统接受自定义断点键（测试工程位于packages/mui-material/test/typescript/breakpointsOverrides.augmentation.tsconfig.json）：

declare module '@mui/material/styles' { interface BreakpointOverrides { xs: false; // removes the `xs` breakpoint sm: false; md: false; lg: false; xl: false; mobile: true; // adds the `mobile` breakpoint tablet: true; laptop: true; desktop: true; } }

这个BreakpointOverrides接口在源码 createBreakpoints.ts#L3-L8 中声明为空接口，配合OverridableStringUnion类型把'xs' | 'sm' | 'md' | 'lg' | 'xl'联合类型与用户增强合并——设为false的键被剔除，设为true的键被新增，从而up/down等方法参数与Grid等组件的属性都能正确推导。

探索默认值与调试

你可以通过两种方式检查当前断点配置：

• 主题浏览器（theme explorer）中展开$.breakpoints路径；
• 或直接打开开发者工具控制台查看window.theme.breakpoints。

在控制台中可以直观验证本文所有 API 的输出，例如theme.breakpoints.down('md')应得到@media (max-width:899.95px)，与测试文件中的断言完全一致。

小结：五个方法的区间语义速查

以默认断点（xs:0 / sm:600 / md:900 / lg:1200 / xl:1536）为例：

核心要点：up/between/only的下界是"含"，上界（down/only/between）通过step/100的极小偏移实现"不含"，从而保证相邻断点查询互不重叠；not在首尾键上退化为up/down以获得更简洁可读的查询。掌握这套规则后，配合useMediaQuery即可完成从 CSS 样式切换（sx/styled）到 JS 渲染树切换的完整响应式方案。

【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Google's Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui