uni-app 从零接入晞晗IM

本页演示在 uni-app 的 H5、App 和小程序构建中连接 XHIM，并发送第一条文字消息。

1. 先选择发布目标

发布目标	runtime	说明
H5	h5	使用浏览器网络能力和 IndexedDB
App	app	使用 uni.request、uni.connectSocket 和本地存储适配器
小程序	mini-program	使用对应小程序平台的请求、Socket 和存储适配器

一个安装包只选择一种运行方式，不要在页面切换时改变 runtime。

2. 安装

npm install @xihansoftware/xhim-uni-app

开始前还需要 Server URL、App ID、当前 User ID，以及由业务后台签发短期凭证的接口。

3. H5 连接示例

import {
  createXHIMUniAppAdapter,
  createXHIMUniAppClient
} from '@xihansoftware/xhim-uni-app'

const client = await createXHIMUniAppClient({
  runtime: 'h5',
  server: 'https://im.example.com',
  appId: 'your-app-id',
  accountHint: currentUser.id,
  indexedDBName: `xhim-${currentUser.id}`,
  credentialProvider: ({ forceRefresh }) =>
    accountApi.fetchXHIMCredential({ forceRefresh })
})

4. App / 小程序连接示例

const client = await createXHIMUniAppClient({
  runtime: 'app', // 小程序填写 'mini-program'
  server: 'https://im.example.com',
  appId: 'your-app-id',
  accountHint: currentUser.id,
  credentialProvider: ({ forceRefresh }) =>
    accountApi.fetchXHIMCredential({ forceRefresh }),
  adapter: createXHIMUniAppAdapter(uni)
})

createXHIMUniAppAdapter 是 SDK 的公开方法，负责把 uni.request、uni.connectSocket 和 uni 本地存储接入 XHIM。如果目标是微信小程序，也可直接使用 XHIM 微信适配器。

createXHIMUniAppClient 返回的客户端已经连接，不要再次调用 connect()。

5. 发送第一条消息

const conversation = await client.getOrCreateDirectConversation('bob')
const sent = await client.sendText(
  conversation.conversationId,
  '你好，XHIM'
)

6. 页面与账号生命周期

• Client 放在应用级 Store，不要在每个页面重复创建；
• 页面卸载只取消本页监听；
• 退出或换号时调用 client.disconnect()；
• 每个账号使用独立的 IndexedDB 名称或本地存储命名空间。

7. 常见问题

• H5 刷新后没有数据：确认 indexedDBName 按账号固定且没有被清理；
• App / 小程序连接失败：检查 adapter 是否原样传递二进制响应和 WebSocket 子协议；
• 请求域名被拦截：在小程序后台配置合法 request 和 socket 域名；
• 切换账号后看到旧数据：先断开旧 Client，并切换到新账号的存储命名空间。

微信平台的完整域名和 adapter 示例见微信 / 通用小程序接入。需要修改页面和状态管理时，再阅读客户端二次开发指南。