Material UI 组合式组件实战：muiName 静态标记、mergeSlotProps 与 component 类型系统

本文基于 Material UI 官方文档「Composition」指南，系统讲解库的三大组合机制：如何用 muiName 静态属性正确包装组件、如何用 mergeSlotProps 工具函数安全合并 slot 属性、以及如何通过 component prop 与 OverrideProps 类型系统实现元素替换与第三方组件集成。读完本文，你将理解 Material UI 组合 API 的设计动机，掌握包装组件时避免内部识别失效的标准写法，并能结合仓库源码验证每一处合并规则的底层实现。

组合（Composition）的设计动机

Material UI 的核心目标之一是让组件组合（composition）尽可能简单。要理解后文的 muiName、component prop、ref 转发等机制，先要看清库面临的实际约束：

• 父组件需要感知子元素的"身份"：Material UI 为了在灵活性与性能之间取得平衡，需要一种方式知道组件接收到的子元素（children）本质上是什么。例如 ListItem 需要区分子元素是否为 ListItemButton、ListItemAvatar 等，才能做正确的样式与布局处理；
• 包装（wrap）组件会切断这种感知：当你用一个自定义函数组件包裹某个 Material UI 组件以增强功能时，内部基于"身份"的识别逻辑可能失效，这就是后文 muiName 方案要解决的问题。

包装组件：muiName 静态属性机制

问题：包装会丢失组件身份

Material UI 通过在部分组件上设置 muiName 静态属性来标记组件类型。从源码可以看到，Icon 组件在文件末尾显式声明了该属性（见 Icon.js）：

Icon.muiName = 'Icon';

对应的 TypeScript 声明中也将其暴露为公开静态成员（见 Icon.d.ts）：

declare const Icon: OverridableComponent<IconTypeMap> & { muiName: string };

类似地，FilledInput、Input、NativeSelect、OutlinedInput、Select、SpeedDialIcon、StepLabel、SvgIcon、ListItemSecondaryAction 等组件都声明了 muiName: string。当父组件需要用"是不是某个 Material UI 组件"这类语义判断子元素时，内部工具 isMuiElement 就依赖这个静态属性做匹配，其测试用例明确验证了这一行为（见 isMuiElement.test.js）：

it('should match static muiName property', () => {
  function Component() {
    return null;
  }
  Component.muiName = 'Component';

  expect(isMuiElement(<Component />, ['Component'])).to.equal(true);
  expect(isMuiElement(<div />, ['Input'])).to.equal(false);
  expect(isMuiElement(null, ['SvgIcon'])).to.equal(false);
  expect(isMuiElement('TextNode', ['SvgIcon'])).to.equal(false);
});

也就是说，isMuiElement 通过读取元素 type 上的 muiName 静态属性来判断元素是否属于指定类型的 Material UI 组件——一旦你用包装组件替代了原组件，包装函数上若没有相同的 muiName，这条识别链就会断开。

标准包装写法

当你确需包装一个组件时，先确认该组件是否设置了 muiName。如果遇到了这类问题，需要做两件事：

1. 包装组件使用与被包装组件相同的 muiName 标记；
2. 转发（forward）所有 props，因为父组件可能需要控制被包装组件的 props。

文档给出的标准示例：

const WrappedIcon = (props) => <Icon {...props} />;
WrappedIcon.muiName = Icon.muiName;

官方文档中的交互示例 Composition.js 展示了包装前后的等价性——两个 IconButton 分别接收原生 Icon 与 WrappedIcon，渲染结果一致：

function WrappedIcon(props) {
  return <Icon {...props} />;
}

WrappedIcon.muiName = 'Icon';

export default function Composition() {
  return (
    <div>
      <IconButton>
        <Icon>alarm</Icon>
      </IconButton>
      <IconButton>
        <WrappedIcon>alarm</WrappedIcon>
      </IconButton>
    </div>
  );
}

注意示例中 WrappedIcon.muiName = 'Icon' 与 Icon.muiName = 'Icon' 取值完全一致，这正是让 isMuiElement 仍能识别为 Icon 的关键。

转发 slot props：mergeSlotProps 工具函数

当你组合一个已经暴露 slotProps 的组件（如 Tooltip）时，不能简单地用展开运算符覆盖，否则会丢掉库内部或用户已经传入的属性。Material UI 提供了 mergeSlotProps 工具函数来合并自定义 props 与 slot props。合并语义为：

• 函数形态会先被解析：如果任一参数是函数，先以 ownerState 解析为对象值再合并；
• 第一个参数的结果优先：解析后，第一个参数的值覆盖第二个参数的同名字段。

特殊属性的合并规则

以下特殊属性在合并时有专门处理，而不是简单覆盖：

属性	合并行为
className	值相互拼接（concatenate），而非互相覆盖
style	对象浅合并（shallow merge），第一个参数的 style key 优先级更高
sx	值拼接为一个数组
^on[A-Z] 事件处理器	两个参数的函数被组合（composed）调用

文档给出的 className 示例——给 Tooltip 的 popper slot 添加自定义类名：

import Tooltip, { TooltipProps } from '@mui/material/Tooltip';
import { mergeSlotProps } from '@mui/material/utils';

export const CustomTooltip = (props: TooltipProps) => {
  const { children, title, sx: sxProps } = props;

  return (
    <Tooltip
      {...props}
      title={<Box sx={{ p: 4 }}>{title}</Box>}
      slotProps={{
        ...props.slotProps,
        popper: mergeSlotProps(props.slotProps?.popper, {
          className: 'custom-tooltip-popper',
          disablePortal: true,
          placement: 'top',
        }),
      }}
    >
      {children}
    </Tooltip>
  );
};

若使用者在 CustomTooltip 上又传入了另一个 className：

<CustomTooltip slotProps={{ popper: { className: 'foo' } }} />

最终 popper slot 的类名会同时包含两者："[…] custom-tooltip-popper foo"，而不是只保留其中一个。

事件处理器的组合/覆盖示例：

mergeSlotProps(props.slotProps?.popper, {
  onClick: (event) => {}, // 与 `slotProps?.popper?.onClick` 组合调用
  createPopper: (popperOptions) => {}, // 覆盖 `slotProps?.popper?.createPopper`
});

即：匹配 on[A-Z] 形态的键会被组合执行，其余键则由第一个参数直接覆盖。

源码级验证：合并规则如何实现

以上文档描述的行为与 mergeSlotProps 的实现一一对应（见 mergeSlotProps.ts）：

• className 拼接：使用 clsx 将两侧的 className 连接成一个字符串，且仅在非空时写回（第 75-76 行）：

  const className = clsx(typedDefaultSlotProps?.className, externalSlotProps?.className);
  return {
    ...defaultSlotProps,
    ...externalSlotProps,
    ...handlers,
    ...(!!className && { className }),
    ...
  

• 事件处理器组合：内部 extractHandlers 遍历默认 slot props 的键，仅当默认侧与外部侧对同一键都是事件处理器函数时才生成组合函数，且外部处理器先执行、默认处理器后执行（第 14-33 行）：

  handlers[key] = (...args: unknown[]) => {
    externalSlotPropsValuekey;
    defaultSlotPropsValuekey;
  };
  

• style 浅合并：仅当两侧都提供 style 时才浅合并，外部键覆盖默认键（第 81-84 行）；

• sx 数组拼接：仅当两侧都提供 sx 时才拼接为数组，非数组值先包成单元素数组（第 85-93 行）；

• 函数参数解析：当任一参数是函数时，返回一个接收 ownerState 的延迟解析函数，先解析默认侧，再用其解析结果构造外部侧的 ownerState 输入（第 34-41 行），最终返回的仍是"函数形态"，保持与调用方的响应式约定一致。

此外，仓库中还有一个面向 Base UI 集成场景的同名工具（参数化对象形态、以 getSlotProps 钩子为核心，见 mergeSlotProps.ts），其注释明确了五层合并顺序：内部 props → additional props → 外部根 slot 转发 props → slotProps.* 外部 props → 最后统一拼接 className。虽然本文档描述的是 @mui/material/utils 导出的两参数版本，但两者共享同一设计原则：className 与 style 永远合并而非覆盖，事件处理器由内部机制负责调用。相关行为有专项测试覆盖（见 mergeSlotProps.test.ts）。

component prop：替换根元素

Material UI 允许通过名为 component 的 prop 改变组件渲染的根元素。例如 List 默认渲染 <ul>，传入字符串或 React 组件即可替换。官方文档示例将根元素换成 <menu>：

<List component="menu">
  <ListItem>
    <ListItemButton>
      <ListItemText primary="Trash" />
    </ListItemButton>
  </ListItem>
  <ListItem>
    <ListItemButton>
      <ListItemText primary="Spam" />
    </ListItemButton>
  </ListItem>
</List>

这一模式价值在于提供了极高的灵活性，也是与路由、表单等第三方库互操作的标准途径。以 Icon 组件为例，其实现中 component 的默认值是 'span'，并被直接传给 styled 组件的 as（见 Icon.js）：

const {
  baseClassName = 'material-icons',
  component: Component = 'span',
  ...
} = props;
// ...
return <IconRoot as={Component} ... />;

传入其他 React 组件

component prop 可以接收任意 React 组件，例如 react-router 的 Link：

import { Link } from 'react-router';
import Button from '@mui/material/Button';

function Demo() {
  return (
    <Button component={Link} to="/react-router">
      React router link
    </Button>
  );
}

使用 TypeScript

要启用 component prop，组件的 props 类型必须以类型参数方式使用。否则 component prop 根本不会出现在类型上。官方示例以 TypographyProps 为例（对任何用 OverrideProps 定义了 props 的组件都适用）：

import { TypographyProps } from '@mui/material/Typography';

function CustomComponent(props: TypographyProps<'a', { component: 'a' }>) {
  /* ... */
}
// ...
<CustomComponent component="a" />;

此时 CustomComponent 必须传入 component="a"，并且会获得全部 <a> HTML 元素的 props，同时 Typography 自身的其他 props 也保留在 CustomComponent 的 props 类型中。

泛型自定义组件

还可以编写接受任意 React 组件（包括内置组件）的泛型自定义组件：

function GenericCustomComponent<C extends React.ElementType>(
  props: TypographyProps<C, { component?: C }>,
) {
  /* ... */
}

当使用时指定了 component，组件所需的必填 props 会传导到泛型组件上：

function ThirdPartyComponent({ prop1 }: { prop1: string }) {
  /* ... */
}
// ...
<GenericCustomComponent component={ThirdPartyComponent} prop1="some value" />;

由于 ThirdPartyComponent 把 prop1 声明为必填，GenericCustomComponent 使用时也必须传入 prop1。

需要注意的是：并非每个组件都对任意组件类型提供了完整的类型支持。文档明确建议——如果你在 TypeScript 下遇到某个组件拒绝其 component props，应提交 issue；团队正在推进使 component props 泛型化的工作。

ref 转发注意事项（Caveat with refs）

本节覆盖两类使用场景下的注意事项：将自定义组件作为 children，或作为 component prop 传入。

部分 Material UI 组件需要访问 DOM 节点。过去通过 ReactDOM.findDOMNode 实现，该函数已被弃用，官方推荐使用 ref 与 ref forwarding。但只有以下组件类型可以被传入 ref：

• 任意 Material UI 组件；
• 类组件（React.Component 或 React.PureComponent）；
• DOM（宿主）组件，例如 div、button；
• React.forwardRef 组件；
• React.lazy 组件；
• React.memo 组件。

若传入的不是上述类型，控制台会出现 React 的告警：

Function components cannot be given refs. Attempts to access this ref will fail. Did you mean to use React.forwardRef()?

注意：若 lazy 或 memo 包裹的组件本身无法持有 ref，同样会触发该告警。某些场景下还会出现辅助调试的附加告警：

Invalid prop component supplied to ComponentName. Expected an element type that can hold a ref.

文档只覆盖最常见的两种用法，修复方式都是改用 React.forwardRef：

-const MyButton = () => <div role="button" />;
+const MyButton = React.forwardRef((props, ref) =>
+  <div role="button" {...props} ref={ref} />);

 <Button component={MyButton} />;

-const SomeContent = props => <div {...props}>Hello, World!</div>;
+const SomeContent = React.forwardRef((props, ref) =>
+  <div {...props} ref={ref}>Hello, World!</div>);

 <Tooltip title="Hello again."><SomeContent /></Tooltip>;

要确认你使用的 Material UI 组件是否有此要求，应查阅该组件的 props API 文档；若需要转发 ref，文档描述中会链接到本章节。

StrictMode 下的额外注意点

若上述场景使用了类组件，在 React.StrictMode 下仍会看到告警——因为库内部出于向后兼容仍会使用 ReactDOM.findDOMNode。解决方式是使用 React.forwardRef 加一个专用 prop，把 ref 转发到类组件内部的 DOM 组件上，之后就不会再出现与 ReactDOM.findDOMNode 弃用相关的告警：

 class Component extends React.Component {
   render() {
-    const { props } = this;
+    const { forwardedRef, ...props } = this.props;
     return <div {...props} ref={forwardedRef} />;
   }
 }

-export default Component;
+export default React.forwardRef((props, ref) => <Component {...props} forwardedRef={ref} />);

关键点在于：解构时把 forwardedRef 从透传给 DOM 的 props 中剔除，避免把 React 内部的 ref 对象错误地当作普通 prop 传给宿主组件。

小结

Material UI 的组合机制围绕三条主线展开，且每条都有明确的源码与测试依据：

1. 身份识别：muiName 静态属性（如 Icon.js 中的 Icon.muiName = 'Icon'）配合 isMuiElement（见 isMuiElement.js）让父组件在包装场景下仍能识别子元素类型；包装时必须复制该静态属性并完整转发 props；
2. slot 属性合并：mergeSlotProps（见 mergeSlotProps.ts）以"className 拼接、style 浅合并、sx 数组合并、事件处理器组合"的规则安全地合并外部与内部 slot props，函数形态参数会被延迟解析；
3. 元素替换：component prop 允许把根元素替换为任意字符串标签或 React 组件，配合 OverrideProps<C, { component: C }> 类型参数获得完整的 props 类型推导；传入无法持有 ref 的函数组件时，应使用 React.forwardRef（类组件场景用 forwardedRef 专用 prop）规避 React 的 ref 告警。

以上写法均直接取自官方指南 composition.md，并已在当前仓库的组件源码、工具函数实现与测试用例中逐一得到印证，可放心作为团队内自定义组件与组合封装的参考规范。