mdm-im-v3

基于 OpenIM SDK 的 Vue 3 即时通讯组件库，提供会话列表、单聊/群聊消息、文件收发、入群审批等功能。同时支持 PC 端（Element-Plus）和 H5 移动端（Vant 4），打包后通过 npm 分发，由同一包提供双端组件。

技术栈

• Node 18+（推荐 Node 20+ LTS）
• Vue 3 + Pinia + vue-router
• OpenIM client-sdk（@openim/[email protected]） 技术文档
• PC 端：Element-Plus / H5 端：Vant 4

npm 包目录结构

安装 mdm-im-v3 后，node_modules 中的包目录如下：

node_modules/mdm-im-v3/
├── dist/                            # PC 端构建产物
│   ├── index.es.js                  #   入口（导出 mdmImV3 组件）
│   ├── core.es.js                   #   入口（导出 useMessage + useChatStore）
│   ├── style/index.css              #   样式文件
│   ├── index-*.js                   #   内部代码分割文件（Vite 自动分包）
│   ├── wangeditor-*.js              #   富文本编辑器分包
│   ├── vue-office-*.js              #   文档预览分包
│   └── assets/                      #   图片/字体等资源文件
├── dist-h5/                         # H5 端构建产物
│   ├── index.es.js                  #   入口（导出 mdmImV3H5 组件，内部自带路由）
│   ├── style/index-h5.css           #   样式文件
│   ├── *H5-*.js                     #   按路由拆分的页面代码
│   └── assets/                      #   图片/字体等资源文件
├── package.json                     # package exports 定义导入路径映射
└── README.md

导入路径映射

package.json 的 exports 字段定义了以下导入路径，消费方使用路径名导入即可，无需关心内部目录结构：

核心原则： mdm-im-v3/core 在两端通用，PC 端额外导入 mdm-im-v3（组件）和 mdm-im-v3/style/index.css（样式），H5 端额外导入 mdm-im-v3/h5（组件）和 mdm-im-v3/style/index-h5.css（样式）。

图标字体已内置： 两个样式文件都包含 @font-face 与全部 .mdm-icon-* 类（字体文件随包输出到 dist/assets/extracted/、dist-h5/assets/extracted/），消费方无需再单独引入 iconfont.css，也不依赖宿主是否已有同名图标字体。

安装

pnpm i mdm-im-v3@latest -S

安装 peer 依赖

PC 端 需安装以下依赖（选择你自己的包管理器）：

pnpm i vue@^3.5 element-plus@^2.9 @element-plus/icons-vue@^2.3 pinia@^3.0 pinia-plugin-persist@^1.0 vue-router@^4.5 axios@^1.8 sass@^1.86 -S

H5 端 同样需要安装 Vue 等基础依赖，但无需安装 element-plus，改为安装 Vant：

# H5 端需要的基础依赖（与 PC 端共享 pinia、vue-router、sass 等）
pnpm i vue@^3.5 pinia@^3.0 pinia-plugin-persist@^1.0 vue-router@^4.5 axios@^1.8 sass@^1.86 -S

# H5 端额外需要 Vant
pnpm i vant@^4.10 -S

H5 端不需要安装 element-plus 和 @element-plus/icons-vue。

PC 端使用

方式一：autoLogin（推荐）

通过组件暴露的 autoLogin 方法一键完成初始化、登录和会话加载：

<template>
  <mdm-im-v3 ref="chatRef" theme="dark" />
</template>

<script setup>
import { ref } from 'vue'
import 'mdm-im-v3/style/index.css'
import { mdmImV3 } from 'mdm-im-v3'

const chatRef = ref()

const handleLogin = () => {
  chatRef.value.autoLogin({
    loginCode: 'your-account',   // 用户登录账号，必填
    userName: 'your-name',       // 用户名
    imToken: 'your-im-token',    // OpenIM 用户令牌，必填
    satoken: 'your-system-token',// 系统 token（上传文件等接口使用）
    apiUrl: 'https://your-api-url:8443',   // IM api 地址，必填
    platformID: 5,           // IM 平台标识，可选，5-网页端
  })
}
</script>

autoLogin 内部自动完成：store 写入用户信息 → 初始化 IM SDK → 登录 → 轮询登录状态 → 状态变为已登录后拉取会话列表。

方式二：手动控制登录流程（分步加载）

适用于先登录 IM 获取未读数 → 再切换到 IM 页面展示内容的场景：

完整说明与可运行示例见 获取即时消息组件mdm-im-v3的未读消息数量的调用方式.md。

1. 入口处调用 useMessage(config) 初始化 IM，获取未读数量
2. 用户切换到 IM 菜单时再渲染 <mdm-im-v3> 组件
3. 组件自动读取 store 中的已登录状态和 window.imInstance，无需重复初始化

// ========== 步骤1：应用入口处登录 IM ==========
import { watch } from 'vue'
import { useMessage } from 'mdm-im-v3/core'

const { initIMSDK, getUnReadMessageCount, loginStatus, messageStore } = useMessage({
  userID: 'your-account',        // 用户 ID，必填
  nickname: 'your-name',          // 用户昵称
  faceURL: '',                    // 用户头像
  imToken: 'your-im-token',       // OpenIM 用户令牌，必填
  satoken: 'your-system-token',   // 系统 token
  apiUrl: 'https://your-api-url:8443',  // IM API 地址，必填
  wsUrl: 'wss://your-ws-url:8443',      // IM WebSocket 地址
  tenantID: '',                   // 租户 ID
  platformID: 5,                  // 平台标识，5-网页端
})

// 初始化并登录
await initIMSDK()

// 监控 IM 登录状态，登录成功后获取未读数
watch(loginStatus, status => {
  if (status === 3) {
    getUnReadMessageCount(true)
  }
})

<!-- ========== 步骤2：切换菜单后渲染 PC 组件 ========== -->
<template>
  <mdm-im-v3 ref="chatRef" theme="dark" />
</template>

<script setup>
import { ref } from 'vue'
import 'mdm-im-v3/style/index.css'
import { mdmImV3 } from 'mdm-im-v3'
// 组件会自动读取 store 和 window.imInstance，无需再次初始化

const chatRef = ref()
</script>

原理： useMessage() 内部自动将配置存入 Pinia store（useChatStore），initIMSDK() 创建的 IM 实例挂载到 window.imInstance。 组件挂载时检测到 loginStatus === 3（已登录），直接复用已有的 IM 实例和会话数据，无需二次登录。

H5 移动端使用

本库同时提供 H5 移动端组件，基于 Vant 4 UI 库构建，采用独立全屏页面路由（区别于 PC 端左右分栏布局）。H5 端从 mdm-im-v3/h5 路径导入组件，与 PC 端一样，只需要一个入口组件，无需暴露路由。

前置准备

H5 端需要安装 Vant 并在入口文件中注册：

pnpm i vant@^4.10 -S

入口文件（main.js）

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import PiniaPersist from 'pinia-plugin-persist'
import Vant from 'vant'
import 'vant/lib/index.css'
import 'mdm-im-v3/style/index-h5.css'
import { mdmImV3H5 } from 'mdm-im-v3/h5'

import App from './App.vue'

const app = createApp(App)
const pinia = createPinia()
pinia.use(PiniaPersist)

app.use(pinia)
app.use(Vant)
app.mount('#app')

注意： H5 路由使用 createWebHashHistory，共有 11 个页面路径，全部内聚在 mdmImV3H5 组件内部，消费方无需注册路由，只需在模板中放置 <mdm-im-v3-h5> 标签即可。

根组件（App.vue）

<template>
  <mdm-im-v3-h5 ref="h5Ref" theme="light" />
</template>

<script setup>
import { ref } from 'vue'
import { mdmImV3H5 } from 'mdm-im-v3/h5'

const h5Ref = ref()
</script>

方式一：autoLogin（推荐）

通过组件暴露的 autoLogin 方法一键完成初始化、登录和会话加载，与 PC 端完全一致：

<template>
  <mdm-im-v3-h5 ref="h5Ref" theme="light" />
</template>

<script setup>
import { ref } from 'vue'
import { mdmImV3H5 } from 'mdm-im-v3/h5'

const h5Ref = ref()

const handleLogin = () => {
  h5Ref.value.autoLogin({
    loginCode: 'your-account',   // 用户登录账号，必填
    userName: 'your-name',       // 用户名
    imToken: 'your-im-token',    // OpenIM 用户令牌，必填
    satoken: 'your-system-token',// 系统 token（上传文件等接口使用）
    apiUrl: 'https://your-api-url:8443',   // IM api 地址，必填
    platformID: 5,               // IM 平台标识，可选，5-网页端
  })
}
</script>

autoLogin 内部自动完成：store 写入用户信息 → 初始化 IM SDK → 登录 → 轮询登录状态 → 状态变为已登录后自动跳转到会话列表页。

方式二：分步加载（手动控制登录流程）

适用于先登录 IM 获取未读数 → 再切换到 IM 页面展示内容的场景，与 PC 端流程一致：

// ========== 步骤1：应用入口处登录 IM ==========
import { watch } from 'vue'
import { useMessage } from 'mdm-im-v3/core'

const { initIMSDK, getUnReadMessageCount, loginStatus } = useMessage({
  userID: 'your-account',
  nickname: 'your-name',
  imToken: 'your-im-token',
  satoken: 'your-system-token',
  apiUrl: 'https://your-api-url:8443',
  wsUrl: 'wss://your-ws-url:8443',
  platformID: 5,
})

// 初始化并登录
await initIMSDK()

// 监控 IM 登录状态，登录成功后获取未读数
watch(loginStatus, status => {
  if (status === 3) {
    getUnReadMessageCount(true)
  }
})

<!-- ========== 步骤2：切换菜单后渲染 H5 组件 ========== -->
<template>
  <mdm-im-v3-h5 ref="h5Ref" theme="light" />
</template>

<script setup>
import { ref } from 'vue'
import { mdmImV3H5 } from 'mdm-im-v3/h5'
// 组件会自动读取 store 和 window.imInstance，无需再次初始化

const h5Ref = ref()
</script>

原理： useMessage() 内部自动将配置存入 Pinia store（useChatStore），initIMSDK() 创建的 IM 实例挂载到 window.imInstance。<mdm-im-v3-h5> 组件挂载时检测到 loginStatus === 3（已登录），直接复用已有的 IM 实例和会话数据，无需二次登录。

H5 内置路由表

以下路由全部内聚在 mdmImV3H5 组件内部，消费方无需关心：

H5 组件 Props

H5 组件暴露的方法

通过 ref 调用 <mdm-im-v3-h5>：

// autoLogin — 一键登录
h5Ref.value.autoLogin({
  loginCode: string    // 用户登录账号，必填
  userName?: string    // 用户名
  imToken: string      // OpenIM 用户令牌，必填
  satoken?: string     // 系统 token
  apiUrl: string       // IM API 地址，必填
  platformID?: number  // IM 平台标识（默认 5-网页端）
})

// checkLogin() — 检测 store 中已有登录状态后跳转到会话列表页
h5Ref.value.checkLogin()

H5 组件同样支持 unread-change 事件（参数与 PC 端一致，见 组件 Events），宿主可通过 @unread-change 监听未读消息数变化。

H5 端与 PC 端差异

组件 Props

baseConfig 字段

组件 Events

PC 与 H5 组件支持相同的事件：

unread-change（未读消息数）

组件在以下时机向上抛出该事件：

事件载荷：

{
  count: number          // 当前未读消息总数
  reason: 'init' | 'receive' | 'update'
  time: number           // 触发时间戳（毫秒）
  conversationID?: string // 仅 reason='receive'：最新消息所属会话 ID
}

PC / H5 用法一致：

<template>
  <mdm-im-v3 ref="chatRef" @unread-change="handleUnreadChange" />
  <!-- H5：<mdm-im-v3-h5 ref="chatRef" @unread-change="handleUnreadChange" /> -->
</template>

<script setup>
const handleUnreadChange = ({ count, reason, conversationID }) => {
  // 同步宿主菜单/标签页的红点数量
  badgeRef.value = count
  console.log('[IM] 未读数：', count, reason, conversationID)
}
</script>

未读总数同时保存在 store 的 unReadCount 中，可通过 useChatStore().getUnReadCount 读取；unread-change 事件适用于不便订阅 store 的宿主（如非 Vue 渲染的菜单/角标）。

组件暴露的方法

通过 ref 调用：

autoLogin(config)

一键登录，参数对象：

{
  loginCode: string   // 用户登录账号，必填
  userName?: string   // 用户名
  imToken: string     // OpenIM 用户令牌，必填
  satoken?: string    // 系统 token
  apiUrl: string      // IM API 地址，必填
  platformID?: number // IM 平台
}

无返回值。方法内部完成 store 写入、SDK 初始化、登录、轮询状态直到会话列表加载完毕。

checkLogin()

轮询检测登录状态：当 store 中 loginStatus === 3（已登录）且 window.imInstance 存在时，自动调用内部 afterLogged() 拉取会话列表。配合方式二（手动 useMessage 登录）使用；方式一（autoLogin）内部已自动调用。

注：afterLogged() 为组件内部方法，未通过 defineExpose 暴露，外部请调用 checkLogin() 触发会话加载。

sendCheckedText({ list, isReply, atUserList })

发送经过敏感词校验后的文本。与 send-chat-text 事件配合使用：

const handleSendChatText = ({ list, isReply, atUserList }) => {
  const filteredList = keywordFilter(list)
  chatRef.value.sendCheckedText({ list: filteredList, isReply, atUserList })
}

inviteUser(groupID, userIDs)

邀请用户进群：

chatRef.value.inviteUser('group-id-xxx', ['user1', 'user2'])
// 返回 Promise<boolean>

useMessage API

从 mdm-im-v3/core 导入，PC / H5 两端通用，用于手动管理 IM 生命周期：

import { useMessage, useChatStore } from 'mdm-im-v3/core'

const { initIMSDK, clearInstance, getUnReadMessageCount, setConversationMsgAsRead, mittBus } = useMessage({
  userID: 'your-account',
  nickname: 'your-name',
  faceURL: '',
  imToken: 'your-im-token',
  satoken: 'your-system-token',
  apiUrl: 'https://your-api-url:8443',
  wsUrl: 'wss://your-ws-url:8443',
  tenantID: '',
  platformID: 5,
})

参数

useMessage(config?) 接收一个可选的配置对象，所有字段均为可选：

传入配置后，useMessage 内部立刻调用 chatStore.setUserInfo() 将参数保存到 Pinia store。也可以不传参数，后续在调用 initIMSDK() 前手动写入 store。

返回值

ChatStore

从 mdm-im-v3/core 导入 useChatStore 后调用获取，是 Pinia store（id: 'chatMessage'），已开启 localStorage 持久化，持久化字段包括：userID、nickname、faceURL、platformID、apiUrl、wsUrl、tenantID（imToken 和 satoken 仅保存在 Pinia 内存中，不持久化到本地存储）。

import { useChatStore } from 'mdm-im-v3/core'
const chatStore = useChatStore()

常用 State

常用 Getters

常用 Actions

MittBus 事件

通过 useMessage().mittBus 获取，可监听以下 IM 自定义事件：

监听示例：

const { mittBus } = useMessage()
mittBus.on('LOGOUT_NOTICE', () => {
  router.push('/login')
})

阅后即焚（Burn After Reading）

单聊会话支持「阅后即焚」：谁开启，谁发送的消息才会在被对方阅读后倒计时并销毁；对方未开启时，其发送的消息不受影响。

使用入口

• PC：聊天窗口右上角「设置」抽屉 → 单聊会话 → 「阅后即焚」开关 + 「阅后即焚时间」；
• H5：聊天设置页（/chat-settings）→ 单聊会话 → 「阅后即焚」开关 + 时间选择。

群聊不提供该入口（OpenIM 的 isPrivateChat 语义按私密会话设计，本期仅支持单聊）。

规则

服务端能力与限制

• 设置依赖服务端对会话 ex 的持久化（本项目已用于隐藏/标记未读，属于既有能力）；
• 阅后即焚的「到期真删」属于 OpenIM 服务端能力，落地前需确认当前部署版本支持；即使服务端不支持，组件仍会按本地倒计时把消息从界面与缓存中移除（弱一致）；
• 服务端会话上的 isPrivateChat / burnDuration 仍会随设置同步（用于 1701 通知与 SDK 私密快照），但组件不再据此决定是否焚毁。

相关字段：会话 ex.burn（设置，按用户）；消息 ex.burnBySender / burnDuration / burnFromUserID / burnToUserID（发送方快照，组件焚毁依据）；attachedInfoElem 仅作兼容展示。

语音消息（Voice Message）

支持在 PC / H5 端录制并发送 OpenIM 语音消息（contentType = 103，soundElem），消息列表复用已有语音气泡（时长 + 声波 + 播放）。

使用入口

• H5：输入区左侧「语音/键盘」切换按钮 → 按住「按住 说话」开始录音，松开发送；上滑超过 80px 松开取消；
• PC：编辑器工具栏麦克风图标 → 录音弹窗 → 点击麦克风开始，点击「停止并发送」结束并发送；
• 另：PC 选择/拖拽音频文件、H5 选择音频文件，都会按语音消息发送（不再显示成文件卡片）。

录音与发送规格

依赖与权限

• 录音依赖 js-audio-recorder（已加入 dependencies），产物为 WAV，iOS / 微信浏览器 / Electron 均可播放；
• 浏览器录音要求 HTTPS 或 localhost，首次使用需授权麦克风；拒绝授权、无麦克风、浏览器不支持时均有 Toast 提示；
• PC Electron 需在系统层允许麦克风权限。

相关字段：soundElem.duration（秒，必填）、sourceUrl / soundPath（播放地址，组件会补 baseUrl 并把 /api/v1/common/reviewFile/ 重写为 /api/v1/auth/reviewFile/）、dataSize、soundType（如 wav）。

主题

支持深色（dark）和浅色（light）两套主题，通过 CSS 变量驱动：

<mdm-im-v3 theme="dark" />
<mdm-im-v3 theme="light" />

主题 CSS 变量定义在 chat-dark-theme / chat-light-theme 类名下，可通过覆盖 CSS 变量进行自定义。