深应智联

简体中文

繁體中文
English

简体中文

繁體中文
English

外观

控制台

Vue UIKit 聊天组件 ​

Vue UIKit 是 @deeprespond/im-web 和 @deeprespond/im-web-vue 之上的独立 Vue 3 组件库，可在业务页面组合会话、聊天窗口、好友与群组，也可直接嵌入完整 ChatApp。运行时不依赖 React；Vue 绑定负责订阅和生命周期，UIKit 负责交互和样式。

当前版本为 1.1.1，已发布到公共 npm，也可以从源码构建本地 tgz 包，仓库中另有开发示例。支持 Vue 3.3 及以上（已用 Vue 3.5.43 实测）。界面范围与 React UIKit 相同，不包含音视频通话、聊天室、独立频道和复杂转发。

构建与安装 ​

Node.js >= 20.19，推荐 Node 22、pnpm 9。在业务项目直接安装（宿主提供 Vue 3）：

bash
pnpm add vue@^3.3 @deeprespond/im-web@1.1.1 @deeprespond/im-web-vue@1.1.1 @deeprespond/im-web-vue-uikit@1.1.1

建议固定版本。

需要本地构建时，在仓库根目录执行：

bash
pnpm --dir sdk/web install
pnpm --dir sdk/web build
pnpm --dir sdk/web-vue install
pnpm --dir sdk/web-vue build
pnpm --dir sdk/web-vue-uikit install
pnpm --dir sdk/web-vue-uikit pack --pack-destination /tmp/vue-uikit-package

在独立业务项目安装核心、Vue 绑定和本地组件包：

bash
pnpm add vue@^3.3 @deeprespond/im-web@1.1.1 @deeprespond/im-web-vue@1.1.1
pnpm add /tmp/vue-uikit-package/deeprespond-im-web-vue-uikit-1.1.1.tgz

组件包已编译为 ESM，包含 SFC 类型声明，不要求业务复制示例源码。必须单独导入样式。

最小接入 ​

vue
<script setup lang="ts">
import { onBeforeUnmount } from 'vue';
import { createDRClient } from '@deeprespond/im-web';
import { UIKitProvider, ChatApp } from '@deeprespond/im-web-vue-uikit';
import '@deeprespond/im-web-vue-uikit/styles.css';

const client = createDRClient({
  appKey: 'your-org#your-app',
  apiUrl: 'https://your-im-api.example.com',
  autoMarkRead: true,
});
// 在业务登录流程中取得短期 Ticket，再调用并捕获失败：
// await client.auth.loginWithTicket({ ticket });
onBeforeUnmount(() => { void client.destroy(); });
</script>

<template>
  <section style="height: 640px">
    <UIKitProvider :client="client" theme="light">
      <ChatApp @logout="client.auth.logout()" />
    </UIKitProvider>
  </section>
</template>
  • 客户端由你的应用创建和管理。UIKit 卸载时不会退出登录或销毁客户端。
  • UIKitProvider 已为内部组件提供 Vue 绑定，不需要再安装 createDRPlugin；它也不会改动你的应用已经安装的 Vue 绑定插件。
  • 换了客户端或登录了另一个用户时，界面整体重建，不会残留上一个用户的消息、草稿和通知。

LoginPanel 默认只提供 Ticket 登录；传 allowPassword、allowRegistration 才显示密码登录和注册。正式项目请由自己的服务端签发 Ticket，不要把 App Secret 放进浏览器。

Nuxt 等服务端渲染的应用：在浏览器端的生命周期中创建客户端（可以包在 <ClientOnly> 中），不要在服务端的多个请求之间共用一个客户端。在 Node 中导入组件包已经过测试，但还没有在 Nuxt 项目中实测。

可组合组件 ​

组件用途 / 事件
UIKitProvider / useUIKit实例级 client、主题、功能开关、中文错误与通知
ChatApp整体界面；v-model:conversation-key、@conversation-change、@logout；header / empty / signed-out 插槽
ChatWindowconversationKey、可选 conversation、@close
ConversationListcurrentKey、@open(key, conversation)
ContactList好友、申请、备注、黑名单；@open-peer(username)
GroupList / GroupMembers建群、成员、角色、邀请、移出、退出与解散；@open-group / @open-peer / @close
MessageBubble受控展示；message、conversation、renderBody、@resend
MessageComposerv-model、@send、附件与语音事件；录音、引用、禁用状态
LoginPanel / ConnectionBanner登录和连接状态
Avatar / Modal / Spinner基础 UI；Modal 管理焦点及嵌套 Escape，提供默认 / footer 插槽

不传 conversationKey 时，ChatApp 自己管理当前选中的会话；传入后由你控制，null 表示没有选中。草稿会话变为正式会话时会通知新的会话键。输入区（MessageComposer）本身不发送消息：由你处理 @send、@file(file, kind) 等事件并调用 SDK。

主题、能力与消息定制 ​

  • 主题：Provider 支持 theme="dark"，主题通过组件内的 CSS 变量设置，不会修改页面的 html、body、localStorage 或主题设置。同一页面的多个 Provider 互不影响，但不要嵌套 Provider。容器要有明确的高度，宽度小于 760px 时自动切换为单栏并提供返回按钮。
  • 功能开关：features 可以关闭 images、files、voice。readOnly 和 readOnlyReason 禁用输入、附件和录音；它只是界面上的限制，不代替服务端的权限检查，也不会禁止好友或群组的其他操作。群主和普通成员看到的管理入口不同；是否显示表情回应按应用策略决定。
  • 自定义消息：renderMessage(message) 返回 Vue VNode 来定制消息内容，返回 undefined 时使用内置的显示。单独使用 MessageBubble 时可以传 renderBody。文本默认经过 Vue 转义，只识别 HTTP(S) 链接；图片、语音和文件通过 SDK 带鉴权下载。
  • 错误：formatError 自定义错误文案，onError(error, action) 可以接入你的监控。

示例与验证 ​

bash
pnpm --dir sdk/web-vue-uikit/demo install
pnpm --dir sdk/web-vue-uikit/demo dev

示例运行在 http://127.0.0.1:5199。用环境变量 VITE_IM_APPKEY、VITE_IM_APIURL 配置，或在地址中带上 URL 编码的 appKey、apiUrl 参数。开发时示例直接加载仓库中的组件源码。

已测试的环境：Vue 3.5 + 浏览器，连接真实的 IM 服务端，覆盖两个用户互发消息、发送失败等场景，桌面和窄屏都截图检查过。尚未实测：其他浏览器、其他 Vue 版本、真实录音、大量消息时的性能，上线前请在你的目标环境中验证。详细结果见仓库中的测试报告目录 Agent测试/VueUIKit/20261022/；完整的参数、启动和测试脚本见组件的 README。