dadedbc4df
- Add docs-site workspace (VitePress 1.5.0) with Android/iOS/RN/Vue3/HarmonyOS/Server docs - Update Dockerfile to build and serve docs under /docs/ - Add /docs/ location block to Nginx config - Add docs-site to yarn workspaces Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
210 行
5.1 KiB
Markdown
210 行
5.1 KiB
Markdown
# React Native SDK 概览
|
||
|
||
**包名**：`@xuqm/rn-sdk` · **版本**：0.1.0 · **支持**：React Native 0.73+、Expo 50+
|
||
|
||
## 功能模块
|
||
|
||
| 导出 | 功能 |
|
||
|------|------|
|
||
| `XuqmSDK` | 全局初始化 |
|
||
| `ImSDK` | 单聊、群聊、消息收发、历史记录 |
|
||
| `UpdateSDK` | App 版本检查、RN Bundle 热更新 |
|
||
| `PushSDK` | 设备 Token 上报 |
|
||
|
||
## 安装
|
||
|
||
### 从 Nexus 私有仓库安装
|
||
|
||
在项目根目录创建 `.npmrc`：
|
||
|
||
```
|
||
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm-hosted/
|
||
```
|
||
|
||
然后安装：
|
||
|
||
```bash
|
||
npm install @xuqm/rn-sdk
|
||
# 或
|
||
yarn add @xuqm/rn-sdk
|
||
```
|
||
|
||
## 快速接入
|
||
|
||
### 1. 初始化（一次即可，在 App 启动时调用）
|
||
|
||
```ts
|
||
import { XuqmSDK } from '@xuqm/rn-sdk'
|
||
|
||
XuqmSDK.init({
|
||
appId: 'your_app_id',
|
||
appKey: 'your_app_id',
|
||
appSecret: 'your_app_secret',
|
||
apiBaseUrl: 'https://sentry.xuqinmin.com',
|
||
imWsUrl: 'wss://sentry.xuqinmin.com/ws/im',
|
||
debug: __DEV__,
|
||
})
|
||
```
|
||
|
||
### 2. IM 登录
|
||
|
||
```ts
|
||
import { ImSDK } from '@xuqm/rn-sdk'
|
||
|
||
await ImSDK.login('user_001', '张三')
|
||
```
|
||
|
||
### 3. 监听消息与连接事件
|
||
|
||
```ts
|
||
import type { ImEventListener } from '@xuqm/rn-sdk'
|
||
|
||
const listener: ImEventListener = {
|
||
onConnected() { console.log('WS connected') },
|
||
onDisconnected(reason) { console.log('WS disconnected:', reason) },
|
||
onMessage(msg) { /* 单聊/群聊消息 */ },
|
||
onGroupMessage(msg) { /* 群消息（独立回调） */ },
|
||
onError(err) { console.error(err) },
|
||
}
|
||
|
||
ImSDK.addListener(listener)
|
||
|
||
// 组件卸载时移除
|
||
return () => {
|
||
ImSDK.removeListener(listener)
|
||
ImSDK.disconnect()
|
||
}
|
||
```
|
||
|
||
### 4. 发送消息
|
||
|
||
```ts
|
||
// 文本
|
||
const sent = await ImSDK.sendMessage('user_002', 'SINGLE', 'TEXT', 'Hello!')
|
||
|
||
// 图片（content 为 JSON 字符串）
|
||
const sent = await ImSDK.sendMessage('user_002', 'SINGLE', 'IMAGE', JSON.stringify({
|
||
url: 'https://cdn.example.com/img.jpg',
|
||
width: 800, height: 600,
|
||
}))
|
||
```
|
||
|
||
### 5. 撤回消息
|
||
|
||
```ts
|
||
const revoked = await ImSDK.revokeMessage(msg.id)
|
||
```
|
||
|
||
### 6. 拉取历史
|
||
|
||
```ts
|
||
// 单聊历史（page=0, size=50）
|
||
const history = await ImSDK.fetchHistory('user_002', 0, 50)
|
||
|
||
// 群历史
|
||
const gHistory = await ImSDK.fetchGroupHistory(groupId, 0, 50)
|
||
```
|
||
|
||
### 7. 群聊
|
||
|
||
```ts
|
||
// 创建群（自动将自己加入成员列表）
|
||
const group = await ImSDK.createGroup('开发讨论组', ['user_001', 'user_002'])
|
||
|
||
// 订阅群 WebSocket topic
|
||
ImSDK.subscribeGroup(group.id)
|
||
|
||
// 列出所有群
|
||
const groups = await ImSDK.listGroups()
|
||
|
||
// 发群消息
|
||
const sent = await ImSDK.sendMessage(group.id, 'GROUP', 'TEXT', '大家好')
|
||
```
|
||
|
||
### 8. 检查 App 更新
|
||
|
||
```ts
|
||
import { UpdateSDK } from '@xuqm/rn-sdk'
|
||
|
||
const info = await UpdateSDK.checkAppUpdate(1 /* 当前 versionCode */)
|
||
if (info) {
|
||
console.log(info.versionName, info.forceUpdate, info.downloadUrl)
|
||
}
|
||
```
|
||
|
||
### 9. RN Bundle 热更新（三步流程）
|
||
|
||
```ts
|
||
import AsyncStorage from '@react-native-async-storage/async-storage'
|
||
|
||
// Step 1: 检查是否有新版本
|
||
const bundle = await UpdateSDK.checkRNUpdate('home', '1.0.0')
|
||
if (!bundle) return // 已是最新
|
||
|
||
// Step 2: 下载 bundle
|
||
const content = await UpdateSDK.downloadBundle(bundle.downloadUrl)
|
||
|
||
// Step 3: 缓存，下次启动由 BundleRuntime 加载
|
||
await AsyncStorage.setItem('rn_bundle_home', JSON.stringify({
|
||
version: bundle.version,
|
||
md5: bundle.md5,
|
||
content,
|
||
cachedAt: new Date().toISOString(),
|
||
}))
|
||
```
|
||
|
||
> **提示**：运行时替换（热加载）需对接原生 `BundleRuntime`，参考 `ProjectFrameReactNative` 架构文档。
|
||
|
||
## 完整消息类型
|
||
|
||
```ts
|
||
type MsgType =
|
||
| 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'FILE'
|
||
| 'CUSTOM' | 'LOCATION' | 'NOTIFY' | 'RICH_TEXT'
|
||
| 'CALL_AUDIO' | 'CALL_VIDEO' | 'FORWARD' | 'REVOKED'
|
||
```
|
||
|
||
每种类型的 `content` 格式：
|
||
|
||
| MsgType | content |
|
||
|---------|---------|
|
||
| `TEXT` | 纯文本字符串 |
|
||
| `IMAGE` | `{"url":"...","width":800,"height":600,"thumbnailUrl":"..."}` |
|
||
| `VIDEO` | `{"url":"...","duration":30,"thumbnailUrl":"...","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>内容"}` |
|
||
| `CALL_AUDIO` | `{"callId":"uuid","action":"INVITE","callerName":"张三"}` |
|
||
| `CALL_VIDEO` | `{"callId":"uuid","action":"INVITE","callerName":"张三"}` |
|
||
| `FORWARD` | `{"originalMsgId":"...","originalContent":"原始内容","originalSender":"张三"}` |
|
||
| `REVOKED` | 服务端下发，客户端只读 |
|
||
|
||
## TypeScript 类型定义
|
||
|
||
```ts
|
||
interface ImMessage {
|
||
id: string
|
||
appId: string
|
||
fromUserId: string
|
||
toId: string
|
||
chatType: 'SINGLE' | 'GROUP'
|
||
msgType: MsgType
|
||
content: string
|
||
status: 'SENT' | 'REVOKED'
|
||
createdAt: string // ISO 8601
|
||
}
|
||
|
||
interface ImGroup {
|
||
id: string
|
||
appId: string
|
||
name: string
|
||
creatorId: string
|
||
memberIds: string[]
|
||
adminIds: string[]
|
||
createdAt: string
|
||
}
|
||
```
|
