MUIv7组件库模式Skill mui

---

名称: mui 描述: Material-UI v7 组件库模式，包括sx prop样式、主题集成、响应式设计和MUI特定钩子。在使用MUI组件、sx prop样式、主题定制或MUI实用工具时使用。

MUI v7 模式

目的

Material-UI v7（发布于2025年3月）的组件使用模式、sx prop样式、主题集成和响应式设计。

注意: MUI v7 从v6的破坏性更改：

• 深度导入不再有效 - 使用包导出字段
• Modal 中的 onBackdropClick 已移除 - 使用 onClose 替代
• 所有组件现在使用标准化的 slots 和 slotProps 模式
• 通过 enableCssLayer 配置支持CSS层（与Tailwind v4兼容）

何时使用此技能

• 使用MUI sx prop样式化组件
• 使用MUI组件（Box, Grid, Paper, Typography等）
• 主题定制和使用
• 使用MUI断点进行响应式设计
• MUI特定实用工具和钩子

---

快速开始

基本MUI组件

import { Box, Typography, Button, Paper } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';

const styles: Record<string, SxProps<Theme>> = {
  container: {
    p: 2,
    display: 'flex',
    flexDirection: 'column',
    gap: 2,
  },
  header: {
    mb: 3,
    fontSize: '1.5rem',
    fontWeight: 600,
  },
};

function MyComponent() {
  return (
    <Paper sx={styles.container}>
      <Typography sx={styles.header}>
        标题
      </Typography>
      <Button variant="contained">
        操作
      </Button>
    </Paper>
  );
}

---

样式模式

内联样式（< 100行）

对于简单样式的组件，在顶部定义样式：

import type { SxProps, Theme } from '@mui/material';

const componentStyles: Record<string, SxProps<Theme>> = {
  container: {
    p: 2,
    display: 'flex',
    flexDirection: 'column',
  },
  header: {
    mb: 2,
    color: 'primary.main',
  },
  button: {
    mt: 'auto',
    alignSelf: 'flex-end',
  },
};

function Component() {
  return (
    <Box sx={componentStyles.container}>
      <Typography sx={componentStyles.header}>标题</Typography>
      <Button sx={componentStyles.button}>操作</Button>
    </Box>
  );
}

单独样式文件（>= 100行）

对于复杂组件，创建单独样式文件：

// UserProfile.styles.ts
import type { SxProps, Theme } from '@mui/material';

export const userProfileStyles: Record<string, SxProps<Theme>> = {
  container: {
    p: 3,
    maxWidth: 800,
    mx: 'auto',
  },
  header: {
    display: 'flex',
    justifyContent: 'space-between',
    alignItems: 'center',
    mb: 3,
  },
  // ... 更多样式
};

// UserProfile.tsx
import { userProfileStyles as styles } from './UserProfile.styles';

function UserProfile() {
  return <Box sx={styles.container}>...</Box>;
}

---

常用组件

布局组件

// Box - 通用容器
<Box sx={{ p: 2, bgcolor: 'background.paper' }}>
  内容
</Box>

// Paper - 高亮表面
<Paper elevation={2} sx={{ p: 3 }}>
  内容
</Paper>

// Container - 居中对齐内容，带有最大宽度
<Container maxWidth="lg">
  内容
</Container>

// Stack - 带间距的Flex容器
<Stack spacing={2} direction="row">
  <Item />
  <Item />
</Stack>

网格系统

import { Grid } from '@mui/material';

// 12列网格
<Grid container spacing={2}>
  <Grid item xs={12} md={6}>
    左半部分
  </Grid>
  <Grid item xs={12} md={6}>
    右半部分
  </Grid>
</Grid>

// 响应式网格
<Grid container spacing={3}>
  <Grid item xs={12} sm={6} md={4} lg={3}>
    卡片
  </Grid>
  {/* 重复更多卡片 */}
</Grid>

排版

<Typography variant="h1">标题1</Typography>
<Typography variant="h2">标题2</Typography>
<Typography variant="body1">正文文本</Typography>
<Typography variant="caption">小文本</Typography>

// 自定义样式
<Typography
  variant="h4"
  sx={{
    color: 'primary.main',
    fontWeight: 600,
    mb: 2,
  }}
>
  自定义标题
</Typography>

按钮

// 变体
<Button variant="contained">实心</Button>
<Button variant="outlined">轮廓</Button>
<Button variant="text">文本</Button>

// 颜色
<Button variant="contained" color="primary">主要</Button>
<Button variant="contained" color="secondary">次要</Button>
<Button variant="contained" color="error">错误</Button>

// 带图标
import { Add as AddIcon } from '@mui/icons-material';

<Button startIcon={<AddIcon />}>添加项目</Button>

---

主题集成

使用主题值

import { useTheme } from '@mui/material';

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

  return (
    <Box
      sx={{
        p: 2,
        bgcolor: theme.palette.primary.main,
        color: theme.palette.primary.contrastText,
        borderRadius: theme.shape.borderRadius,
      }}
    >
      主题化盒子
    </Box>
  );
}

主题在sx Prop中

<Box
  sx={{
    // 在sx中访问主题
    color: 'primary.main',          // theme.palette.primary.main
    bgcolor: 'background.paper',     // theme.palette.background.paper
    p: 2,                            // theme.spacing(2)
    borderRadius: 1,                 // theme.shape.borderRadius
  }}
>
  内容
</Box>

// 回调用于高级用法
<Box
  sx={(theme) => ({
    color: theme.palette.primary.main,
    '&:hover': {
      color: theme.palette.primary.dark,
    },
  })}
>
  悬停我
</Box>

---

响应式设计

断点

// 移动优先的响应式值
<Box
  sx={{
    width: {
      xs: '100%',    // 0-600px
      sm: '80%',     // 600-900px
      md: '60%',     // 900-1200px
      lg: '40%',     // 1200-1536px
      xl: '30%',     // 1536px+
    },
  }}
>
  响应式宽度
</Box>

// 响应式显示
<Box
  sx={{
    display: {
      xs: 'none',    // 在移动端隐藏
      md: 'block',   // 在桌面端可见
    },
  }}
>
  仅桌面
</Box>

响应式排版

<Typography
  sx={{
    fontSize: {
      xs: '1rem',
      md: '1.5rem',
      lg: '2rem',
    },
    lineHeight: {
      xs: 1.5,
      md: 1.75,
    },
  }}
>
  响应式文本
</Typography>

---

表单

import { TextField, Stack, Button } from '@mui/material';

<Box component="form" onSubmit={handleSubmit}>
  <Stack spacing={2}>
    <TextField
      label="电子邮件"
      type="email"
      value={email}
      onChange={(e) => setEmail(e.target.value)}
      fullWidth
      required
      error={!!errors.email}
      helperText={errors.email}
    />
    <Button type="submit" variant="contained">提交</Button>
  </Stack>
</Box>

---

常见模式

卡片组件

import { Card, CardContent, CardActions, Typography, Button } from '@mui/material';

<Card>
  <CardContent>
    <Typography variant="h5" component="div">
      标题
    </Typography>
    <Typography variant="body2" color="text.secondary">
      描述
    </Typography>
  </CardContent>
  <CardActions>
    <Button size="small">了解更多</Button>
  </CardActions>
</Card>

对话框/模态框

import { Dialog, DialogTitle, DialogContent, DialogActions, Button } from '@mui/material';

<Dialog open={open} onClose={handleClose}>
  <DialogTitle>确认操作</DialogTitle>
  <DialogContent>
    您确定要继续吗？
  </DialogContent>
  <DialogActions>
    <Button onClick={handleClose}>取消</Button>
    <Button onClick={handleConfirm} variant="contained">
      确认
    </Button>
  </DialogActions>
</Dialog>

加载状态

import { CircularProgress, Skeleton } from '@mui/material';

// 旋转器
<Box sx={{ display: 'flex', justifyContent: 'center', p: 3 }}>
  <CircularProgress />
</Box>

// 骨架屏
<Stack spacing={1}>
  <Skeleton variant="text" width="60%" />
  <Skeleton variant="rectangular" height={200} />
  <Skeleton variant="text" width="40%" />
</Stack>

---

MUI特定钩子

useMuiSnackbar

import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

function Component() {
  const { showSuccess, showError, showInfo } = useMuiSnackbar();

  const handleSave = async () => {
    try {
      await saveData();
      showSuccess('保存成功');
    } catch (error) {
      showError('保存失败');
    }
  };

  return <Button onClick={handleSave}>保存</Button>;
}

---

图标

import { Add as AddIcon, Delete as DeleteIcon } from '@mui/icons-material';
import { Button, IconButton } from '@mui/material';

<Button startIcon={<AddIcon />}>添加</Button>
<IconButton onClick={handleDelete}><DeleteIcon /></IconButton>

---

最佳实践

1. 类型化sx Props

import type { SxProps, Theme } from '@mui/material';

// ✅ 良好
const styles: Record<string, SxProps<Theme>> = {
  container: { p: 2 },
};

// ❌ 避免
const styles = {
  container: { p: 2 }, // 无类型安全
};

2. 使用主题令牌

// ✅ 良好：使用主题令牌
<Box sx={{ color: 'primary.main', p: 2 }} />

// ❌ 避免：硬编码值
<Box sx={{ color: '#1976d2', padding: '16px' }} />

3. 一致的间距

// ✅ 良好：使用间距比例
<Box sx={{ p: 2, mb: 3, mt: 1 }} />

// ❌ 避免：随机像素值
<Box sx={{ padding: '17px', marginBottom: '25px' }} />

---

额外资源

更多详细模式，请参阅：

• styling-guide.md - 高级样式模式
• component-library.md - 组件示例
• theme-customization.md - 主题设置