第四章：高级组件

4.2 模态框

概述

模态框（Modal）是覆盖在页面主内容上方的临时窗口，用于展示关键信息、收集用户输入或确认操作。Shadcn提供的模态框组件具有高度可定制性，支持动态控制、动画效果和无障碍访问。

核心特性

  1. 动态控制

    • 通过React状态管理显示/隐藏
    • 支持条件渲染（如表单验证后关闭）
    const [isOpen, setIsOpen] = useState(false);
<Button onClick={() => setIsOpen(true)}>打开模态框</Button>
<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
  {/* 内容 */}
</Modal>

  2. 布局结构

    • 默认包含：遮罩层、容器、标题区、内容区、操作区
    • 支持自定义关闭按钮位置

  3. 动画效果

    • 内置淡入淡出动画
    • 可扩展CSS过渡效果
    .modal-enter { opacity: 0; }
.modal-enter-active { opacity: 1; transition: opacity 200ms; }

基础用法

import { Modal, ModalTrigger, ModalContent } from "@/components/ui/modal";

function Example() {
  return (
    <Modal>
      <ModalTrigger asChild>
        <Button>编辑资料</Button>
      </ModalTrigger>
      <ModalContent>
        <h3 className="text-lg font-semibold">用户信息编辑</h3>
        <FormComponent />
        <div className="flex justify-end gap-2 mt-4">
          <Button variant="outline">取消</Button>
          <Button>保存</Button>
        </div>
      </ModalContent>
    </Modal>
  );
}

高级功能

  1. 尺寸控制

    <ModalContent size="lg">  // sm|md|lg|xl
  {/* 内容 */}
</ModalContent>

  2. 嵌套模态框

    • 通过ModalProvider管理模态框堆叠
    • 支持ESC键逐层关闭

  3. 表单集成

    <ModalContent asChild>
  <form onSubmit={handleSubmit}>
    {/* 表单字段 */}
  </form>
</ModalContent>

最佳实践

  1. 无障碍设计

    • 自动焦点管理（首元素获取焦点）
    • 屏幕阅读器支持ARIA标签
    <Modal aria-labelledby="modal-title">
  <h2 id="modal-title">操作确认</h2>
</Modal>

  2. 性能优化

    • 使用lazy加载模态内容
    • 避免在模态框内渲染大型组件树

  3. 设计规范

    • 保持操作按钮右对齐（确认→取消）
    • 内容区域最大高度限制（带滚动条）

常见问题解决方案

问题解决方法
模态框内容闪烁预加载关键资源
滚动穿透禁用body滚动
移动端布局异常添加视口meta标签
动画卡顿使用will-change: transform

扩展阅读


注：实际使用时需根据Shadcn具体版本调整组件导入路径和API细节。建议结合项目中的`components.json`配置文件确认准确参数。
Last Updated::