XuqmGroup-Web/docs-site/docs/rn/index.md

React Native SDK 概览

包名：@xuqm/rn-sdk · 版本：0.3.0 · 支持：React Native 0.73+

功能模块

包	功能
@xuqm/rn-common	初始化、网络、设备信息（必须）
@xuqm/rn-im	单聊、群聊、消息收发、本地 DB
@xuqm/rn-push	推送设备 Token 上报
@xuqm/rn-update	App 版本检查、RN Bundle 热更新
@xuqm/rn-sdk	以上所有模块的 meta 包（推荐直接使用）

安装

在项目根目录创建 .npmrc：

@xuqm:registry=https://nexus.xuqinmin.com/repository/npm/

安装 meta 包（包含全部功能）：

yarn add @xuqm/rn-sdk

或按需安装（减小包体积）：

yarn add @xuqm/rn-common @xuqm/rn-im

快速接入

1. 初始化（推荐异步方式）

import { XuqmSDK } from '@xuqm/rn-sdk'

// 推荐：从租户平台拉取完整配置
await XuqmSDK.initialize({
  appId:     'your_app_id',
  serverUrl: 'https://your-server.com',
  debug:     __DEV__,
})

// 兼容：同步初始化，不发网络请求，根据 serverUrl 推导 URL
XuqmSDK.init({
  appId:     'your_app_id',
  serverUrl: 'https://your-server.com',
})

initialize 自动从 GET /api/sdk/config?appId= 获取 imWsUrl、fileServiceUrl 等配置，并在网络失败时 fallback 到 serverUrl 推导值。

2. IM 登录

import { ImSDK } from '@xuqm/rn-sdk'

// 使用 IM token（由你的业务服务端签发）
await ImSDK.loginWithToken('user_001', 'im_token_from_server', 'xuqm_im')

// 直接登录（适用于 im-service 直接认证场景）
await ImSDK.login('user_001', '张三', 'https://cdn.example.com/avatar.jpg', 'xuqm_im')

3. 监听消息与连接状态

import type { ImEventListener } from '@xuqm/rn-sdk'

const listener: ImEventListener = {
  onConnected()           { console.log('WS 已连接') },
  onDisconnected(reason)  { console.log('WS 断开:', reason) },
  onMessage(msg)          { /* 收到单聊消息 */ },
  onGroupMessage(msg)     { /* 收到群聊消息 */ },
  onError(err)            { console.error(err) },
}

ImSDK.addListener(listener)
return () => ImSDK.removeListener(listener)

4. 发送消息

// 文本消息
const msg = await ImSDK.sendMessage('user_002', 'SINGLE', 'TEXT', 'Hello!')

// 图片（SDK 自动上传到 file-service）
const msg = await ImSDK.sendImageMessage('user_002', 'SINGLE', localUri, width, height)

// 视频
const msg = await ImSDK.sendVideoMessage('user_002', 'SINGLE', localUri, thumbnailUri, durationSeconds)

// 语音
const msg = await ImSDK.sendAudioMessage('user_002', 'SINGLE', localUri, durationSeconds)

// 文件
const msg = await ImSDK.sendFileMessage('user_002', 'SINGLE', localUri, 'report.pdf', fileSize)

5. 拉取历史消息

// 单聊历史（先读本地 DB，再回源服务端）
const history = await ImSDK.fetchHistory('user_002', 0, 30)

// 群聊历史
const gHistory = await ImSDK.fetchGroupHistory(groupId, 0, 30)

6. 会话列表（响应式）

// 订阅本地 DB 变更，新消息/已读/静音/置顶都会触发回调
const unsub = ImSDK.subscribeConversations((convs) => {
  setConversations(convs)
})
return unsub  // 组件卸载时调用

// 标记已读
await ImSDK.markRead('user_002')

// 置顶/静音
await ImSDK.setConversationPinned('user_002', 'SINGLE', true)
await ImSDK.setConversationMuted('user_002', 'SINGLE', true)

7. 群聊

// 创建群
const group = await ImSDK.createGroup('讨论组', ['user_001', 'user_002'])

// 订阅群消息 WebSocket topic
ImSDK.subscribeGroup(group.id)

// 群消息撤回
await ImSDK.revokeMessage(messageId)

8. 好友管理

await ImSDK.addFriend('user_002')
await ImSDK.removeFriend('user_002')
const friends = await ImSDK.listFriends()

9. 消息搜索

const results = await ImSDK.searchMessages({
  keyword: '关键字',
  msgType: 'TEXT',          // 可选，过滤消息类型
  startTime: '2026-01-01',  // 可选，时间范围
  endTime: '2026-12-31',
})

10. App 版本更新

import { UpdateSDK } from '@xuqm/rn-sdk'

// 自动读取原生版本码，无需传参
const info = await UpdateSDK.checkAppUpdate()
if (info?.needsUpdate) {
  console.log(info.versionName, info.forceUpdate, info.downloadUrl)
}

11. RN Bundle 热更新

// 插件在 bundle 加载时自注册（自动读取 plugin.json）
import meta from './plugin.json'  // { moduleId, version }
UpdateSDK.registerPlugin(meta)

// 检查 → 下载 → 缓存（三步）
const checkInfo = await UpdateSDK.checkRnUpdate('home')
if (checkInfo.needsUpdate) {
  const source = await UpdateSDK.downloadRnBundle(checkInfo.downloadUrl)
  await UpdateSDK.cacheRnBundle('home', checkInfo.latestVersion, checkInfo.md5, source)
}

消息类型 content 格式

MsgType	content
TEXT	纯文本字符串
IMAGE	{"url":"...","thumbnailUrl":"...","width":800,"height":600}
VIDEO	{"url":"...","thumbnailUrl":"...","duration":30,"size":1048576}
AUDIO	{"url":"...","duration":12,"size":204800}
FILE	{"url":"...","name":"report.pdf","size":512000,"mimeType":"application/pdf"}
LOCATION	{"lat":39.9042,"lng":116.4074,"address":"北京市","title":"天安门"}
CUSTOM	任意 JSON 字符串
NOTIFY	{"title":"系统通知","content":"内容","level":"INFO"}
RICH_TEXT	{"html":"<b>加粗</b>内容"}

TypeScript 类型

interface ImMessage {
  id:               string
  appId:            string
  fromUserId:       string
  toId:             string
  chatType:         'SINGLE' | 'GROUP'
  msgType:          MsgType
  content:          string
  status:           'SENT' | 'DELIVERED' | 'READ' | 'REVOKED'
  mentionedUserIds?: string
  createdAt:        string   // ISO 8601
}

interface ConversationData {
  targetId:      string
  chatType:      'SINGLE' | 'GROUP'
  lastMsgContent: string
  lastMsgType:   string
  lastMsgTime:   number    // Unix ms
  unreadCount:   number
  isMuted:       boolean
  isPinned:      boolean
}