React UIKit 聊天组件

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

text

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

当前版本为 1.1.1，已发布到公共 npm，也可以从仓库源码构建本地安装包，仓库中另有可运行的示例。支持 React 18 和 19（已在浏览器中实测 React 18）。Vue 项目请用 Vue UIKit。

从 npm 安装

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

bash

pnpm add @deeprespond/im-web@1.1.1 @deeprespond/im-web-react@1.1.1 @deeprespond/im-web-react-uikit@1.1.1

建议固定具体版本。React 和 React DOM 由你的项目提供。所有组件都从包的根路径导出，不需要复制示例源码；样式要单独导入。

从源码构建与离线安装

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

bash

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 时，仍需提供核心和绑定依赖：

bash

pnpm add @deeprespond/im-web@1.1.1 @deeprespond/im-web-react@1.1.1
pnpm add /tmp/react-uikit-package/deeprespond-im-web-react-uikit-1.1.1.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 组件中嵌入：

tsx

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>
  );
}

UIKitProvider 内部已经包含 DRProvider，不需要再套一层。
组件卸载时只清理自己的订阅、定时器和媒体资源，不会退出登录或销毁客户端；应用结束时由你调用 client.destroy()。
同一页面可以放多个 UIKitProvider，它们的通知、主题和组件状态互不影响。

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（会话键，或 null 表示没有选中）并处理 onConversationChange。新建的单聊从草稿会话变为正式会话时，也会通过它通知新的会话键，请同步更新路由。

主题、消息与权限定制

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 鉴权下载；发送失败保留消息并提供重发入口。

示例运行

bash

# 在仓库根目录；先完成前面的核心、绑定、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 示例用现成的组件拼装，不需要自己写整页界面。

验证范围与边界

已提供：单聊、群聊；文本、图片预览、文件、录音和语音播放；发送状态与失败重发、已读、引用、撤回、表情回应、消息置顶、仅自己删除；好友和基本的群管理。

尚未提供：音视频通话、聊天室、独立频道、复杂转发、举报，以及更完整的群管理员设置界面。需要时可以直接调用 SDK 的接口，配合自己的组件实现。不认识的消息类型显示类型提示，也可以用 renderMessage 自定义。

已测试的环境：React 18 + Chromium，连接真实的 IM 服务端，覆盖两个用户互发消息、发送失败等场景，桌面和窄屏都截图检查过。React 19、Next.js、Safari、Firefox，以及移动设备上的录音权限和自动播放还没有实测，上线前请在这些环境中验证。详细结果见仓库中的测试报告 Agent测试/ReactUIKit/20261022/测试报告.md。

React UIKit 聊天组件 ​

从 npm 安装 ​

从源码构建与离线安装 ​

最小接入 ​

按组件组合 ​

主题、消息与权限定制 ​

示例运行 ​

验证范围与边界 ​

React UIKit 聊天组件

从 npm 安装

从源码构建与离线安装

最小接入

按组件组合

主题、消息与权限定制

示例运行

验证范围与边界