mui-v7-mastery

MUI V7 精通

专门针对 Material-UI V7 的技能，用于使用 React + TypeScript 创建专业且响应式的界面。提供迁移、最佳实践和高级模式方面的知识。

何时使用此技能

在以下情况下使用此技能：

• 创建仪表板或管理界面
• 使用 Material Design 开发 React 应用
• 从 MUI V6 迁移到 V7
• 需要移动优先的响应式模式
• 使用深色模式配置专业主题
• 实现复杂组件（表格、表单等）
• 希望确保正确使用 MUI V7 API

MUI V7 使用理念

🎨 MUI 不只是用于按钮和栏！

MUI V7 的真正优势在于：

1. 响应式 Grid 系统 - 可自适应的专业布局
2. 高级主题设置 - 完整的品牌定制
3. 复合组件 - 打造丰富的体验
4. CSS Variables - 高性能动态主题
5. 设计系统 - 确保整个应用的一致性
6. 默认采用移动优先 - 确保界面在任何设备上都能完美运行

📱 移动优先要点

务必先为移动设备设计，再扩展到桌面设备！

基本原则

1. 从 xs（0px）开始 - 基础样式适用于移动设备
2. 使用 up() 扩展 - 使用 theme.breakpoints.up('md') 适配桌面设备
3. 二维布局使用 Grid - 卡片、图库、仪表板
4. 一维布局使用 Stack - 垂直/水平列表
5. 触控目标 ≥44px - 可点击的按钮和图标（WCAG 2.2 AAA）

MUI V7 断点

名称	像素	设备
xs	0px	移动设备竖屏
sm	600px	移动设备横屏 / 平板竖屏
md	900px	平板横屏 / 小型桌面设备
lg	1200px	桌面设备
xl	1536px	大型桌面设备

何时使用 Grid 与 Stack

Precisa de layout?
│
├─ Itens em LINHAS E COLUNAS? → Grid
│   └─ Exemplo: Cards de produtos, dashboard tiles
│
└─ Itens em UMA DIREÇÃO? → Stack
    ├─ Vertical? → Stack (default)
    └─ Horizontal? → Stack direction="row"

何时使用 sx 与 useMediaQuery

Precisa de responsividade?
│
├─ Apenas ESTILOS mudam? → sx prop
│   └─ fontSize, padding, display, width, etc
│
└─ LÓGICA/COMPORTAMENTO muda? → useMediaQuery
    └─ Componentes diferentes, render condicional

快速开始

1. 创建新界面（移动优先）

// PASSO 1: Comece lendo as referências relevantes
// - Read references/responsive-design.md
// - Read references/advanced-theming.md
// - Read references/advanced-components.md

import { Container, Grid, Card, Stack, IconButton, useTheme, useMediaQuery } from '@mui/material';

function Dashboard() {
  const theme = useTheme();

  // PASSO 2: Defina breakpoint APENAS se lógica/comportamento mudar
  const isMobile = useMediaQuery(theme.breakpoints.down('md'));

  return (
    <Container maxWidth="lg">
      {/* PASSO 3: Mobile-first Grid (xs → md → lg) */}
      <Grid container spacing={{ xs: 2, md: 3 }}>
        {/* Mobile: 100% largura, Tablet: 50%, Desktop: 33% */}
        <Grid size={{ xs: 12, md: 6, lg: 4 }}>
          <Card sx={{
            p: { xs: 2, md: 3 },  // Padding responsivo
            minHeight: 200
          }}>
            {/* PASSO 4: Touch targets ≥44px em mobile */}
            <Stack direction="row" spacing={1}>
              <IconButton sx={{ minHeight: 44, minWidth: 44 }}>
                <EditIcon />
              </IconButton>
            </Stack>

            {/* PASSO 5: Componentes diferentes se necessário */}
            {isMobile ? <MobileView /> : <DesktopView />}
          </Card>
        </Grid>
      </Grid>
    </Container>
  );
}

2. 从 V6 迁移到 V7

# ANTES de qualquer código, leia:
# references/migration-v6-to-v7.md

# Depois execute os codemods:
npx @mui/codemod v7.0.0/grid-props src
npx @mui/codemod v7.0.0/lab-removed-components src
npx @mui/codemod v7.0.0/input-label-size-normal-medium src

# Configure ESLint para detectar código antigo:
node scripts/setup-mui-eslint.js

3. 配置专业主题

// Leia references/advanced-theming.md primeiro

import { createTheme, ThemeProvider } from '@mui/material/styles';

const theme = createTheme({
  cssVariables: true, // ✅ Ativa CSS variables (recomendado V7)
  
  colorSchemes: {
    light: {
      palette: {
        primary: { main: '#1976d2' },
        background: { default: '#fafafa' },
      },
    },
    dark: {
      palette: {
        primary: { main: '#90caf9' },
        background: { default: '#121212' },
      },
    },
  },
  
  typography: {
    fontFamily: 'Inter, system-ui, sans-serif',
  },
  
  components: {
    MuiButton: {
      styleOverrides: {
        root: {
          textTransform: 'none',
          borderRadius: 8,
        },
      },
    },
  },
});

推荐工作流

适用于任何 MUI 任务

1. 确定工作类型：

   • 新界面？→ 阅读 responsive-design.md + advanced-components.md
   • 迁移？→ 首先阅读 migration-v6-to-v7.md
   • 主题？→ 阅读 advanced-theming.md
   • 以上都涉及？→ 阅读所有参考资料

2. 阅读相关参考资料：

   // SEMPRE faça isso ANTES de escrever código
   view references/[arquivo-relevante].md
   

3. 遵循模式进行实现：

   • 以参考资料中的示例为基础
   • 根据具体情况进行调整
   • 遵循所述最佳实践

4. 使用 ESLint 验证（可选，但建议执行）：

   node scripts/setup-mui-eslint.js
   npm run lint:mui
   

可用资源

📚 参考资料（按需阅读）

migration-v6-to-v7.md

何时阅读： 迁移现有代码或修复重大变更导致的错误时。

包含：

• ❌ 旧语法与 ✅ V7 新语法
• 重大变更（Grid、导入、属性）
• 自动 codemod
• 逐步迁移指南
• V7 新功能（ESM、CSS Layers）

使用场景：

• 更新到 V7 后出现导入错误
• Grid 组件无法正常工作
• 正在使用已弃用的属性
• Hidden、Dialog.onBackdropClick 等相关问题

responsive-design.md

何时阅读： 创建任何需要在移动设备上正常运行的界面时。

包含：

• 完整的 Grid 系统及示例
• 断点和 useMediaQuery
• 响应式导航模式
• 响应式卡片、表单和对话框
• 移动优先最佳实践

使用场景：

• 创建响应式仪表板
• 创建适配不同屏幕的布局
• 移动设备与桌面设备的导航
• 针对移动设备优化表单

advanced-theming.md

阅读时机： 配置自定义主题或深色模式时。

包含：

• 使用 TypeScript 创建主题
• CSS Variables（V7 新方法）
• 深色／浅色模式切换
• 组件高级自定义
• 自定义变体
• Module augmentation

使用场景：

• 应用品牌视觉识别
• 实现深色模式
• 创建自定义组件变体
• 实现一致的全局样式

advanced-components.md

阅读时机： 实现复杂组件时。

包含：

• 完整的仪表盘布局
• 带骨架屏加载的卡片
• 高级数据表格（排序、搜索、分页）
• 带验证的表单
• Toast／Snackbar 系统
• 异步自动补全
• 性能优化（延迟加载、记忆化、虚拟化）

使用场景：

• 创建专业布局
• 实现数据表格
• 实现带验证的复杂表单
• 加载状态
• 大型列表（虚拟化）

🔧 脚本

setup-mui-eslint.js

用途： 配置 ESLint，自动检测 MUI V6 的旧语法。

使用方法：

node scripts/setup-mui-eslint.js

功能：

• 添加自定义 ESLint 规则
• 检测已弃用的导入
• 提示已移除的属性
• 提供友好且有指导性的消息（表情符号 + 说明）
• 创建用于自动迁移的 npm 脚本

消息示例：

• ❌ MUI V7 不再支持深层导入
• ✨ 此组件已移至 @mui/material
• ⚠️ Grid 已重命名。建议迁移到新版 Grid
• 🔄 请使用 onClose 替代 onBackdropClick

V7 关键变更（快速摘要）

❌ 不再可用：

// Deep imports
import createTheme from '@mui/material/styles/createTheme'; // ❌

// Grid antigo
import Grid from '@mui/material/Grid'; // ❌ (agora é GridLegacy)

// Grid2
import Grid2 from '@mui/material/Grid2'; // ❌ (agora é Grid)

// Componentes do lab
import Alert from '@mui/lab/Alert'; // ❌

// Props depreciadas
<Dialog onBackdropClick={...} /> // ❌
<InputLabel size="normal" /> // ❌
<Hidden xlUp>...</Hidden> // ❌

✅ 现在请使用：

// Imports corretos
import { createTheme } from '@mui/material/styles'; // ✅

// Novo Grid (era Grid2)
import Grid from '@mui/material/Grid'; // ✅

// Componentes movidos
import Alert from '@mui/material/Alert'; // ✅

// Props atualizadas
<Dialog onClose={(e, reason) => {...}} /> // ✅
<InputLabel size="medium" /> // ✅
<Box sx={{ display: { xl: 'none' } }} /> // ✅

仪表盘的响应模式

当收到“创建一个漂亮的仪表盘”的请求时，请遵循以下模式：

1. 阅读参考资料：

   view references/responsive-design.md
   view references/advanced-components.md
   view references/advanced-theming.md
   

2. 采用 Mobile-First 方法实现：

   • 从 xs（移动端）开始 - 垂直布局，触控目标为 44px
   • 扩展到 md（平板） - 2 列，更大的间距
   • 最后适配 lg（桌面端） - 3-4 列，紧凑布局
   • 使用新版 Grid V7 实现响应式布局
   • 使用带深色模式的自定义主题
   • 使用专业组件（不只是基础 Button）
   • 加载状态（Skeleton）
   • TypeScript 中不使用 any

3. 始终包含（Mobile-First）：

   • 用于居中的 Container
   • 使用 size={{ xs: 12, md: 6, lg: 4 }} 的 Grid
   • 使用响应式内边距 p={{ xs: 2, md: 3 }} 的卡片
   • IconButton／Button 的触控目标 ≥44px
   • 垂直布局使用 Stack（不要使用 Grid direction="column"）
   • 使用 Skeleton 表示加载状态
   • 仅在逻辑发生变化时使用 useMediaQuery
   • 使用 cssVariables 的主题
   • 在 375px、768px、1200px 下测试

黄金建议 💡

Mobile-First（优先事项！）

• 始终从 xs 开始 - 先定义移动端的基础样式
• 使用 up() 扩展 - 使用 theme.breakpoints.up('md')，绝不使用 down()
• 触控目标 ≥44px - 按钮、图标和可点击链接

  <IconButton sx={{ minHeight: 44, minWidth: 44 }}>
  

• 触控目标之间的间距 ≥10px - 避免误触
• 2D 布局用 Grid，1D 布局用 Stack - 不要使用 Grid direction="column"
• 样式使用 sx，逻辑使用 useMediaQuery
• 在 375px、768px、1200px 下测试 - 关键断点

触控目标（WCAG 2.2）

场景	可视尺寸	触控目标	WCAG 级别
移动端主要操作	40-48px	48px	AAA
桌面端紧凑布局	32-36px	44px	AAA
法定最小尺寸	24px	24px	AA

推荐模式：

// Visual: 36px (compacto), Touch: 48px (seguro)
<Button sx={{
  height: { xs: 40, md: 36 },  // Visual height
  minHeight: { xs: 48, md: 44 } // Touch target
}}>
  Action
</Button>

性能

• 使用 cssVariables: true 实现动态主题
• 使用 Skeleton 实现加载状态
• 对重量级组件使用延迟加载
• 对大型列表进行虚拟化（react-window）
• 共享 useMediaQuery - 避免在子组件中重复调用

响应式设计

• 始终采用移动优先 - xs → sm → md → lg → xl
• 在 Grid 中使用 size={{ xs: 12, md: 6 }}
• 使用 sx 属性设置响应式样式：

  sx={{
    fontSize: { xs: '14px', md: '16px' },
    p: { xs: 2, md: 3 }
  }}
  

• 仅使用 useMediaQuery 处理条件逻辑
• 在真实设备上测试，不要只在模拟器上测试

主题

• 从一开始就配置深色模式
• 使用 theme.vars.* 设置 CSS 变量
• 在主题中创建变体，不要内联定义
• 使用 TypeScript 的 module augmentation

组件

• 阅读 advanced-components.md 了解相关模式
• 使用组合而非 prop drilling
• 对开销较大的组件进行记忆化
• 骨架屏 > 加载动画

常用命令

# Migração automática
npx @mui/codemod v7.0.0/lab-removed-components src
npx @mui/codemod v7.0.0/grid-props src
npx @mui/codemod v7.0.0/input-label-size-normal-medium src

# Setup ESLint (detecção de código antigo)
node scripts/setup-mui-eslint.js

# Lint MUI
npm run lint:mui

# Migração completa (após configurar ESLint)
npm run mui-migrate

移动优先质量检查清单

在将 MUI V7 界面视为完整之前：

移动优先设计

• xs（0px）基础样式 - 优先确保在移动设备上正常运行
• 使用 up() 渐进增强 - theme.breakpoints.up('md') 和 up('lg')
• 触控目标 ≥44px - 按钮、图标、链接（WCAG 2.2 AAA）
• 视觉高度可以为 32-36px，前提是触控目标 ≥44px
• 交互元素之间的间距 ≥10px
• 二维布局使用 Grid - 卡片、仪表板、图库
• 一维布局使用 Stack - 垂直/水平列表
• 不要使用 Grid direction="column" - 请使用 Stack

响应式设计

• 已在 375px（小屏移动设备） 下测试布局
• 已在 599px（sm 断点边缘） 下测试布局
• 已在 768px（平板） 下测试布局
• 已在 899px（md 断点边缘） 下测试布局
• 已在 1199px（lg 断点边缘） 下测试布局
• 已在 1920px（大屏桌面设备） 下测试布局
• 使用 sx 属性设置样式 - fontSize、padding、display
• 仅使用 useMediaQuery 处理逻辑 - 不同组件、条件渲染
• 共享 useMediaQuery - 不要在子组件中重复使用
• 断点不使用硬编码的像素值

主题与样式

• 已配置深色模式主题
• 已启用 cssVariables: true
• 无已弃用导入导致的错误

性能

• 已实现加载状态（骨架屏）
• 对重量级组件使用延迟加载
• 对大型列表进行虚拟化（react-window）
• 在必要时对组件进行记忆化

代码质量

• TypeScript 无错误
• 未使用 any
• 组件遵循 Atomic Design（适用时）

无障碍

• 颜色对比度符合要求（至少 WCAG AA）
• 交互元素带有 ARIA 标签
• 触控目标符合 WCAG 2.2
• 已使用屏幕阅读器进行测试（关键时）

外部资源

• MUI V7 官方文档
• 迁移指南
• 主题创建器
• Material Design 指南

---

请记住： 充分使用时，MUI V7 功能强大。不要局限于按钮——探索 Grid、主题、组合和高级模式！🚀