Storybook中原生MUI组件Props无法自动检测显示问题

开发者阿泽

2026-8-28

问题描述

在Storybook中搭配Docs功能展示MUI原生组件（未对组件做任何扩展或二次封装）时，无法实现组件props的自动检测与展示。
使用MUI Button组件的示例代码如下：

import React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';
import  Button  from  '@mui/material/Button';;

export default {
  title: 'Button',
  component: Button,
} as ComponentMeta<typeof Button>;


const Template: ComponentStory<typeof Button> = (args) => <Button {...args} >Button</Button>;

export const Primary = Template.bind({});
Primary.args = {
};

上述写法下Button组件可正常渲染，但controls面板为空，未展示任何props。替换为封装原生HTML button的自定义组件时，所有props均可正常展示，自定义组件代码如下：

import React, { Component } from 'react';

class Button extends Component<React.HTMLAttributes<HTMLButtonElement>, {}> {
    public render() {
        return (<button></button>); 
    }
}

export default Button;

已修改main.js中的propFilter函数配置，使其返回true以展示所有props，配置代码如下：

//main.js 
module.exports = {
  "stories": ["../src/**/*.stories.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
    '@storybook/addon-controls'],
  "framework": "@storybook/react",
  core: {
    builder: "webpack5"
  },
  typescript: {
    check: false,
    checkOptions: {},
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) => {
        return true
      },
    },
  }
};

项目依赖配置如下：

{
  "devDependencies": {
    "@babel/cli": "^7.17.10",
    "@babel/core": "^7.18.5",
    "@babel/preset-env": "^7.18.2",
    "@babel/preset-typescript": "^7.17.12",
    "@storybook/addon-actions": "^6.5.9",
    "@storybook/addon-docs": "^6.5.9",
    "@storybook/addon-essentials": "^6.5.9",
    "@storybook/addon-interactions": "^6.5.9",
    "@storybook/addon-links": "^6.5.9",
    "@storybook/builder-webpack4": "^6.5.9",
    "@storybook/builder-webpack5": "^6.5.9",
    "@storybook/manager-webpack4": "^6.5.9",
    "@storybook/manager-webpack5": "^6.5.9",
    "@storybook/react": "^6.5.9",
    "@storybook/testing-library": "^0.0.13",
    "babel-loader": "^8.2.5",
    "fork-ts-checker-webpack-plugin": "^7.2.11",
    "jest": "^28.1.1",
    "ts-node": "^10.8.1",
    "typescript": "^4.7.3",
    "webpack": "^5.73.0",
    "webpack-cli": "^4.10.0"
  },
  "publishConfig": {
    "registry": "http://artifacts.cloud.bamfunds.net/repository/bam-npm/"
  },
  "peerDependencies": {
    "@emotion/react": "^11.9.3",
    "@emotion/styled": "^11.9.3",
    "@mui/material": "^5.8.4",
    "@types/node": "^16.11.36",
    "@types/react": "^18.0.9",
    "@types/react-dom": "^18.0.5",
    "react": "^18.1.0",
    "react-dom": "^18.1.0",
    "react-router-dom": "^6.3.0"
  },
}

解决方案

问题核心原因是react-docgen-typescript默认仅解析项目本地源码的类型定义，不会处理node_modules目录下的第三方包类型，MUI作为安装在依赖中的第三方组件库，其props类型不会被自动提取。
按以下步骤修改配置即可修复：

在main.js顶部引入path模块：const path = require('path')
调整reactDocgenTypescriptOptions配置，新增tsconfigPath指向项目的tsconfig文件，同时将MUI的包路径加入类型解析的包含范围，修改后的typescript配置段如下：

typescript: {
  check: false,
  checkOptions: {},
  reactDocgen: 'react-docgen-typescript',
  reactDocgenTypescriptOptions: {
    shouldExtractLiteralValuesFromEnum: true,
    tsconfigPath: path.resolve(__dirname, "../tsconfig.json"),
    propFilter: (prop) => {
      // 若需要过滤React原生HTML属性减少冗余，可保留以下判断，全量展示直接返回true即可
      if (prop.parent) {
        return !prop.parent.fileName.includes('node_modules/@types/react')
      }
      return true
    },
    // 关键配置：允许解析node_modules下MUI组件的类型定义
    include: ["src/**/*", "node_modules/@mui/material/**/*"],
  },
}

检查项目tsconfig.json配置，不要将node_modules/@mui加入严格排除范围，也可在compilerOptions.types中显式添加@mui/material的类型引用。
清除Storybook缓存后重启服务，Controls面板即可正常加载MUI组件的所有props。

若使用Storybook 7+版本，默认docgen解析逻辑已做优化，只需在配置中设置features.emotionAlias=false适配MUI即可，无需额外调整include路径。

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