VersaChat (Vue Versatile IM)

A lightweight, zero-dependency, highly customizable Vue 3 IM UI component library. Supports PC dual-panel mode and Service single-panel mode.

轻量级、零依赖、高度可定制的 Vue3 IM UI 组件库。支持 PC 双栏模式与 Service 单栏客服模式。

Installation | 安装

npm install vue-versatile-im

Usage | 使用

import { VersatileIM } from "vue-versatile-im";
import "vue-versatile-im/style.css";

<VersatileIM
  :list="sessions"
  :messages="messages"
  :active-session-id="activeId"
  :config="config"
  :theme="theme"
  :draft="draftBySession[activeId] ?? ''"
  @update:draft="(v) => (draftBySession[activeId] = v)"
  v-model:replying-to="replyingTo"
  @send="onSend"
  @pull-history="onPullHistory"
  @menu-click="onMenuClick"
  @quote-locate="onQuoteLocate"
  @input-files="onInputFiles"
  @select-session="onSelectSession"
>
  <template #header-actions>
    <button @click="startVoice">📞</button>
    <button @click="startVideo">📹</button>
  </template>
</VersatileIM>

Props

| Prop | Type | Default | Description | 说明 | |------|------|---------|--------------|------| | list | VIMSessionItem[] | [] | Session/contact list | 会话/联系人列表 | | messages | VIMMessage[] | required | Current session messages（随 activeSessionId 切换） | 当前会话消息 | | activeSessionId | string | "" | Active session ID | 当前选中会话 ID | | typing | boolean | false | Show typing indicator (text from config.typingText) | 对方输入中 | | theme | VIMTheme | {} | Theme overrides | 主题覆盖 | | config | VIMConfig | {} | mode, showAvatar, sortSessionByLatest, sidebarMenuItems, sidebarMenuBottomItems, inputPlaceholder, etc. | 配置项 | | messageTypeMap | VIMMessageTypeMap | {} | Custom message type components | 自定义消息类型映射 | | draft | string | - | Input draft (use v-model:draft for per-session draft) | 输入草稿，可配合 v-model:draft 实现按会话保存 | | replyingTo | VIMMessage \| null | - | Reply target (use v-model:replying-to) | 引用回复目标消息 |

Events

| Event | Payload | Description | 说明 | |-------|---------|--------------|------| | send | VIMSendPayload | Send text message (payload: { text, quote? }) | 发送文本，支持引用回复 | | pull-history | - | Load history on scroll top | 加载历史 | | click-avatar | message | Avatar clicked | 点击头像 | | menu-click | { action, message } | Context menu: copy, quote, forward, recall, retry, delete | 右键菜单 | | quote-locate | { quotedId, message? } | Quote bar clicked | 引用定位 | | input-files | { files, source } | Paste or drop files | 粘贴/拖拽文件 | | select-session | id: string | Switch session | 切换会话 | | click-image | { url, message } | Image message clicked | 点击图片 | | session-menu-click | { action, session } | Session menu: pin, mute, delete (default keys) | 好友列表菜单 | | click-header | session | Chat header clicked | 点击头部好友名 |

Slots

| Slot | Scope | Description | 说明 | |------|-------|--------------|------| | header | - | Chat area title | 聊天区域标题 | | header-actions | { session } | Right-side buttons (video/voice, etc.) | 头部右侧操作按钮（视频、语音等） | | message-item | { message } | Custom message render | 自定义消息渲染 | | input-tools | - | Toolbar above input | 输入框上方工具栏 | | empty | - | Empty state when no messages | 无消息时占位 | | header-dialog | { session } | Dialog when clicking header | 点击头部弹窗内容 | | main-pane | { activeSidebarKey } | Right pane when sidebar in mainPaneKeys (e.g. "me") | 选中「我」等菜单时右侧自定义内容 |

会话切换 | Session Switching

点击好友列表时，父组件需根据 activeSessionId 切换 messages：

const messagesBySession = ref<Record<string, VIMMessage[]>>({});
const currentMessages = computed(() => messagesBySession.value[activeSessionId.value] ?? []);

<VersatileIM :messages="currentMessages" :active-session-id="activeSessionId" @select-session="onSelectSession />

消息发送失败 | Failed Messages

• 消息的 failed: true 时显示失败状态
• 右键菜单出现「重新发送」，@menu-click 收到 action: "retry" 时由业务侧重发

配置项 | Config

| Field | Type | Description | 说明 | |-------|------|--------------|------| | sidebarMenuItems | VIMSidebarMenuItem[] | 顶部菜单（最近、联系人、我） | 左侧边栏顶部菜单 | | sidebarMenuBottomItems | VIMSidebarMenuItem[] | 底部菜单（设置等） | 左侧边栏底部菜单 | | mainPaneKeys | string[] | 如 ["me"]，选中时显示 main-pane 插槽 | 使用右侧自定义内容的菜单 | | inputPlaceholder | string | 输入框 placeholder | 输入框占位文案 | | typingText | string | Custom typing indicator text (when typing is true) | 「对方正在输入」提示文案 |

VIMMessage / VIMSessionItem

| Field | Type | Description | 说明 | |-------|------|-------------|------| | deliveryStatus | 'sent' \| 'delivered' \| 'read' | Self messages only; shown under bubble when send succeeded | 己方消息送达/已读（业务层在发送成功后更新） | | pinned | boolean | Session pinned to top (still sorted by lastMessageTime within pinned group) | 会话置顶，列表最前 |

Theme Variables (vars.css)

Override in :root to customize:

:root {
  --vim-primary-color: #07c160;
  --vim-bg-color: #f5f5f5;
  --vim-bubble-left-bg: #ffffff;
  --vim-bubble-right-bg: #95ec69;
  --vim-font-size: 14px;
  --vim-border-radius: 4px;
  --vim-delivery-sent: #8b8b8b;
  --vim-delivery-read: #34b7f1;
}

Development | 开发

npm run dev          # Dev preview (playground) | 开发预览
npm run docs:dev     # Docs (VitePress) | 文档
npm run docs:build   # Build docs | 构建文档
npm run build        # Build library | 构建库
npm run test         # Unit tests | 单元测试

Documentation | 文档

Run npm run docs:dev to start VitePress docs at http://localhost:5173.

运行 npm run docs:dev 启动 VitePress 文档。

NPM publish | 发布

0.x：API 可能调整，建议在业务中锁定 minor 版本。

发布前请：

1. 将 package.json 中的 repository / homepage / bugs 里的 versa-chat 换成真实 Git 仓库，并同步修改 CHANGELOG.md 底部链接。
2. 执行 npm run build && npm test，再用 npm pack --dry-run 检查打包包内容。
3. 登录 NPM：npm login，然后 npm publish（非 scope 包默认 public）。

样式也可写为 import "vue-versatile-im/dist/style.css"（与 style.css 子路径等价）。

Exports

• 主入口：import { VersatileIM, VimDialog, sortSessionItems, … } from "vue-versatile-im"
• 样式：import "vue-versatile-im/style.css"