Popup UI 组件

Popup UI 组件是一个基于 Vue 3 的弹出层组件库，包含模态框（Modal）、抽屉（Drawer）和警告框（Alert）等组件，提供了丰富的配置选项和 API 调用方式。

安装

npm install @cimom/vben-core-ui-kit-popup-ui

组件列表

• Modal: 模态对话框
• Drawer: 抽屉组件
• Alert: 警告提示框

Modal 模态对话框

基本使用

<script setup lang="ts">
import { Modal } from '@cimom/vben-core-ui-kit-popup-ui';
import { ref } from 'vue';

const visible = ref(false);

const handleOpen = () => {
  visible.value = true;
};

const handleClose = () => {
  visible.value = false;
};

const handleConfirm = () => {
  console.log('确认');
  visible.value = false;
};
</script>

<template>
  <button @click="handleOpen">打开模态框</button>

  <Modal
    v-model:isOpen="visible"
    title="基本模态框"
    @confirm="handleConfirm"
    @cancel="handleClose"
  >
    <div>这是一个基本的模态框内容</div>
  </Modal>
</template>

使用 API 方式调用

<script setup lang="ts">
import { useModal } from '@cimom/vben-core-ui-kit-popup-ui';

const modal = useModal();

const openModal = () => {
  modal.open({
    title: 'API 调用模态框',
    content: '这是通过 API 方式打开的模态框',
    onConfirm: () => {
      console.log('确认');
      modal.close();
    },
  });
};
</script>

<template>
  <button @click="openModal">API 打开模态框</button>
</template>

Modal 属性

| 属性名 | 类型 | 默认值 | 说明 | | ------------------ | --------- | -------- | -------------------- | | isOpen | boolean | false | 是否显示模态框 | | title | string | '' | 标题 | | titleTooltip | string | - | 标题提示信息 | | description | string | - | 描述信息 | | confirmText | string | '确认' | 确认按钮文本 | | cancelText | string | '取消' | 取消按钮文本 | | showConfirmButton | boolean | true | 是否显示确认按钮 | | showCancelButton | boolean | true | 是否显示取消按钮 | | confirmDisabled | boolean | false | 确认按钮是否禁用 | | confirmLoading | boolean | false | 确认按钮是否加载中 | | closable | boolean | true | 是否显示关闭按钮 | | closeOnClickModal | boolean | true | 点击遮罩是否关闭 | | closeOnPressEscape | boolean | true | 按 ESC 是否关闭 | | centered | boolean | false | 是否居中显示 | | fullscreen | boolean | false | 是否全屏显示 | | fullscreenButton | boolean | true | 是否显示全屏按钮 | | draggable | boolean | false | 是否可拖拽 | | bordered | boolean | true | 是否显示边框 | | destroyOnClose | boolean | true | 关闭时是否销毁子元素 | | loading | boolean | false | 是否显示加载状态 | | submitting | boolean | false | 是否处于提交状态 | | modal | boolean | true | 是否显示遮罩 | | openAutoFocus | boolean | false | 打开时是否自动聚焦 | | header | boolean | true | 是否显示头部 | | footer | boolean | true | 是否显示底部 | | class | string | '' | 自定义类名 | | headerClass | string | '' | 头部自定义类名 | | contentClass | string | '' | 内容自定义类名 | | footerClass | string | '' | 底部自定义类名 | | zIndex | number | - | z-index 层级 | | appendToMain | boolean | false | 是否挂载到主内容区域 | | overlayBlur | boolean | false | 是否模糊背景 |

Modal 事件

| 事件名 | 参数 | 说明 | | ------------- | --------------------------- | ------------------------ | | update:isOpen | (isOpen: boolean) => void | 更新打开状态 | | confirm | - | 点击确认按钮时触发 | | cancel | - | 点击取消按钮时触发 | | close | - | 关闭模态框时触发 | | closed | - | 模态框关闭动画结束后触发 | | open | - | 打开模态框时触发 | | opened | - | 模态框打开动画结束后触发 |

Modal API 方法

| 方法名 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | open | (options?: ModalOptions) => void | - | 打开模态框 | | close | - | Promise<void> | 关闭模态框 | | setData | <T>(data: T) => ModalApi | ModalApi | 设置数据 | | getData | - | <T>() => T | 获取数据 | | setState | (state: Partial<ModalState>) => ModalApi | ModalApi | 设置状态 | | lock | (isLocked?: boolean) => ModalApi | ModalApi | 锁定模态框 | | unlock | - | ModalApi | 解锁模态框 |

Drawer 抽屉组件

基本使用

<script setup lang="ts">
import { Drawer } from '@cimom/vben-core-ui-kit-popup-ui';
import { ref } from 'vue';

const visible = ref(false);
const placement = ref('right');

const handleOpen = () => {
  visible.value = true;
};

const handleClose = () => {
  visible.value = false;
};
</script>

<template>
  <button @click="handleOpen">打开抽屉</button>

  <Drawer
    v-model:isOpen="visible"
    :placement="placement"
    title="基本抽屉"
    @close="handleClose"
  >
    <div>这是一个基本的抽屉内容</div>
  </Drawer>
</template>

使用 API 方式调用

<script setup lang="ts">
import { useDrawer } from '@cimom/vben-core-ui-kit-popup-ui';

const drawer = useDrawer();

const openDrawer = () => {
  drawer.open({
    title: 'API 调用抽屉',
    content: '这是通过 API 方式打开的抽屉',
    placement: 'right',
    width: '30%',
    onClose: () => {
      console.log('关闭');
    },
  });
};
</script>

<template>
  <button @click="openDrawer">API 打开抽屉</button>
</template>

Drawer 属性

| 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | isOpen | boolean | false | 是否显示抽屉 | | title | string | '' | 标题 | | placement | 'top' \| 'right' \| 'bottom' \| 'left' | 'right' | 抽屉位置 | | width | string \| number | '30%' | 宽度（placement 为 left 或 right 时有效） | | height | string \| number | '30%' | 高度（placement 为 top 或 bottom 时有效） | | closable | boolean | true | 是否显示关闭按钮 | | closeOnClickModal | boolean | true | 点击遮罩是否关闭 | | closeOnPressEscape | boolean | true | 按 ESC 是否关闭 | | destroyOnClose | boolean | true | 关闭时是否销毁子元素 | | loading | boolean | false | 是否显示加载状态 | | submitting | boolean | false | 是否处于提交状态 | | modal | boolean | true | 是否显示遮罩 | | header | boolean | true | 是否显示头部 | | footer | boolean | false | 是否显示底部 | | showConfirmButton | boolean | false | 是否显示确认按钮 | | showCancelButton | boolean | false | 是否显示取消按钮 | | confirmText | string | '确认' | 确认按钮文本 | | cancelText | string | '取消' | 取消按钮文本 | | class | string | '' | 自定义类名 | | headerClass | string | '' | 头部自定义类名 | | contentClass | string | '' | 内容自定义类名 | | footerClass | string | '' | 底部自定义类名 | | zIndex | number | - | z-index 层级 |

Drawer 事件

| 事件名 | 参数 | 说明 | | ------------- | --------------------------- | ---------------------- | | update:isOpen | (isOpen: boolean) => void | 更新打开状态 | | confirm | - | 点击确认按钮时触发 | | cancel | - | 点击取消按钮时触发 | | close | - | 关闭抽屉时触发 | | closed | - | 抽屉关闭动画结束后触发 | | open | - | 打开抽屉时触发 | | opened | - | 抽屉打开动画结束后触发 |

Drawer API 方法

| 方法名 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | open | (options?: DrawerOptions) => void | - | 打开抽屉 | | close | - | Promise<void> | 关闭抽屉 | | setData | <T>(data: T) => DrawerApi | DrawerApi | 设置数据 | | getData | - | <T>() => T | 获取数据 | | setState | (state: Partial<DrawerState>) => DrawerApi | DrawerApi | 设置状态 | | lock | (isLocked?: boolean) => DrawerApi | DrawerApi | 锁定抽屉 | | unlock | - | DrawerApi | 解锁抽屉 |

Alert 警告提示框

基本使用

<script setup lang="ts">
import { useAlert } from '@cimom/vben-core-ui-kit-popup-ui';

const alert = useAlert();

const showSuccess = () => {
  alert.success('操作成功', '成功提示');
};

const showError = () => {
  alert.error('操作失败', '错误提示');
};

const showWarning = () => {
  alert.warning('注意事项', '警告提示');
};

const showInfo = () => {
  alert.info('提示信息', '信息提示');
};
</script>

<template>
  <div class="space-x-2">
    <button @click="showSuccess">成功提示</button>
    <button @click="showError">错误提示</button>
    <button @click="showWarning">警告提示</button>
    <button @click="showInfo">信息提示</button>
  </div>
</template>

Alert API 方法

| 方法名 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | success | (message: string, title?: string, options?: AlertOptions) => void | - | 显示成功提示 | | error | (message: string, title?: string, options?: AlertOptions) => void | - | 显示错误提示 | | warning | (message: string, title?: string, options?: AlertOptions) => void | - | 显示警告提示 | | info | (message: string, title?: string, options?: AlertOptions) => void | - | 显示信息提示 | | confirm | (message: string, title?: string, options?: AlertOptions) => Promise<boolean> | Promise<boolean> | 显示确认提示框 |

AlertOptions 配置项

| 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | confirmText | string | '确认' | 确认按钮文本 | | cancelText | string | '取消' | 取消按钮文本 | | showCancelButton | boolean | false | 是否显示取消按钮 | | centered | boolean | true | 是否居中显示 | | closable | boolean | true | 是否显示关闭按钮 | | closeOnClickModal | boolean | true | 点击遮罩是否关闭 | | closeOnPressEscape | boolean | true | 按 ESC 是否关闭 | | duration | number | 3000 | 自动关闭的延时（毫秒），设为 0 则不自动关闭 |

示例

自定义内容的模态框

<template>
  <button @click="openCustomModal">打开自定义模态框</button>
</template>

<script setup lang="ts">
import { useModal } from '@cimom/vben-core-ui-kit-popup-ui';
import { h } from 'vue';

const modal = useModal();

const openCustomModal = () => {
  modal.open({
    title: '自定义内容',
    content: h('div', { class: 'p-4' }, [
      h('h3', { class: 'text-lg font-bold mb-2' }, '用户信息'),
      h('div', { class: 'mb-2' }, [
        h('span', { class: 'font-medium' }, '用户名: '),
        h('span', 'admin'),
      ]),
      h('div', { class: 'mb-2' }, [
        h('span', { class: 'font-medium' }, '邮箱: '),
        h('span', '[email protected]'),
      ]),
      h('div', { class: 'mb-2' }, [
        h('span', { class: 'font-medium' }, '角色: '),
        h('span', '管理员'),
      ]),
    ]),
    width: '500px',
    centered: true,
  });
};
</script>

异步操作的模态框

<template>
  <button @click="openAsyncModal">打开异步操作模态框</button>
</template>

<script setup lang="ts">
import { useModal } from '@cimom/vben-core-ui-kit-popup-ui';

const modal = useModal();

const openAsyncModal = () => {
  const modalInstance = modal.open({
    title: '异步操作',
    content: '确认执行此操作吗？此操作需要一些时间完成。',
    onConfirm: async () => {
      try {
        // 锁定模态框，防止重复提交
        modalInstance.lock();

        // 模拟异步操作
        await new Promise((resolve) => setTimeout(resolve, 2000));

        // 操作成功后关闭模态框
        modalInstance.close();

        // 显示成功提示
        modal.success('操作成功完成');
      } catch (error) {
        // 解锁模态框，允许用户重试
        modalInstance.unlock();

        // 显示错误提示
        modal.error('操作失败: ' + error.message);
      }
    },
  });
};
</script>

表单抽屉

<template>
  <button @click="openFormDrawer">打开表单抽屉</button>
</template>

<script setup lang="ts">
import { useDrawer } from '@cimom/vben-core-ui-kit-popup-ui';
import { ref, h } from 'vue';

const drawer = useDrawer();

const openFormDrawer = () => {
  const formData = ref({
    name: '',
    email: '',
    description: '',
  });

  const drawerInstance = drawer.open({
    title: '添加用户',
    content: h('div', { class: 'p-4' }, [
      h('div', { class: 'mb-4' }, [
        h('label', { class: 'block mb-1' }, '姓名'),
        h('input', {
          class: 'w-full p-2 border rounded',
          value: formData.value.name,
          onInput: (e) => (formData.value.name = e.target.value),
        }),
      ]),
      h('div', { class: 'mb-4' }, [
        h('label', { class: 'block mb-1' }, '邮箱'),
        h('input', {
          class: 'w-full p-2 border rounded',
          value: formData.value.email,
          onInput: (e) => (formData.value.email = e.target.value),
        }),
      ]),
      h('div', { class: 'mb-4' }, [
        h('label', { class: 'block mb-1' }, '描述'),
        h('textarea', {
          class: 'w-full p-2 border rounded',
          rows: 4,
          value: formData.value.description,
          onInput: (e) => (formData.value.description = e.target.value),
        }),
      ]),
    ]),
    footer: true,
    showConfirmButton: true,
    showCancelButton: true,
    confirmText: '保存',
    cancelText: '取消',
    width: '400px',
    onConfirm: async () => {
      // 验证表单
      if (!formData.value.name || !formData.value.email) {
        drawer.error('请填写必填字段');
        return;
      }

      // 锁定抽屉
      drawerInstance.lock();

      try {
        // 模拟提交数据
        await new Promise((resolve) => setTimeout(resolve, 1000));

        // 关闭抽屉
        drawerInstance.close();

        // 显示成功提示
        drawer.success('用户添加成功');
      } catch (error) {
        // 解锁抽屉
        drawerInstance.unlock();

        // 显示错误提示
        drawer.error('保存失败: ' + error.message);
      }
    },
  });
};
</script>