Modal 对话框
居中弹窗组件,用于需要用户确认的关键操作,支持自定义标题、按钮文案与插槽内容。
默认形态对齐设计稿:左对齐标题 + 右上角关闭按钮 + header 分割线 + 右对齐 pill 按钮(确认在左、取消在右);通过 icon / content-align 可实现「文本 + 图标」通知变体,footer-align="stretch" 可回到等宽铺满的旧按钮布局。穿梭框(双栏选人)场景见 EmContactTransferModal。
使用方式
组件以 EmModal 为名导出,全局注册后可直接使用:
vue
<script setup lang="ts">
import { ref } from 'vue'
const show = ref(false)
</script>
<template>
<em-button @click="show = true">打开对话框</em-button>
<em-modal v-model:show="show" title="确认删除?">
删除后数据将无法恢复,是否继续?
</em-modal>
</template>基础用法
自定义
使用建议
| ✅ Do | ❌ Don't |
|---|---|
| 用于需要用户明确决策的关键操作 | 用来展示普通提示信息(用 Toast) |
删除、退群等不可逆操作设置 type="danger" | 确认删除仍用 primary 主色 |
| 标题直接说明操作后果,如「确认删除该会话?」 | 标题只写「提示」或「确认」 |
| 正文补充必要上下文,帮助用户做决定 | 正文堆砌长段免责条款 |
| 弹窗内最多两个按钮(确认 / 取消) | 在弹窗底部放 3 个以上选项 |
需要复杂表单时使用 Popup 或抽屉 | 在 Modal 里塞入多步骤表单 |
穿梭框 EmContactTransferModal
EmContactTransferModal 是基于 EmModal 的穿梭框(双栏选人)弹窗:左栏为联系人列表(搜索 + 字母分组 + 多选 + 字母索引条),右栏为已选列表(搜索 + 单个移除),底部确认 / 取消按钮。弹窗宽 960px。移动端(<768px,isMobile 口径)重构为全屏单栏范式:候选列表独占主区,已选成员收敛为顶部横向头像条(点击移除),底部仅保留通栏主按钮「确认 (n)」(0 人禁用,贴底含 safe-bottom),取消由头部 × 承担;字母索引条支持按住滑动连续定位(触摸热区 24px),键盘弹起时列表区自动收缩、完成键保持可见。
依赖登录态(自动拉取联系人列表),需包裹在 EmUIKitProvider 内使用。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { EmContactTransferModal, EmUIKitProvider } from '@easemob-community/uikit-im'
const show = ref(false)
const loading = ref(false)
async function onConfirm(ids: string[]) {
loading.value = true
try {
// await inviteMembers(ids) —— 业务侧提交
show.value = false
}
finally {
loading.value = false
}
}
</script>
<template>
<EmUIKitProvider app-key="your-app-key" :auto-init="true">
<em-contact-transfer-modal
v-model:show="show"
:max-selected="20"
:loading="loading"
@confirm="onConfirm"
/>
</EmUIKitProvider>
</template>confirm不会自动关闭弹窗,由业务侧提交成功后自行关闭(配合loading防止重复提交)disabledFn可排除不可选项(如自己 / 已在群成员):(contact: Contact) => boolean
ContactTransferModal API
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| show | boolean | — | 是否显示弹窗(v-model:show 受控) |
| title | string | '' | 弹窗标题,默认按当前语言显示「选择成员」 |
| selectedIds | string[] | () => [] | 已选中 id 列表(v-model:selected-ids 受控) |
| maxSelected | number | — | 最大可选数量,超过会被回滚并 emit max-exceed |
| disabledFn | ContactDisabledFn | — | 左栏条目禁用判定(如:排除自己 / 已在群成员) |
| confirmText | string | '' | 「确认」按钮文案,默认按当前语言显示「确认」 |
| cancelText | string | '' | 「取消」按钮文案,默认按当前语言显示「取消」(移动端不渲染取消按钮,取消语义由头部 × 承担) |
| loading | boolean | false | 确认按钮加载态(异步提交期间禁止重复点击) |
Events
| 事件名 | 参数 | 说明 |
|---|---|---|
update:show | value: boolean | 显示状态变化时触发,供 v-model:show 双向同步 |
update:selectedIds | ids: string[] | 选中变化时触发,供 v-model:selected-ids 双向同步 |
confirm | ids: string[] | 点击「确认」按钮时触发,负载为当前选中 id 列表(不自动关闭,由业务侧决定后续) |
cancel | — | 点击「取消」按钮或右上角关闭时触发(随后自动关闭弹窗) |
max-exceed | max: number | 左栏选择超过 maxSelected 时触发 |
Slots
| 插槽名 | 说明 |
|---|---|
body | — |
panel-top | — |
notice | — |
footer | — |
API
Modal API
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| show | boolean | — | 是否显示弹窗(v-model:show 受控) |
| title | string | '' | 弹窗标题,为空时不渲染标题文本(showClose 为 true 时 header 行仍保留) |
| titleAlign | 'left' | 'center' | 'left' | 标题对齐方式:left(默认,设计稿形态)/ center |
| showClose | boolean | true | 是否显示右上角关闭按钮,默认 true |
| showHeaderDivider | boolean | — | 是否显示 header 下分割线;不传时跟随全局 theme.headerBorder 开关(默认关闭),显式传入优先 |
| width | number | 420 | 弹窗宽度(px),默认 420;桌面端实际宽度 = min(width, 视口宽 × --uikit-modal-width-ratio), 随屏幕宽度按比例自适应(ratio 默认 0.5,宿主可覆写该 CSS 变量调整占屏比),最小不小于 280px |
| height | number | 0 | 弹窗高度(px),不传时由内容撑开;受 90vh 上限约束 |
| contentAlign | 'left' | 'center' | — | 正文对齐方式:left / center(Text-Icon 居中变体);不传时按 type 自动判定—— 通知类(type 非 default,带语义图标)居中,其余左对齐;显式传入优先 |
| icon | string | '' | 正文图标名(Text-Icon 模式),格式 "category/icon-name",如 "circle/bang";也可用 #icon 插槽接管。 不传时按 type 内置语义图标(参考 Toast:danger/warning/info → 感叹号圆,success → 对勾圆) |
| showFooter | boolean | true | 是否显示底部按钮区,默认 true;列表/搜索类弹窗可置 false 并用默认插槽自绘内容 |
| footerAlign | 'right' | 'stretch' | 'right' | 底部按钮布局:right(默认,右对齐 pill 按钮)/ stretch(等宽铺满,兼容旧形态); 移动端忽略该 prop,强制 stretch 等宽铺满 |
| showCancel | boolean | true | 是否显示「取消」按钮,默认 true |
| cancelText | string | t('button.cancel', '取消') | 「取消」按钮文案,默认按当前语言显示「取消」 |
| confirmText | string | t('button.confirm', '确认') | 「确认」按钮文案,默认按当前语言显示「确认」 |
| closeOnClickOverlay | boolean | false | 点击遮罩是否关闭弹窗,默认 false(需通过按钮或 ESC 关闭) |
| type | 'default' | 'danger' | 'warning' | 'info' | 'success' | 'default' | 弹窗类型:default(默认)/ danger(危险操作,确认按钮变红色)/ warning / info / success; 非 default 时正文自动带对应语义图标(icon prop / #icon 插槽可覆盖); 图标默认脱色(主文字色),语义着色需显式开启 semanticIconColor; 移动端回落差异:default 表单类回落 bottom sheet,语义类(短文案确认/通知)保持居中 |
| semanticIconColor | boolean | false | 语义图标是否按类型着色(warning 橙 / danger 红 等),默认 false 脱色展示 |
| confirmDisabled | boolean | false | 确认按钮禁用态(如未选择成员时禁止提交),默认 false |
| confirmLoading | boolean | false | 确认按钮加载态(异步提交期间),默认 false |
| confirmAutoClose | boolean | true | 点击确认后是否自动关闭弹窗,默认 true;异步表单类弹窗置 false,由业务侧在成功后自行关闭 |
| bodyFlush | boolean | false | 正文是否贴边(去除 body 内边距并撑满高度),列表/搜索类弹窗使用,默认 false |
| mobileFullscreen | boolean | false | 移动端全高档位(opt-in):bottom sheet 形态下弹窗拉满视口高度(100dvh + safe-top), 突破默认 80dvh 上限,用于选人等重交互场景;仅移动端 bottom sheet 生效,桌面端无影响 |
Events
| 事件名 | 参数 | 说明 |
|---|---|---|
update:show | value: boolean | 显示状态变化时触发(确认/取消/遮罩或 ESC 关闭),负载为最新显示状态,供 v-model:show 双向同步 |
confirm | — | 点击「确认」按钮时触发(随后自动关闭弹窗) |
cancel | — | 点击「取消」按钮、右上角关闭、遮罩或按 ESC 关闭时触发(随后自动关闭弹窗) |
Slots
| 插槽名 | 说明 |
|---|---|
title | — |
icon | — |
footer | — |
