媒体查询

通过原生 Hook 观察 CSS 媒体查询，并配置可选 SSR 匹配策略。

本指南覆盖默认 Emotion 环境的 Material UI Core；扩展包与额外示例按清单单独标注。

使用场景与业务边界

服务端没有浏览器视口；defaultMatches／ssrMatchMedia 会影响水合，noSsr 不是通用 SSR 修复。

原生组成与范围

原生 useMediaQuery Hook 指南，不是可见控件。

保持 Material UI 原生组合与类型，不替换为 JGuang／Base UI／Radix 同名 API。示例条目不是额外组件。

原生安装与初始化

npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1

采用原生 npm 包与 Emotion，不提供虚构的 JGuang UI Registry 地址。将示例放在原生 ThemeProvider 内，按项目选择 CssBaseline 或 ScopedCssBaseline。先检查 React、现有 Provider、锁文件与 SSR 配置；不要覆盖用户文件或忽略 peer 冲突。本批实际验收 React 19.2.8；React 18 及以下须匹配 react-is。完整初始化规则见随附的双语 setup 文档。

Hook 参数

第一个参数为 CSS 媒体查询字符串，或接收原生 theme 的查询函数；使用 theme 回调时先提供原生 ThemeProvider。第二个 options 参数的 defaultMatches、ssrMatchMedia、matchMedia 与 noSsr 属于原生匹配策略，不是可见组件属性。服务端没有真实视口，应提供可验证的服务端估计，或接受客户端二次匹配；不要用另一套系统的断点回调替换它。

可运行原生示例

下列机器键只选择示例入口，不会作为通用 variant 属性传入每个组件。原生示例 JSX 与数据保持上游原文；JGuang 编写的验收示例明确标注。

基础媒体查询 · SimpleMediaQuery · 上游原生示例
使用断点辅助函数 · ThemeHelper · 上游原生示例
从 withWidth 迁移 · UseWidth · 上游原生示例

尚未支持的额外示例

这些条目仍保留在上游清单中，不静默跳过，也不展示为已完成预览。需要补充依赖／框架验收后再纳入可运行列表。

JavaScript 媒体查询语法扩展 · JavaScriptMedia: json2mq
服务端渲染 · ServerSide: css-mediaquery

真实使用示例

固定版本的未修改原生示例；复制时同时保留所需的局部辅助文件。

import useMediaQuery from '@mui/material/useMediaQuery';

export default function SimpleMediaQuery() {
  const matches = useMediaQuery('(min-width:600px)');

  return <span>{`(min-width:600px) matches: ${matches}`}</span>;
}

示例依赖边界

@mui/material/useMediaQuery, @mui/material/styles

直接导入 Icons／System／Utils 的示例需要匹配 9.4.0 包。局部数据与辅助文件属于示例闭包，不是额外组件。远程图片和模拟操作不提供后端。

安装后验收

执行严格类型检查、生产构建和实际交互。检查键盘标签／焦点、原生支持的禁用／错误／只读语义、深浅色、窄屏和减少动画。按真实宿主数据检查回调，不把复制提示词当作安装完成。初始化工具还需检查服务端 HTML 与无告警水合。

来源与许可

https://github.com/mui/material-ui/tree/809a7717b4c050ba3f69b75300689f07c050a16e

MIT · @mui/material@9.4.0. 保留上游原始内容与许可证。上游完整原文保留于 vendor/docs，不标为全文中文化。