MUI Material 的 Backdrop 组件：遮罩层实现、过渡插槽与样式定制详解

2026-09-05 09:33:20作者：蔡丛锟

Backdrop 是 Material UI 中用于在应用界面上叠加一层半透明遮罩的基础组件，它将用户的注意力聚焦到屏幕上的特定元素，常用于加载状态、对话框与弹窗场景。本文基于仓库中的 Backdrop 官方文档与源码实现，完整讲解 Backdrop 的基本用法、Props 参数、过渡（Transitions）定制方式，以及根元素与过渡插槽（slots）在源码层面的工作原理，帮助你在实际项目中快速搭建可控的遮罩层。

一、Backdrop 是什么：聚焦视觉焦点的遮罩层

文档对 Backdrop 的定义是：Backdrop 组件将用户的焦点收窄到屏幕上的某个特定元素（The Backdrop component narrows the user's focus to a particular element on the screen）。它向用户传达“应用内部状态正在发生变化”的信号，可用于创建加载器（loaders）、对话框（dialogs）等场景。

在其最简单的形态下，Backdrop 会在你的应用上方添加一个变暗（dimmed）的图层。从源码中可以看到这层“变暗”的默认实现：

position: 'fixed',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
right: 0,
bottom: 0,
top: 0,
left: 0,
backgroundColor: 'rgba(0, 0, 0, 0.5)',

也就是说，Backdrop 的根节点是一个 position: fixed 且铺满整个视口的 flex 容器（内容默认水平垂直居中），背景色为 50% 透明度的黑色 rgba(0, 0, 0, 0.5)。这个 flex 布局特性意味着：你放入 children 的内容（比如一个进度圈）会自动位于屏幕正中央，不需要额外的定位代码。

二、基本用法：加载态示例

官方文档中给出的示例（SimpleBackdrop.js）演示了一个带 CircularProgress 前景的基础 Backdrop，用于指示加载状态。点击 Show backdrop 按钮打开遮罩，此后点击页面任意位置即可关闭它：

import * as React from 'react';
import Backdrop from '@mui/material/Backdrop';
import CircularProgress from '@mui/material/CircularProgress';
import Button from '@mui/material/Button';

export default function SimpleBackdrop() {
  const [open, setOpen] = React.useState(false);
  const handleClose = () => {
    setOpen(false);
  };
  const handleOpen = () => {
    setOpen(true);
  };

  return (
    <div>
      <Button onClick={handleOpen}>Show backdrop</Button>
      <Backdrop
        sx={(theme) => ({ color: '#fff', zIndex: theme.zIndex.drawer + 1 })}
        open={open}
        onClick={handleClose}
      >
        <CircularProgress color="inherit" />
      </Backdrop>
    </div>
  );
}

示例中有几个值得注意的实战细节：

open 是必需属性：Backdrop 没有内置的开关状态，完全由你传入的 open 布尔值控制显隐（见类型定义，open 没有默认值）。
zIndex: theme.zIndex.drawer + 1：通过 sx 将遮罩层级抬到 drawer 之上，确保它盖住其他浮层内容；color: '#fff' 则配合 color="inherit" 让进度圈显示为白色。
点击关闭：onClick 被透传到根节点，任何点击都会触发 handleClose——因为根节点铺满全屏，这实现了“点击页面任意位置关闭”的交互。

三、Props 参数详解

结合类型定义文件与 PropTypes，Backdrop 的核心参数如下：

参数	类型	默认值	说明
`open`	`boolean`	—（必填）	为 `true` 时组件显示。直接对应内部过渡组件的 `in` 属性
`invisible`	`boolean`	`false`	为 `true` 时遮罩背景完全透明（仍拦截点击），适合渲染 popover 或自定义 select 组件时使用
`component`	`elementType`	`'div'`	根节点使用的组件，可以是 HTML 元素字符串或自定义组件
`children`	`ReactNode`	—	遮罩层上渲染的内容，默认居中显示
`transitionDuration`	`number \| { appear?, enter?, exit? }`	由 Fade 主题默认值决定	过渡时长（毫秒）。可指定单一数值，也可用对象分别为 appear/enter/exit 指定
`slots`	`{ root?, transition? }`	`{}`	替换根节点组件或过渡组件（见下文“过渡定制”）
`slotProps`	`{ root?, transition? }`	`{}`	分别向 `root`、`transition` 两个插槽透传 props，支持对象或函数形式
`sx`	`SxProps<Theme>`	—	通过 System 的 sx prop 定义样式覆盖或附加 CSS
`classes`	`Partial<BackdropClasses>`	—	覆盖/扩展组件应用的样式类

除了上述自有属性，BackdropOwnProps 还 extends Partial<Omit<FadeProps, 'children'>>（见 Backdrop.d.ts），即 Backdrop 继承了 Fade 组件的全部过渡事件回调：onEnter、onEntered、onEntering、onExit、onExited、onExiting、appear、enter、exit、in 等（children 除外）。这些 props 在运行时经由 {...other} 直接展开透传给内部的过渡组件，测试用例中就使用了 onEntered 回调来验证过渡是否真正完成。

invisible：透明但可拦截的遮罩

invisible 是源码中唯一一个通过 CSS variant 实现的行为开关（Backdrop.js）：

variants: [
  {
    props: { invisible: true },
    style: {
      backgroundColor: 'transparent',
    },
  },
],

注意它只把背景改为透明，position: fixed 全屏覆盖与点击拦截行为保持不变。这正是文档中提到的典型用途：当你需要渲染 popover 或自定义 select 组件、希望挡住背景交互但不希望视觉变暗时，使用 invisible。

四、过渡（Transitions）：默认 Fade 与替换方式

文档的 Transitions 一节指出：Backdrop 默认使用 Fade 过渡，可以通过 slots.transition 和 slotProps.transition 替换为其他过渡组件或向其传递过渡 props。

这一点在源码中体现得很直接（Backdrop.js）：

const [TransitionSlot, transitionProps] = useSlot('transition', {
  elementType: Fade, // 默认过渡组件是 Fade
  externalForwardedProps,
  ownerState,
});

return (
  <TransitionSlot in={open} timeout={transitionDuration} {...other} {...transitionProps}>
    <RootSlot {...rootProps} ref={ref}>
      {children}
    </RootSlot>
  </TransitionSlot>
);

渲染结构是：过渡组件在外，根节点（遮罩层）在内。open 映射为过渡组件的 in，transitionDuration 映射为 timeout。想换成其他过渡（例如 Slide、Collapse 满足 Transition 要求的组件），只需：

<Backdrop
  open={open}
  slots={{ transition: MyTransition }}
  slotProps={{ transition: { timeout: 500 } }}
>
  <CircularProgress />
</Backdrop>

slots.transition 的类型在 Backdrop.d.ts 中被约束为 React.ElementType，且注释提示自定义过渡组件需满足文档中 Transition slots 一节列出的要求；slotProps.transition 的可用 props 基于 Fade 组件的 TransitionProps（见 BackdropSlotsAndSlotProps）。

过渡时长与减弱动画（reduced motion）

transitionDuration 支持单个数值或 { appear, enter, exit } 对象。单元测试验证了两类行为：

设置 transitionDuration={1954} 后，用假时钟推进 1954ms，onEntered 恰好被调用 1 次——即时长精确控制了过渡完成的时机；
当主题配置为 motion.reducedMotion: 'always'（createTheme({ motion: { reducedMotion: 'always' } })）时，过渡时长被压缩为 0，下一个任务即完成进入。

这说明 Backdrop 的过渡行为与主题的 motion 配置是联动的：面向偏好减弱动画的用户时，遮罩会跳过渐变过程直接出现，这是无障碍（a11y）层面的重要保证。

五、根节点插槽、类名与主题定制

root 插槽与类名

Backdrop 通过 useSlot('root', ...) 解析根节点插槽（Backdrop.js），默认元素是 BackdropRoot 这个 styled div，可通过 component 或 slots.root 替换。其工具类名定义在 backdropClasses.ts：

类名 key	实际类名	应用条件
`root`	`MuiBackdrop-root`	始终应用于根元素
`invisible`	`MuiBackdrop-invisible`	当 `invisible={true}` 时附加到根元素

从 useUtilityClasses 的实现可以看到，invisible 类与 root 类挂在同一节点上，因此通过 classes.invisible 或主题覆盖都能针对透明模式做样式定制。

主题覆盖（style overrides）

BackdropRoot 以 name: 'MuiBackdrop'、slot: 'Root' 注册（Backdrop.js），这意味着它支持在主题 components 配置中做 style overrides：

const theme = createTheme({
  components: {
    MuiBackdrop: {
      styleOverrides: {
        root: {
          backgroundColor: 'rgba(0, 0, 0, 0.3)', // 降低变暗程度
        },
        invisible: {
          backgroundColor: 'rgba(0, 0, 0, 0.05)', // 为透明模式添加极浅底色
        },
      },
    },
  },
});

overridesResolver 在 invisible 为 true 时同时返回 [styles.root, styles.invisible]，保证两种规则按序合并生效。

默认 props 与事件透传

组件入口先经过 useDefaultProps({ props: inProps, name: 'MuiBackdrop' })（Backdrop.js），即项目级 DefaultPropsProvider 中针对 MuiBackdrop 设置的默认值会在此处合并，为全局统一调整 Backdrop 行为提供了入口。此外，除已消费的 props 外的其余属性（如 onClick、data-*、aria-* 及 Fade 的过渡回调）会通过 useSlot 与 {...other} 透传到对应层级——根节点相关属性进入 RootSlot，Fade 过渡相关属性进入 TransitionSlot。

六、测试与行为验证

Backdrop.test.js 对该组件做了三方面验证，可作为使用行为的权威依据：

合规性测试（describeConformance）：声明 inheritComponent: Fade，验证 Backdrop 继承 Fade 的 API 契约；ref 指向 HTMLDivElement；插槽声明为 root（期望类名 MuiBackdrop-root）与 transition；testVariantProps: { invisible: true } 验证了 invisible 变体。
children 渲染：<Backdrop open><h1>Hello World</h1></Backdrop> 渲染后 h1 内容可被查询到，确认 children 正常落入根节点。
transitionDuration 行为：如前所述，验证了指定时长精确延迟进入完成、以及 reduced motion 下时长归零的行为。

七、小结与源码导航

Backdrop 的定位是“简单但有完整扩展点的遮罩层”：一层 fixed 全屏 flex 容器 + 50% 黑色背景 + 默认 Fade 过渡，同时通过 slots/slotProps、invisible、主题 overrides 和 useDefaultProps 提供多层定制能力。关键实现文件：