MUI v5迁移后Checkbox样式异常：类名结构变更致样式失效

项目从 MUI v4 迁移到 v5 后，Checkbox 组件自定义样式完全失效，列表显示异常。对比 DOM 结构发现，v5 移除了原有的 MuiIconButton-label 类名的 span 容器，同时新增了一批类名，导致基于该类名的 SCSS 样式无法命中元素。其他组件迁移后表现正常，仅 Checkbox 出问题。

已执行迁移文档中的 codemods 工具完成自动迁移，尝试通过 StyledEngineProvider 设置 injectFirst 调整样式注入顺序，无效果；换回 v4 版本的 Checkbox（从 material-ui/core 导入）则恢复正常。

DOM 结构对比 #

v4 旧版 DOM #

<span class="MuiButtonBase-root MuiIconButton-root jss10 MuiCheckbox-root
      MuiCheckbox-colorSecondary Checkbox jss11 Mui-checked --checked 
      MuiIconButton-colorSecondary" aria-disabled="false">
    <span class="MuiIconButton-label">
        <input class="jss13" tabindex="0" type="checkbox" data-indeterminate="false" value="" checked="">
        <svg width="16" height="16" viewBox="0 0 16 12" xmlns="http://www.w3.org/2000/svg"></svg>
    </span>
</span>

v5 新版 DOM #

<span class="MuiButtonBase-root MuiCheckbox-root MuiCheckbox-colorPrimary 
      PrivateSwitchBase-root MuiCheckbox-root MuiCheckbox-colorPrimary MuiCheckbox-root 
      MuiCheckbox-colorPrimary Checkbox css-1k6mikw-MuiButtonBase-root-MuiCheckbox-root">
    <input class="PrivateSwitchBase-input css-1m9pwf3" tabindex="0" type="checkbox" data-indeterminate="false">
    <svg width="16" height="16" viewBox="0 0 16 12" xmlns="http://www.w3.org/2000/svg" font-size="medium"></svg>
</span>

尝试的样式注入顺序配置 #

return (
    <StyledEngineProvider injectFirst>
      <ThemeProvider theme={theme}>
        <LocaleUtils.LocaleProvider>
          <ErrorBoundary fatal={true} resetKey={resetKey}>
            {(topLevelError: Error | null) =>
              topLevelError ? (
                <FatalError error={topLevelError} />
              ) : (
                React.createElement(routerManager.component, {
                  children: (routes: any) => <RouterContent renderId={renderId} routes={routes} />,
                } as any)
              )
            }
          </ErrorBoundary>
        </LocaleUtils.LocaleProvider>
      </ThemeProvider>
    </StyledEngineProvider>
  );

自定义 Checkbox 组件代码（checkbox.tsx） #

import "./Checkbox.scss";

import React, { useCallback, useMemo } from "react";
import clsx from "clsx";
import { IconLine, IconTick } from "../../../assets";
import { Checkbox }  from "@mui/material";

import * as Utils from "../../../lib/util/Utils";

export interface CheckboxProps {
  id?: string;
  value?: string | boolean;
  checked?: boolean;
  indeterminate?: boolean;
  defaultValue?: boolean;
  className?: string;
  disabled?: boolean;
  onChange?: (event: React.ChangeEvent<HTMLInputElement>, checked: boolean, id?: string) => void;
  size?: "small" | "medium";
}

const CustomCheckbox = (props: CheckboxProps) => {
  const { id, value, checked, size, onChange, disabled, className, defaultValue, indeterminate } = props;

  const handleChange = useCallback(
    (event: React.ChangeEvent<HTMLInputElement>, checked: boolean) => {
      if (onChange) {
        onChange(event, checked, id);
      }
    },
    [id, onChange],
  );

  const isChecked = useMemo(() => {
    if (checked !== undefined) {
      return checked;
    }

    return Boolean(value);
  }, [value, checked]);

  return (
    <Checkbox
      disabled={disabled}
      onClick={Utils.stopPropagation}
      size={size}
      disableRipple={true}
      icon={<IconTick />}
      checkedIcon={<IconTick />}
      indeterminateIcon={<IconLine />}
      indeterminate={indeterminate}
      className={clsx("Checkbox", className)}
      classes={{
        checked: "--checked",
        indeterminate: "--indeterminate",
        disabled: "--disabled",
      }}
      onChange={handleChange}
      value={value}
      checked={isChecked}
      defaultChecked={defaultValue}
      tabIndex={0}
    />
  );
};

export default CustomCheckbox;

样式代码（Checkbox.scss） #

@import "../../../stylesheet/toolkit";

@mixin checkbox-color($color) {
  color: $color !important;

  &.--checked,
  &.--indeterminate {
    .MuiIconButton-label {
      border-color: $color;
      box-shadow: inset 0 0 0 3px transparentize($color, 0.7);
    }
  }
}

.Checkbox.MuiCheckbox-root {
  margin: 0;
  padding: 0;

  @include checkbox-color($goldenrod);

  &:hover {
    background: transparent;
  }

  @each $color, $value in $placeholders-colors {
    &.--col-#{$color} {
      @include checkbox-color($value);
    }
  }

  @each $color, $value in $colors {
    &.--col-#{$color} {
      @include checkbox-color($value);
    }
  }

  .MuiIconButton-label {
    border: 1px solid $grey;
    border-radius: 4px;
    padding: 5px;
    background: white;
  }

  &.--checked {
    svg {
      transform: scale(1);
    }
  }

  &.--disabled {
    @include checkbox-color($grey);

    .MuiIconButton-label {
      border-style: dashed;
      cursor: not-allowed;
    }
  }
}

.Checkbox {
  svg {
    width: 16px;
    height: 16px;
    transform: scale(0);
    transition: transform 300ms cubic-bezier(0.175, 0.885, 0.32, 1.275);
  }
}

问题根源与解决方法 #

问题核心是 MUI v5 重构了 Checkbox 的 DOM 结构，移除了 MuiIconButton-label 容器，原样式依赖该类名的选择器全部失效。

修复步骤： #

1. 替换选择器：将 SCSS 中所有 .MuiIconButton-label 替换为 &（直接命中 Checkbox 根元素），因为 v5 中 input 和 svg 直接作为根元素的子节点，原标签容器的样式需要直接应用到根节点。
   示例修改：

   // 原代码
   .MuiIconButton-label {
     border: 1px solid $grey;
     border-radius: 4px;
     padding: 5px;
     background: white;
   }
   // 修改后
   & {
     border: 1px solid $grey;
     border-radius: 4px;
     padding: 5px;
     background: white;
   }
   

2. 调整勾选状态样式：移除 .MuiIconButton-label 嵌套，直接在 &.--checked 和 &.--indeterminate 下设置边框和阴影：

   @mixin checkbox-color($color) {
     color: $color !important;
   
     &.--checked,
     &.--indeterminate {
       border-color: $color;
       box-shadow: inset 0 0 0 3px transparentize($color, 0.7);
     }
   }
   

3. 禁用默认内边距：MUI v5 Checkbox 根节点默认有内边距，需确保 padding: 0 生效（当前代码已设置，但需确认优先级）。

修改后的样式可以直接适配 v5 的 DOM 结构，无需回退到 v4 组件。

内容的提问来源于stack exchange，提问作者Dzsonah