157 行
3.2 KiB
Markdown
157 行
3.2 KiB
Markdown
|
# H5 IM 接入
|
|||
|
|
|
|||
|
|
**模块**：`@xuqm/h5-sdk` · **功能范围**：消息收发、会话管理、好友、群组
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## IM 管理器
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
import { ImManager } from '@xuqm/h5-sdk'
|
|||
|
|
|
|||
|
|
const im = new ImManager()
|
|||
|
|
|
|||
|
|
// 监听连接状态
|
|||
|
|
im.on('connected', () => console.log('IM 已连接'))
|
|||
|
|
im.on('disconnected', () => console.log('IM 已断开'))
|
|||
|
|
|
|||
|
|
// 监听实时消息
|
|||
|
|
im.on('messages', (msgs) => {
|
|||
|
|
console.log('收到消息', msgs)
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// 监听会话列表变化
|
|||
|
|
im.on('conversations', (convs) => {
|
|||
|
|
console.log('会话列表更新', convs)
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// 开始连接
|
|||
|
|
im.connect()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 发送消息
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// 发送文本
|
|||
|
|
im.send({
|
|||
|
|
toId: 'user_002',
|
|||
|
|
chatType: 'SINGLE',
|
|||
|
|
msgType: 'TEXT',
|
|||
|
|
content: 'Hello H5!',
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 发送文件消息（自动上传）
|
|||
|
|
|
|||
|
|
SDK 内部自动上传文件到文件服务器，无需调用方手动上传。
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
import { sendImageMessage, sendFileMessage } from '@xuqm/h5-sdk'
|
|||
|
|
|
|||
|
|
// 发送图片（从 input 元素获取）
|
|||
|
|
const file = document.querySelector('input[type="file"]').files[0]
|
|||
|
|
await sendImageMessage('user_002', 'SINGLE', file, 800, 600)
|
|||
|
|
|
|||
|
|
// 发送文件
|
|||
|
|
await sendFileMessage('user_002', 'SINGLE', file)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 核心 API
|
|||
|
|
|
|||
|
|
### 事件订阅
|
|||
|
|
|
|||
|
|
| 事件 | 回调签名 | 说明 |
|
|||
|
|
|------|---------|------|
|
|||
|
|
| `connected` | `() => void` | IM 实时连接已建立 |
|
|||
|
|
| `disconnected` | `() => void` | IM 实时连接已断开 |
|
|||
|
|
| `messages` | `(msgs: ImMessage[]) => void` | 收到新消息 |
|
|||
|
|
| `conversations` | `(convs: ConversationData[]) => void` | 会话列表变化 |
|
|||
|
|
| `error` | `(err: Error) => void` | 发生错误 |
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
im.on('conversations', (convs) => {
|
|||
|
|
// 更新 UI
|
|||
|
|
})
|
|||
|
|
im.off('conversations', handler) // 取消订阅
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 状态属性
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
im.connected // boolean，是否已连接
|
|||
|
|
im.messages // ImMessage[]，当前消息列表
|
|||
|
|
im.conversations // ConversationData[]，当前会话列表
|
|||
|
|
im.error // Error | null，最近错误
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### HTTP API
|
|||
|
|
|
|||
|
|
所有 IM 功能均通过纯函数暴露：
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
import {
|
|||
|
|
sendMessage,
|
|||
|
|
sendTextMessage,
|
|||
|
|
sendImageMessage,
|
|||
|
|
sendVideoMessage,
|
|||
|
|
sendFileMessage,
|
|||
|
|
sendAudioMessage,
|
|||
|
|
fetchHistory,
|
|||
|
|
fetchGroupHistory,
|
|||
|
|
listConversations,
|
|||
|
|
markRead,
|
|||
|
|
listFriends,
|
|||
|
|
addFriend,
|
|||
|
|
listGroups,
|
|||
|
|
createGroup,
|
|||
|
|
// ...
|
|||
|
|
} from '@xuqm/h5-sdk'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 与框架集成
|
|||
|
|
|
|||
|
|
### React
|
|||
|
|
|
|||
|
|
```tsx
|
|||
|
|
import { useEffect, useState } from 'react'
|
|||
|
|
import { ImManager } from '@xuqm/h5-sdk'
|
|||
|
|
|
|||
|
|
function useIm() {
|
|||
|
|
const [im] = useState(() => new ImManager())
|
|||
|
|
const [messages, setMessages] = useState([])
|
|||
|
|
const [conversations, setConversations] = useState([])
|
|||
|
|
|
|||
|
|
useEffect(() => {
|
|||
|
|
im.on('messages', setMessages)
|
|||
|
|
im.on('conversations', setConversations)
|
|||
|
|
im.connect()
|
|||
|
|
return () => {
|
|||
|
|
im.off('messages', setMessages)
|
|||
|
|
im.off('conversations', setConversations)
|
|||
|
|
im.disconnect()
|
|||
|
|
}
|
|||
|
|
}, [im])
|
|||
|
|
|
|||
|
|
return { im, messages, conversations }
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 纯 HTML/JS
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<script src="https://dev.xuqinmin.com/docs/h5-sdk/index.umd.js"></script>
|
|||
|
|
<script>
|
|||
|
|
XuqmH5SDK.init({ appKey: 'your_app_key' })
|
|||
|
|
XuqmH5SDK.login('user_001', 'userSig')
|
|||
|
|
const im = new XuqmH5SDK.ImManager()
|
|||
|
|
im.on('messages', function(msgs) { console.log(msgs) })
|
|||
|
|
im.connect()
|
|||
|
|
</script>
|
|||
|
|
```
|
