React中MUI Stepper的StepContent无法渲染问题排查

常见问题排查与修复 #

1. 检查StepContent的key属性是否唯一匹配步骤索引 #

MUI Stepper依赖唯一key识别不同步骤内容，务必保证每个StepContent的key与对应Step的索引完全一致：

<Stepper activeStep={activeStep}>
  <Step key={0}>
    <StepLabel>Dispatchs</StepLabel>
    <StepContent key={0}>
      {/* Dispatchs步骤内容 */}
    </StepContent>
  </Step>
  <Step key={1}>
    <StepLabel>Orders</StepLabel>
    <StepContent key={1}>
      {/* Orders步骤内容 */}
    </StepContent>
  </Step>
  <Step key={2}>
    <StepLabel>Tenders</StepLabel>
    <StepContent key={2}>
      {/* Tenders步骤内容 */}
    </StepContent>
  </Step>
</Stepper>

2. 确认activeStep状态控制逻辑正确 #

检查activeStep的更新逻辑，切换到Orders或Tenders步骤时，确保状态值对应正确的步骤索引：

const [activeStep, setActiveStep] = useState(0);

const handleNext = () => {
  setActiveStep(prev => prev + 1);
};

const handleBack = () => {
  setActiveStep(prev => prev - 1);
};

3. 排查错误的条件渲染逻辑 #

检查Orders和Tenders的StepContent内部，是否存在错误的条件判断导致内容被隐藏：

// 错误示例：条件错误导致内容不渲染
<StepContent>
  {someInvalidCondition && <div>Orders内容</div>}
</StepContent>

替换为正确的条件判断，或直接渲染内容。

4. 验证组件结构符合MUI规范 #

确保StepContent直接嵌套在Step内部，无多余层级嵌套：

// 正确结构示例
<Step>
  <StepLabel>Orders</StepLabel>
  <StepContent>
    <Typography>Orders步骤内容</Typography>
    <Box sx={{ mt: 2 }}>
      <Button onClick={handleBack}>返回</Button>
      <Button onClick={handleNext}>下一步</Button>
    </Box>
  </StepContent>
</Step>

5. 排查样式冲突问题 #

检查自定义样式或全局样式是否覆盖了StepContent的显示属性，比如：

/* 错误示例：隐藏了StepContent */
.MuiStepContent-root {
  display: none;
}

移除这类样式，或使用MUI的sx属性重新设置显示规则。

修复后的最小复现代码示例 #

import * as React from 'react';
import Box from '@mui/material/Box';
import Stepper from '@mui/material/Stepper';
import Step from '@mui/material/Step';
import StepLabel from '@mui/material/StepLabel';
import StepContent from '@mui/material/StepContent';
import Button from '@mui/material/Button';
import Typography from '@mui/material/Typography';

const steps = [
  { label: 'Dispatchs', content: 'Dispatchs步骤的内容' },
  { label: 'Orders', content: 'Orders步骤的内容' },
  { label: 'Tenders', content: 'Tenders步骤的内容' },
];

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

  const handleNext = () => {
    setActiveStep(prev => prev + 1);
  };

  const handleBack = () => {
    setActiveStep(prev => prev - 1);
  };

  const handleReset = () => {
    setActiveStep(0);
  };

  return (
    <Box sx={{ maxWidth: 400 }}>
      <Stepper activeStep={activeStep} orientation="vertical">
        {steps.map((step, index) => (
          <Step key={index}>
            <StepLabel>{step.label}</StepLabel>
            <StepContent key={index}>
              <Typography>{step.content}</Typography>
              <Box sx={{ mb: 2 }}>
                <div>
                  <Button
                    disabled={index === 0}
                    onClick={handleBack}
                    sx={{ mr: 1 }}
                  >
                    返回
                  </Button>
                  <Button
                    variant="contained"
                    onClick={handleNext}
                    sx={{ mr: 1 }}
                  >
                    {index === steps.length - 1 ? '完成' : '下一步'}
                  </Button>
                </div>
              </Box>
            </StepContent>
          </Step>
        ))}
      </Stepper>
      {activeStep === steps.length && (
        <Box sx={{ p: 3 }}>
          <Typography>所有步骤已完成</Typography>
          <Button onClick={handleReset} sx={{ mt: 1, mr: 1 }}>
            重置
          </Button>
        </Box>
      )}
    </Box>
  );
}

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