如何开发可在Storybook中运行的React Modal Component组件

1 库级ModalBox核心实现标准 #

要达到库级组件的要求，需要覆盖可复用性、扩展性、稳定性三个核心维度：

• 基础能力封装：同时支持受控/非受控两种模式，受控模式下用visible + onVisibleChange 由父组件控制状态，非受控模式内置defaultVisible参数管理内部状态，避免用户写冗余的状态逻辑。默认自带点击蒙层关闭、ESC键关闭、右上角关闭按钮三个常规关闭能力，每个能力都留单独的开关支持禁用。
• 样式&功能扩展性：用CSS变量定义核心样式（遮罩透明度、圆角、边距、z-index等），支持传入className、style覆盖容器样式，maskClassName、maskStyle覆盖蒙层样式，同时预留header、footer、closeIcon的自定义渲染插槽，满足不同业务场景的扩展需求。
• 无障碍适配：弹窗打开时自动聚焦到Modal内的第一个可交互元素，关闭时焦点回退到触发弹窗的按钮，添加aria-modal="true"、role="dialog"等语义化属性，支持屏幕阅读器正确识别弹窗身份。
• 类型支持：TS项目要导出完整的组件Props类型定义，所有参数都要有明确的类型和注释，用户引入组件时可以获得完整的类型提示。
• 边界处理：打开时自动锁定body滚动，避免背景滚动穿透；支持getContainer参数自定义挂载节点，默认挂载到body下避免被父容器的overflow: hidden截断；嵌套Modal场景下自动处理z-index层级，不会出现下层Modal盖在上层的问题；销毁时自动清除所有绑定的全局事件（ESC监听、滚动锁定监听），避免内存泄漏。

2 Storybook适配实现步骤 #

完成组件开发后，按以下步骤适配Storybook即可实现可视化调试：

• 先确认已安装必要依赖：React技术栈下需要提前安装@storybook/react、@storybook/addon-controls、@storybook/addon-actions，用于参数可视化调试和事件日志打印。
• 新建故事文件：在ModalBox组件同级目录下新建ModalBox.stories.tsx（JS项目用jsx后缀），引入ModalBox组件和对应的样式文件。
• 配置基础元信息：定义组件的故事分组、默认参数，用argTypes把所有组件参数映射到Storybook的控制面板，布尔类型对应开关、枚举类型对应下拉选择、字符串类型对应输入框，方便直接在面板调整参数看效果。
• 覆盖全场景用例：把基础弹窗、自定义头部/底部、禁用蒙层关闭、超长内容滚动、嵌套弹窗等常用场景，每个场景单独定义一个故事，打开Storybook就能直接看到所有用例的效果。
• 绑定事件监听：用action装饰器把onVisibleChange、onOk、onCancel这些事件绑定到Storybook的事件面板，点击弹窗按钮的时候可以直接看到事件触发日志，验证事件参数是否正确。

示例Story文件代码 #

import type { Meta, StoryObj } from '@storybook/react';
import { ModalBox } from './ModalBox';
import { action } from '@storybook/addon-actions';

const meta = {
  // 故事在侧边栏的路径
  title: 'Components/ModalBox',
  component: ModalBox,
  // 控制面板参数配置
  argTypes: {
    visible: { control: 'boolean' },
    title: { control: 'text' },
    maskClosable: { control: 'boolean', defaultValue: true },
    escClosable: { control: 'boolean', defaultValue: true },
    zIndex: { control: 'number', defaultValue: 1000 }
  },
  // 所有故事的默认参数
  args: {
    onVisibleChange: action('onVisibleChange触发'),
    onOk: action('onOk触发'),
    onCancel: action('onCancel触发'),
    title: '基础弹窗',
    children: '这是弹窗的内容区域',
  },
} satisfies Meta<typeof ModalBox>;

export default meta;
type Story = StoryObj<typeof meta>;

// 基础弹窗故事
export const Base: Story = {};

// 自定义底部故事
export const CustomFooter: Story = {
  args: {
    footer: <button style={{padding: '4px 12px'}}>自定义底部按钮</button>
  }
};

// 禁用蒙层关闭故事
export const DisableMaskClose: Story = {
  args: {
    maskClosable: false,
    title: '点击蒙层无法关闭',
    children: '只能点击关闭按钮或ESC键关闭弹窗'
  }
};

内容的提问来源于stack exchange，提问作者Emmanuel Sánchez