@mt-kit/vue-element-plus-extra

基于 Element Plus 的 Vue 组件库，提供增强的 UI 组件和工具。

安装

pnpm add @mt-kit/vue-element-plus-extra
# 或
yarn add @mt-kit/vue-element-plus-extra
# 或
npm install @mt-kit/vue-element-plus-extra

🪟 弹出窗

一个功能强大的弹窗组件，支持 Modal 和 Drawer 两种模式，提供 Promise 化的 API 和完整的表单验证支持。

特性

• 🎯 双模式支持：Modal 和 Drawer 两种展示模式
• 🚀 Promise 化 API：支持 async/await 语法
• 📝 表单验证：内置 Element Plus Form 支持
• 🎨 自定义按钮：支持自定义按钮和事件处理
• 🔒 状态管理：内置加载、锁定等状态管理
• 📱 响应式设计：支持不同屏幕尺寸
• 🎭 动画支持：流畅的打开/关闭动画

使用

<script lang="ts" setup>
import {
  ElButton
} from 'element-plus';
import { 
  open
} from '@mt-kit/vue-element-plus-extra';

const handleClick = () => {
  open({
    title: '基础弹窗',
    content: '这是弹窗内容',
    mode: DialogMode.MODAL
  });
};
</script>

<template>
  <ElButton @click="handleClick">打开弹窗</ElButton>
</template>

API

open(props)

打开弹窗的主要方法。

参数：

参数	类型	默认值	说明
op	string	-	记录当前操作类型（便于埋点等）
title	string | VNode	-	弹窗标题
titleExtra	string | VNode	-	标题右侧额外内容
footerExtra	VNode | string	-	底部额外按钮区域
content	string | VNode	-	弹窗内容
mode	DialogMode	DialogMode.MODAL	展示模式：模态框或抽屉
size	number | ESize	-	尺寸，支持枚举 ESize 或自定义像素值
classNameOnBody	string	-	容器（Body）附加类名
backdrop	boolean	true	是否显示背投（遮罩）
backdropClosable	boolean	true	点击遮罩是否允许关闭
closable	boolean	true	是否显示右上角关闭按钮
esc	boolean	-	是否允许 ESC 关闭
zIndex	number	-	弹窗的 zIndex
data	D | () => Promise<D | unknown | string | undefined | number | Record<string, unknown>>	-	初始数据或异步拉取函数（当为 Promise 时，会自动显示加载状态）
onClose	(result?: T | Error | unknown, defaultData?: D) => void	-	关闭回调
onSubmit	(result?: D, defaultData?: D) => Promise<Record<string, unknown> | undefined | T | boolean>	-	提交回调，返回 T 或对象
isSubmit	boolean	true	已废弃：为 false 时仅展示关闭（查看/详情）
ok	IButtonProps | string	-	确认按钮配置或文案
cancel	IButtonProps | string	-	取消按钮配置或文案
options	Partial<Omit<DrawerProps, TExcludedProps>> | Partial<Omit<ModalProps, TExcludedProps>>	-	透传 Element Plus 抽屉/模态框属性（与已存在同名属性冲突时以上述 props 为准）

DialogMode

弹窗模式枚举：

enum DialogMode {
  MODAL = 'modal',    // 模态框
  DRAWER = 'drawer'   // 抽屉
}

enum DialogSize {
  S = 300,    // 小尺寸
  M = 400,    // 中尺寸
  L = 600,    // 大尺寸
  XL = 800    // 超大尺寸
  XXL = 1000   // 超大尺寸
  AUTO = 'auto', // 自动
  ALMOST_FULL = 'almost-full', // 几乎全屏
  FULL = 'full' // 全屏
}

🔔 消息提示

基于 Element Plus ElMessage 的单例消息控制器，保证同一时刻仅显示一条消息，并提供“替换”语义以在单例下刷新最新消息。

快速使用

<script lang="ts" setup>
import { ElButton } from "element-plus";
import { messages } from "@mt-kit/vue-element-plus-extra";

const handleSingleton = () => {
  // 单例：已有消息则复用，不会新建
  messages.error("单例消息");
};

const handleReplace = () => {
  // 替换：关闭当前并在关闭后展示最新消息
  messages.error("新的消息", { replace: true });
};
</script>

<template>
  <ElButton @click="handleSingleton">单例消息</ElButton>
  <ElButton @click="handleReplace">单例消息（替换）</ElButton>
</template>

API

• messages.show(options: string | IEnhancedMessageOptions): MessageHandler
• messages.success(message: string, options?: IEnhancedMessageOptions): MessageHandler
• messages.warning(message: string, options?: IEnhancedMessageOptions): MessageHandler
• messages.error(message: string, options?: IEnhancedMessageOptions): MessageHandler
• messages.info(message: string, options?: IEnhancedMessageOptions): MessageHandler
• messages.close(): void 手动关闭当前消息
• messages.isShowing(): boolean 是否正在显示消息

IEnhancedMessageOptions

在 ElMessage 的 MessageOptions 基础上，新增：

• replace?: boolean 是否用新消息替换当前正在显示的消息，默认 false

设计说明：当当前有消息且 replace=true 时，控制器会先关闭当前消息，等待关闭结束后再展示最新待替换的消息，以确保同屏不出现多条消息同时又能“刷新”展示。