zui

Appearance

Modal 弹窗组件 ​

Modal 组件是一个功能强大的弹窗组件，用于展示重要信息、表单输入或进行用户交互确认。它支持多种尺寸、位置、动画效果和自定义内容，提供组件式和函数式两种调用方式。

基础用法 ​

Modal 组件的基础用法非常简单，通过控制 open 属性来显示或隐藏弹窗。

基础用法

通过控制 open 属性来显示或隐藏弹窗

不同尺寸 ​

Modal 组件支持多种预设尺寸，可以根据内容需求选择合适的大小。

不同尺寸

Modal 组件支持多种预设尺寸和自定义尺寸，可以根据内容需求选择合适的大小

自定义弹窗大小

不同位置 ​

Modal 组件可以显示在屏幕的不同位置，包括居中、顶部、底部、左侧和右侧。

不同位置

Modal 组件可以显示在屏幕的不同位置，包括居中、顶部、底部、左侧和右侧

自定义位置 ​

Modal 组件支持通过设置 position="absolute" 并配合 top、right、bottom、left 属性来自定义弹窗位置，支持像素值和百分比值。

动画效果 ​

Modal 组件提供了多种动画效果，可以通过 animation 属性进行选择。

不同动画效果

遮罩控制 ​

Modal 组件支持控制遮罩层的显示/隐藏，以及自定义遮罩样式。

Mask 测试

测试1: mask=false

测试2: mask=true (默认)

测试3: 自定义遮罩样式

自定义内容 ​

Modal 组件支持自定义头部、内容和底部，可以通过插槽来定制弹窗的各个部分。

自定义内容

Modal 组件支持自定义头部、内容和底部，可以通过插槽来定制弹窗的各个部分， 也可以控制是否显示头部和底部

API 调用方式 ​

除了组件方式，Modal 还提供了函数式 API，可以直接通过 JavaScript/TypeScript 调用。

函数式 API 说明

通过 showModal(options) 函数可以方便地在任何地方打开弹窗，无需在模板中预先声明组件。

该函数返回一个包含 close() 方法的对象，用于手动关闭弹窗。

属性名类型默认值说明
idstring-弹窗的唯一标识符
openboolean-控制弹窗的显示和隐藏
defaultOpenbooleanfalse弹窗的默认显示状态
titlestring-弹窗标题
contentstring | HTMLElement | (() => HTMLElement)-弹窗内容（函数式API时使用）
size'sm' | 'md' | 'lg' | 'xl' | 'fullscreen''md'弹窗尺寸
position'center' | 'top' | 'bottom' | 'left' | 'right' | 'absolute''center'弹窗位置，设置为 'absolute' 时启用自定义位置
closablebooleantrue是否显示关闭按钮
maskbooleantrue是否显示遮罩层
maskClosablebooleantrue点击遮罩层是否可以关闭弹窗
escClosablebooleantrue按 ESC 键是否可以关闭弹窗
footerboolean | HTMLElement | (() => HTMLElement)true底部按钮配置
widthstring | number-自定义宽度
heightstring | number-自定义高度
topstring | number-自定义顶部定位（支持像素值和百分比值），需配合 position="absolute" 使用
rightstring | number-自定义右侧定位（支持像素值和百分比值），需配合 position="absolute" 使用
bottomstring | number-自定义底部定位（支持像素值和百分比值），需配合 position="absolute" 使用
leftstring | number-自定义左侧定位（支持像素值和百分比值），需配合 position="absolute" 使用
transitionDurationnumber300弹窗动画时长（毫秒）
maskTransitionDurationnumber200遮罩层动画时长（毫秒）
animation'zoom' | 'slide' | 'fade' | 'bounce''zoom'弹窗动画类型
contentStyleRecord<string, string | number>{}自定义弹窗样式
maskStyleRecord<string, string | number>{}自定义遮罩样式

事件 ​

事件名参数说明
openvalue: boolean弹窗打开时触发
closevalue: boolean弹窗关闭时触发
ok-点击确定按钮时触发
cancel-点击取消按钮或关闭弹窗时触发

插槽 ​

插槽名说明
default弹窗内容
footer底部自定义内容

函数式 API ​

Modal 组件提供了 showModal 函数，可以通过编程方式打开弹窗：

showModal(options) ​

参数：

  • options: ModalOptions 类型，包含以下属性：
    • title: string - 弹窗标题
    • content: string \| HTMLElement \| (() => HTMLElement) - 弹窗内容
    • size: ModalSize - 弹窗尺寸
    • position: ModalPosition - 弹窗位置
    • animation: 'zoom' \| 'slide' \| 'fade' \| 'bounce' - 弹窗动画类型
    • closable: boolean - 是否显示关闭按钮
    • mask: boolean - 是否显示遮罩层
    • maskClosable: boolean - 点击遮罩是否可以关闭
    • escClosable: boolean - 按 ESC 键是否可以关闭
    • footer: boolean \| HTMLElement \| (() => HTMLElement) - 底部配置
    • contentStyle: Record<string, string \| number> - 自定义弹窗样式
    • maskStyle: Record<string, string \| number> - 自定义遮罩样式
    • onOk: () => void - 确定按钮回调
    • onCancel: () => void - 取消按钮回调
    • onClose: () => void - 关闭回调

返回值：

  • 包含 close() 方法的对象，用于手动关闭弹窗

使用示例 ​

javascript
import { showModal } from '@/components/Modal';

// 基础用法
const modal = showModal({
  title: '确认操作',
  content: '确定要执行此操作吗？',
  size: 'sm',
  onOk: () => {
    console.log('用户确认操作');
  },
  onCancel: () => {
    console.log('用户取消操作');
  },
});

// 自定义遮罩样式示例
showModal({
  title: '自定义遮罩',
  content: '这个弹窗使用了自定义的遮罩样式',
  mask: true,
  maskStyle: {
    backgroundColor: 'rgba(0, 255, 0, 0.3)',
    backdropFilter: 'blur(5px)',
  },
});

// 无遮罩示例
showModal({
  title: '无遮罩弹窗',
  content: '这个弹窗没有遮罩层',
  mask: false,
});

// 手动关闭
// modal.close();

响应式设计 ​

Modal 组件在移动设备上会自动调整大小和位置，确保良好的用户体验。对于侧边弹窗（left/right），在小屏幕上会自动调整为全屏模式。

无障碍支持 ​

Modal 组件支持无障碍功能，包括 ARIA 属性和键盘导航。默认情况下，弹窗会自动管理焦点，并支持通过 ESC 键关闭。

暗黑模式 ​

Modal 组件完全支持暗黑模式，会根据当前主题自动调整样式。