跳到正文

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 ​

属性类型默认值说明
showboolean—是否显示弹窗(v-model:show 受控)
titlestring''弹窗标题,默认按当前语言显示「选择成员」
selectedIdsstring[]() => []已选中 id 列表(v-model:selected-ids 受控)
maxSelectednumber—最大可选数量,超过会被回滚并 emit max-exceed
disabledFnContactDisabledFn—左栏条目禁用判定(如:排除自己 / 已在群成员)
confirmTextstring''「确认」按钮文案,默认按当前语言显示「确认」
cancelTextstring''「取消」按钮文案,默认按当前语言显示「取消」(移动端不渲染取消按钮,取消语义由头部 × 承担)
loadingbooleanfalse确认按钮加载态(异步提交期间禁止重复点击)

Events ​

事件名参数说明
update:showvalue: boolean显示状态变化时触发,供 v-model:show 双向同步
update:selectedIdsids: string[]选中变化时触发,供 v-model:selected-ids 双向同步
confirmids: string[]点击「确认」按钮时触发,负载为当前选中 id 列表(不自动关闭,由业务侧决定后续)
cancel—点击「取消」按钮或右上角关闭时触发(随后自动关闭弹窗)
max-exceedmax: number左栏选择超过 maxSelected 时触发

Slots ​

插槽名说明
body—
panel-top—
notice—
footer—

API ​

Props ​

属性类型默认值说明
showboolean—是否显示弹窗(v-model:show 受控)
titlestring''弹窗标题,为空时不渲染标题文本(showClose 为 true 时 header 行仍保留)
titleAlign'left' | 'center''left'标题对齐方式:left(默认,设计稿形态)/ center
showClosebooleantrue是否显示右上角关闭按钮,默认 true
showHeaderDividerboolean—是否显示 header 下分割线;不传时跟随全局 theme.headerBorder 开关(默认关闭),显式传入优先
widthnumber420弹窗宽度(px),默认 420;桌面端实际宽度 = min(width, 视口宽 × --uikit-modal-width-ratio),
随屏幕宽度按比例自适应(ratio 默认 0.5,宿主可覆写该 CSS 变量调整占屏比),最小不小于 280px
heightnumber0弹窗高度(px),不传时由内容撑开;受 90vh 上限约束
contentAlign'left' | 'center'—正文对齐方式:left / center(Text-Icon 居中变体);不传时按 type 自动判定——
通知类(type 非 default,带语义图标)居中,其余左对齐;显式传入优先
iconstring''正文图标名(Text-Icon 模式),格式 "category/icon-name",如 "circle/bang";也可用 #icon 插槽接管。
不传时按 type 内置语义图标(参考 Toast:danger/warning/info → 感叹号圆,success → 对勾圆)
showFooterbooleantrue是否显示底部按钮区,默认 true;列表/搜索类弹窗可置 false 并用默认插槽自绘内容
footerAlign'right' | 'stretch''right'底部按钮布局:right(默认,右对齐 pill 按钮)/ stretch(等宽铺满,兼容旧形态);
移动端忽略该 prop,强制 stretch 等宽铺满
showCancelbooleantrue是否显示「取消」按钮,默认 true
cancelTextstringt('button.cancel', '取消')「取消」按钮文案,默认按当前语言显示「取消」
confirmTextstringt('button.confirm', '确认')「确认」按钮文案,默认按当前语言显示「确认」
closeOnClickOverlaybooleanfalse点击遮罩是否关闭弹窗,默认 false(需通过按钮或 ESC 关闭)
type'default' | 'danger' | 'warning' | 'info' | 'success''default'弹窗类型:default(默认)/ danger(危险操作,确认按钮变红色)/ warning / info / success;
非 default 时正文自动带对应语义图标(icon prop / #icon 插槽可覆盖);
图标默认脱色(主文字色),语义着色需显式开启 semanticIconColor;
移动端回落差异:default 表单类回落 bottom sheet,语义类(短文案确认/通知)保持居中
semanticIconColorbooleanfalse语义图标是否按类型着色(warning 橙 / danger 红 等),默认 false 脱色展示
confirmDisabledbooleanfalse确认按钮禁用态(如未选择成员时禁止提交),默认 false
confirmLoadingbooleanfalse确认按钮加载态(异步提交期间),默认 false
confirmAutoClosebooleantrue点击确认后是否自动关闭弹窗,默认 true;异步表单类弹窗置 false,由业务侧在成功后自行关闭
bodyFlushbooleanfalse正文是否贴边(去除 body 内边距并撑满高度),列表/搜索类弹窗使用,默认 false
mobileFullscreenbooleanfalse移动端全高档位(opt-in):bottom sheet 形态下弹窗拉满视口高度(100dvh + safe-top),
突破默认 80dvh 上限,用于选人等重交互场景;仅移动端 bottom sheet 生效,桌面端无影响

Events ​

事件名参数说明
update:showvalue: boolean显示状态变化时触发(确认/取消/遮罩或 ESC 关闭),负载为最新显示状态,供 v-model:show 双向同步
confirm—点击「确认」按钮时触发(随后自动关闭弹窗)
cancel—点击「取消」按钮、右上角关闭、遮罩或按 ESC 关闭时触发(随后自动关闭弹窗)

Slots ​

插槽名说明
title—
icon—
footer—