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

# 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://dev.xuqinmin.com/docs/h5-sdk/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://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>
```