React UIKit 聊天组件

React UIKit 提供可直接嵌入业务项目的会话、聊天、好友和群组界面。它与 Web SDK 的关系是：

@deeprespond/im-web               协议、连接、消息和缓存
          ↓
@deeprespond/im-web-react         React 订阅和生命周期
          ↓
@deeprespond/im-web-react-uikit   可组合的聊天界面
          ↓
业务项目 / UIKit 宿主示例

当前版本为 1.0.0-alpha，已通过 公共 npm 的 alpha 标签分发，并提供仓库源码、本地安装包构建和运行示例。React / React DOM 的 peer 范围为 18 或 19，本轮浏览器运行验收使用 React 18；Vue 版见 Vue UIKit（已通过公共 npm 分发 1.0.0-alpha，标签为 alpha）。

从 npm 安装

在自己的 React 项目安装兼容的核心、绑定与 UIKit：

pnpm add @deeprespond/im-web@1.0.0-alpha @deeprespond/im-web-react@1.0.0-alpha @deeprespond/im-web-react-uikit@1.0.0-alpha

也可以安装 @deeprespond/im-web-react-uikit@alpha 跟随预发布标签；业务项目建议固定具体版本。宿主项目自行提供 React 和 React DOM。UIKit 不依赖示例源码，所有界面组件从包根导出，必须单独导入样式。

从源码构建与离线安装

仅在修改组件源码或准备离线包时需要克隆仓库。Node.js >= 20.19，推荐 Node 22、pnpm 9，在仓库根目录执行：

pnpm --dir sdk/web install
pnpm --dir sdk/web build
pnpm --dir sdk/web-react install
pnpm --dir sdk/web-react build
pnpm --dir sdk/web-react-uikit install
pnpm --dir sdk/web-react-uikit build
cd sdk/web-react-uikit
pnpm pack --pack-destination /tmp/react-uikit-package

在业务项目安装本地 tgz 时，仍需提供核心和绑定依赖：

pnpm add @deeprespond/im-web@1.0.0-alpha @deeprespond/im-web-react@1.0.0-alpha
pnpm add /tmp/react-uikit-package/deeprespond-im-web-react-uikit-1.0.0-alpha.tgz

最小接入

先在业务客户端初始化处创建一次 SDK client，并用业务后端签发的 Ticket 登录：

import { createDRClient } from '@deeprespond/im-web';

export const client = createDRClient({
  appKey: 'your-org#your-app',
  apiUrl: 'https://your-im-api.example.com',
  autoMarkRead: true,
});
// ticket 由自己的业务服务端签发，不在浏览器中保存 App Secret。
await client.auth.loginWithTicket({ ticket });

登录成功后，在 React 组件中嵌入：

import { ChatApp, UIKitProvider } from '@deeprespond/im-web-react-uikit';
import '@deeprespond/im-web-react-uikit/styles.css';
import { client } from './im';

export function Messenger() {
  return (
    <section style={{ height: 640 }}>
      <UIKitProvider client={client} theme="light">
        <ChatApp title="业务消息" onLogout={() => client.auth.logout()} />
      </UIKitProvider>
    </section>
  );
}

UIKit 内部已经提供 DRProvider，不必额外嵌套。组件卸载时只清理自身订阅、定时器、媒体资源，不会销毁或退出宿主的 client；应用结束时由宿主调用 client.destroy()。同页多个 Provider 的通知、主题和组件状态相互独立。

ChatApp 在未登录时显示提示。业务可传 signedOut 内容，或者在 Provider 内使用 LoginPanel：默认显示 Ticket 登录，allowPassword / allowRegistration 显式开启密码及注册。登录能力仍受应用策略约束。

按组件组合

组件	接口与用途
ChatApp	完整会话、好友、群组与聊天布局；title、header、emptyState、signedOut、onLogout
ChatWindow	单独嵌入聊天窗口；conversationKey、可选 conversation 和 onClose
ConversationList	currentKey、onOpen(key, conversation)；未读、置顶、免打扰与本地草稿
ContactList	onOpenPeer(username)；好友申请、备注、删除、黑名单
GroupList	onOpenGroup(groupId)、onOpenPeer(username)；建群和成员管理
GroupMembers	groupId、onClose、onOpenPeer；群角色、邀请与群主移出入口
MessageBubble	message、可选 conversation、renderBody、onResend；独立模式不显示会话操作菜单
MessageComposer	value、onChange、onSend；可选附件、录音、引用回调和 disabled，由宿主负责发送
ConnectionBanner	连接状态与恢复提示
Avatar / Modal / Spinner	头像、含焦点管理的弹窗与加载提示
useUIKit	当前实例的通知、错误格式化与能力设置

ChatApp 的 conversationKey 为 undefined 时内部管理选择；传入字符串或 null 后改为受控选择，同时处理 onConversationChange。新建单聊从草稿转正式会话时也会通知新 key，业务应同步路由。

主题、消息与权限定制

UIKitProvider 支持：

参数	行为
theme	light / dark，只作用于当前组件容器
features	{ images, files, voice }，设置 false 隐藏对应输入能力
readOnly / readOnlyReason	移除聊天文字、附件、录音入口并展示原因；不限制好友等所有写操作
renderMessage(message)	返回自定义消息内容，返回 undefined 使用内置展示
formatError(error)	自定义错误格式化，默认中文
onError(error, action)	接收操作错误供宿主记录，不应记录 Token、密码等凭据
className / style	调整容器和局部 CSS 变量

样式限定在 .dr-uikit 内，通过局部 data-theme 管理亮暗主题，不修改宿主 html、body、主题或存储。可覆写 --accent、--grad、--panel、--text 等 CSS 变量。容器需有明确高度；窄于 760px 时显示单栏，聊天窗口有返回按钮。弹窗、预览与提示位于组件容器内。

客户端隐藏按钮只是界面行为，最终权限始终由服务端验证。表情回应按应用策略显示；群主与普通成员的管理入口不同。图片和文件通过 SDK 鉴权下载；发送失败保留消息并提供重发入口。

示例运行

# 在仓库根目录；先完成前面的核心、绑定、UIKit 构建
pnpm --dir sdk/web-react-uikit/demo install
pnpm --dir sdk/web-react-uikit/demo dev

默认地址 http://127.0.0.1:5198，在示例的 .env.local 设置 VITE_IM_APPKEY / VITE_IM_APIURL，或使用经过 URL 编码的 appKey / apiUrl 参数。示例允许密码和注册，仅供开发接入体验；生产业务应使用自己的身份认证及 Ticket。

与React 工程版 Demo的区别：原 Demo 展示如何使用底层 hooks；UIKit 示例使用组件包组装，业务无需复制整页实现。

验证范围与边界

基础版包含单聊、群聊、文本、图片预览、文件、录音和语音播放、发送状态与失败重发、已读、引用、撤回、回应、消息置顶及仅自己删除，以及好友和基本群管理。

音视频通话、聊天室、独立 RTC 频道、复杂转发、举报和更完整的群管理员设置界面尚未提供；可继续通过 SDK API 与自定义组件扩展。未知消息类型显示类型提示，也可自定义 renderMessage。

本轮自动验收使用本地真实 IM 后端、React 18 和 Chromium，覆盖双用户流程、确定性失败夹具、桌面及窄视口截图。具体通过数量与未执行项以仓库 Agent测试/ReactUIKit/20261022/测试报告.md 为准。SSR 组件契约通过不等于完成 Next.js 宿主验收；React 19、Safari、Firefox 和移动设备音频权限、自动播放仍需对应环境验收。