用途
slots/slotProps 模式是 MUI 深度定制组件的主要机制。它允许替换组件内部的子组件、注入自定义渲染器,并向复合组件的每一层传递属性,而无需使用包装器 hack。
主要能力
每个复合 MUI 组件都由更小的内部元素构成。slots 属性可将任意内部元素替换为自己的组件;slotProps 属性可向每个插槽传递额外属性——无论是否替换了该插槽。
关键规则:
- slots 接收组件引用(不是 JSX 元素)
- slotProps 接收普通对象或回调函数
- 插槽名为 camelCase:slots.valueLabel,而非 slots.ValueLabel
- 提供的组件会接收默认插槽组件本应接收的所有属性——需将其透传
使用方式
常见插槽模式
TextField:可替换 input、inputLabel 等插槽,并通过 slotProps 设置 sx、aria-describedby、shrink、htmlInput 的 maxLength 与 pattern 等。
Autocomplete:可替换 paper、popper、listbox 等插槽,slotProps 支持 data-testid、popper modifiers、listbox 的 sx、chip、clearIndicator 等。
Select:可替换 root 插槽,slotProps 可设置 listbox 的 sx 与 MenuItem 样式。
Slider:可替换 thumb、track、rail、valueLabel、mark、markLabel 等插槽,slotProps 支持 data-testid、sx 等。
DatePicker:可替换 day、field、textField、actionBar、toolbar、layout 等插槽,slotProps 支持 day 的 sx、textField 的 size/variant/helperText、actionBar 的 actions、toolbar 的 hidden/toolbarFormat、popper 的 placement 等。
Dialog:可替换 backdrop、transition 插槽,slotProps 支持 backdrop 的 timeout、data-testid,以及 paper 的 sx 与 elevation。
Tooltip:可替换 popper 插槽,slotProps 支持 popper modifiers、arrow、tooltip、transition 等。
自定义插槽组件
创建自定义插槽组件时需遵循:
- 转发 ref——MUI 需要 ref 进行定位(Popper、Tooltip)和焦点管理
- 透传所有属性——父组件会传递必需属性(事件处理器、ARIA 属性、样式),丢弃它们会破坏功能
- 使用 forwardRef——所有插槽组件都必需
合并 sx 时,若自定义插槽定义了自身 sx,同时希望 slotProps.*.sx 也生效,可使用数组语法合并。
slotProps 回调形式
slotProps 可传入函数而非静态对象,以根据组件当前状态(owner state)计算属性。回调模式特别适用于:基于 focused/error/disabled 状态的条件样式、基于值计算的 ARIA 属性、依赖组件内部状态的动态类名。
常见 ownerState 属性因组件而异:
- TextField:focused、error、disabled、required、filled、size、variant、color
- Slider:active、disabled、dragging、focusedThumbIndex、marked、orientation、value
- Button:active、disabled、focusVisible、fullWidth、size、variant、color
- Chip:clickable、deletable、disabled、size、variant、color
- Badge:anchorOrigin、color、invisible、max、overlap、variant
从 v5 迁移到 v6
MUI v6 统一了定制 API。属性重命名:components 改为 slots,componentsProps 改为 slotProps。部分组件原有的专用属性也统一到 slots 下,例如 PaperComponent 对应 slots.paper,PopperComponent 对应 slots.popper,TransitionComponent 对应 slots.transition,BackdropComponent 对应 slots.backdrop,IconComponent 对应 slots.openPickerIcon,OpenPickerButtonProps 对应 slotProps.openPickerButton,InputAdornmentProps 对应 slotProps.inputAdornment,ToolbarComponent 对应 slots.toolbar,PaperProps 对应 slotProps.paper,PopperProps 对应 slotProps.popper,TransitionProps 对应 slotProps.transition,BackdropProps 对应 slotProps.backdrop。
大小写变化:components 使用 PascalCase 键,slots 使用 camelCase。
MUI 提供 codemod 自动化迁移:
npx @mui/codemod v6.0.0/preset-safe ./src
DataGrid 插槽
DataGrid 拥有 MUI 中最丰富的 slots API。可自定义 Toolbar(使用 GridToolbarContainer、GridToolbarExport、GridToolbarFilterButton、GridToolbarQuickFilter 等)、Footer(使用 GridFooterContainer)、No Rows 与 Loading 覆盖层(noRowsOverlay、noResultsOverlay、loadingOverlay)。
适用场景
适用于需要深度定制 MUI 组件内部结构、替换内部子组件、注入自定义渲染器、向复合组件各层传递属性的 React 前端开发场景。
限制
资料未提供该技能的具体安装方式、收费模式、平台支持范围或效果保证等信息。