Vue UIKit 聊天组件

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

当前版本 1.0.0-alpha，通过 公共 npm 的 alpha 标签分发，同时提供源码、本地 tgz 构建与开发示例。支持 Vue 3.3+ peer 范围，本轮使用 Vue 3.5.43 验收。基础 IM 界面范围与 React UIKit 对齐，音视频通话、聊天室、RTC 频道和复杂转发等界面不在本版。

构建与安装

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

pnpm add vue@^3.3 @deeprespond/im-web@1.0.0-alpha @deeprespond/im-web-vue@1.0.0-alpha @deeprespond/im-web-vue-uikit@1.0.0-alpha

建议固定版本，也可使用 @deeprespond/im-web-vue-uikit@alpha 跟随预发布标签。

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

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 绑定和本地组件包：

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

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

最小接入

<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>

宿主统一管理 client。UIKit 卸载不会销毁或退出宿主客户端，不修改宿主 app 已安装的 Vue 绑定插件；Provider 已为内部组件提供绑定上下文，无需重复安装 createDRPlugin。更换 client 或登录会话会重建账号内界面，避免残留旧账号消息、草稿和通知。

LoginPanel 默认仅提供 Ticket 登录；密码和注册需通过 allowPassword / allowRegistration 显式启用。正式业务从自己的服务端签发 Ticket，浏览器不要放 App Secret。

SSR / Nuxt 应在客户端生命周期创建浏览器 SDK client，可使用 ClientOnly，不要在服务端请求之间共享实例。包导入与 Node SSR 契约有独立验证，Nuxt 宿主本轮未实测。

可组合组件

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

不传 conversationKey 时 ChatApp 内部管理选择，传入 null 表示受控空选择。草稿会话转正式会话会向宿主通知新 key。输入区本身不调用 SDK 发送方法，由宿主消费 @send / @file(file, kind) 等事件。

主题、能力与消息定制

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) 可接入业务监控。

示例与验证

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

示例端口 5199，使用 VITE_IM_APPKEY / VITE_IM_APIURL，或通过 URLSearchParams 编码的 appKey / apiUrl 参数。可复用本地一致性测试后端 18480 / 18490。开发版本直接加载本工作树的组件源码。

验收产物位于仓库 Agent测试/VueUIKit/20261022/：先独立冒烟失败夹具，再执行桌面与窄视口真实双用户流程；断言通过后统一截图，并逐张记录实际视觉检查。测试报告由结构化产物自动生成，失败和未执行项保留，不计为通过。

当前未执行的浏览器、其他 Vue 版本、真实录音成功、大规模消息性能等限制，以测试报告为准；构建通过不等于这些宿主或场景已经验收。组件 README 包含完整参数、启动和测试脚本。