277e8ed7c6
- 实现了聊天消息发送功能，支持文本、图片、视频、音频、文件等多种消息类型 - 集成了文件上传下载功能，支持多媒体文件的传输和管理 - 添加了群组管理功能，包括创建群组、成员管理、权限控制等操作 - 实现了好友系统，支持好友添加、删除、分组等功能 - 集成了黑名单管理，提供用户屏蔽和解除屏蔽功能 - 添加了会话管理功能，支持对话列表、未读消息统计等 - 实现了历史消息查询和搜索功能 - 添加了实时连接状态管理和自动重连机制
198 行
4.1 KiB
Markdown
198 行
4.1 KiB
Markdown
# H5 SDK 接入指南
|
||
|
||
**包名**：`@xuqm/h5-sdk` · **语言**：TypeScript / JavaScript · **格式**：ESM + UMD
|
||
|
||
`@xuqm/h5-sdk` 是从 Vue3 SDK 提取的纯 JavaScript/TypeScript 核心库，**不依赖任何前端框架**（Vue/React/Angular 均可使用），可在任何支持 ES6 的浏览器或 H5 环境中运行。
|
||
|
||
> **功能范围**：仅包含 **IM** 功能（消息收发、会话管理、好友、群组），**不包含 Push 和 Update**。
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
npm install @xuqm/h5-sdk
|
||
```
|
||
|
||
或 CDN 引入：
|
||
|
||
```html
|
||
<script src="https://unpkg.com/@xuqm/h5-sdk@latest/dist/index.umd.js"></script>
|
||
<script>
|
||
const { init, ImManager, login } = XuqmH5SDK
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## 快速接入
|
||
|
||
### 1. 初始化
|
||
|
||
只需传入 `appKey`，服务器地址由 SDK 内置。
|
||
|
||
```typescript
|
||
import { init } from '@xuqm/h5-sdk'
|
||
|
||
init({
|
||
appKey: 'your_app_key', // 在租户平台创建应用后获得
|
||
})
|
||
```
|
||
|
||
### 2. 登录
|
||
|
||
```typescript
|
||
import { login } from '@xuqm/h5-sdk'
|
||
|
||
await login('user_001', 'your_user_sig_jwt')
|
||
```
|
||
|
||
### 3. 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()
|
||
```
|
||
|
||
### 4. 发送消息
|
||
|
||
```typescript
|
||
// 发送文本
|
||
im.send({
|
||
toId: 'user_002',
|
||
chatType: 'SINGLE',
|
||
msgType: 'TEXT',
|
||
content: 'Hello H5!',
|
||
})
|
||
```
|
||
|
||
### 5. 发送文件消息（自动上传）
|
||
|
||
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://unpkg.com/@xuqm/h5-sdk@latest/dist/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>
|
||
```
|
