React UIKit 聊天元件
React UIKit 提供可直接嵌入業務專案的會話、聊天、好友和群組介面。它與 Web SDK 的關係是：
@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：
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，在倉庫根目錄執行：
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.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 元件中嵌入：
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 鑑權下載；傳送失敗保留訊息並提供重發入口。
示例執行
# 在仓库根目录；先完成前面的核心、绑定、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。