Material UI V5 Stepper：顶部标签、线条布局及图标对齐问题

一、顶部标签（Top Text）实现 #

不需要单独创建Grid或Box，直接借助StepLabel组件结合MUI排版组件就能实现。用Stack或Box将顶部文本与步骤图标/标签垂直排列，保持结构紧凑：

import { StepLabel, Stack, Typography } from '@mui/material';

<StepLabel>
  <Stack spacing={0.5} alignItems="center">
    {/* 顶部文本 */}
    <Typography variant="caption" color="text.secondary">
      Top Text
    </Typography>
    {/* 步骤图标（默认或自定义） */}
    <YourStepIcon />
    {/* 底部主标签 */}
    <Typography variant="body2">Step Label</Typography>
  </Stack>
</StepLabel>

二、图标与线条对齐调整 #

默认Stepper的线条位置可能和图标中心不对齐，通过自定义StepConnector的样式修正：

方式1：用sx属性直接调整 #

import { Stepper, StepConnector } from '@mui/material';

<Stepper
  connector={
    <StepConnector
      sx={{
        '& .MuiStepConnector-line': {
          top: '12px', // 图标中心位置，根据图标大小调整（如24px图标设为12px）
          height: 'calc(100% - 24px)', // 减去图标高度，避免线条穿透图标
        },
      }}
    />
  }
>
  {/* 步骤内容 */}
</Stepper>

方式2：自定义Styled Connector组件 #

如果需要复用样式，用styled创建自定义连接器：

import { styled } from '@mui/material/styles';
import StepConnector from '@mui/material/StepConnector';

const AlignedStepConnector = styled(StepConnector)(({ theme }) => ({
  '& .MuiStepConnector-line': {
    top: theme.spacing(1.5), // 对应24px图标中心（theme.spacing(1)=8px）
    height: `calc(100% - ${theme.spacing(3)})`,
    borderColor: theme.palette.grey[300],
  },
}));

// 使用时
<Stepper connector={<AlignedStepConnector />}>
  {/* 步骤 */}
</Stepper>

三、线条整体定位优化 #

如果需要调整线条的左右间距，避免和图标/文本重叠，给StepConnector添加偏移样式：

<StepConnector
  sx={{
    '& .MuiStepConnector-line': {
      left: 'calc(-50% + 12px)', // 左移对应图标半径
      right: 'calc(50% + 12px)',
    },
  }}
/>

完整示例代码 #

import { useState } from 'react';
import {
  Stepper, Step, StepLabel, StepContent, Button, Typography,
  Stack, styled, StepConnector
} from '@mui/material';

const AlignedStepConnector = styled(StepConnector)(({ theme }) => ({
  '& .MuiStepConnector-line': {
    top: theme.spacing(1.5),
    height: `calc(100% - ${theme.spacing(3)})`,
    borderColor: theme.palette.grey[300],
    left: 'calc(-50% + 12px)',
    right: 'calc(50% + 12px)',
  },
}));

const CustomStepLabel = ({ topText, label }) => (
  <StepLabel>
    <Stack spacing={0.5} alignItems="center">
      <Typography variant="caption" color="text.secondary">
        {topText}
      </Typography>
      {/* 可替换为自定义图标 */}
      {/* <Icon>check_circle</Icon> */}
      <Typography variant="body2">{label}</Typography>
    </Stack>
  </StepLabel>
);

export default function VerticalLinearStepper() {
  const [activeStep, setActiveStep] = useState(0);

  const steps = [
    { topText: 'TOP 1', label: 'Step 1', description: 'Description 1' },
    { topText: 'TOP 2', label: 'Step 2', description: 'Description 2' },
    { topText: 'TOP 3', label: 'Step 3', description: 'Description 3' },
  ];

  const handleNext = () => setActiveStep((prev) => prev + 1);
  const handleBack = () => setActiveStep((prev) => prev - 1);
  const handleReset = () => setActiveStep(0);

  return (
    <Stepper
      activeStep={activeStep}
      connector={<AlignedStepConnector />}
      orientation="vertical"
    >
      {steps.map((step, index) => (
        <Step key={step.label}>
          <CustomStepLabel topText={step.topText} label={step.label} />
          <StepContent>
            <Typography>{step.description}</Typography>
            <div style={{ marginBottom: 16 }}>
              <Button
                disabled={index === 0}
                onClick={handleBack}
                style={{ marginRight: 8 }}
              >
                Back
              </Button>
              <Button
                variant="contained"
                color="primary"
                onClick={handleNext}
              >
                {index === steps.length - 1 ? 'Finish' : 'Next'}
              </Button>
            </div>
          </StepContent>
        </Step>
      ))}
    </Stepper>
  );
}

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