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

# 微信小程序 SDK 概览

**包名**：`xuqm-group-wechat-mini-program-sdk` · **版本**：0.1.0

---

## npm 安装

在项目根目录创建 `.npmrc`：

```
registry=https://nexus.xuqinmin.com/repository/npm/
```

然后安装：

```bash
npm install xuqm-group-wechat-mini-program-sdk
```

或在微信开发者工具中：

1. 打开「工具」→「构建 npm」
2. 在小程序 `package.json` 中添加上述依赖

---

## 初始化

```ts
import { XuqmMiniProgramSDK } from 'xuqm-group-wechat-mini-program-sdk'

const sdk = new XuqmMiniProgramSDK()

sdk.init({
  appKey: 'your_app_key',
  debug: true, // 可选
})
```

---

## IM 接入

### 登录

```ts
// 使用 UserSig 登录
await sdk.login('user_001', 'your_user_sig_jwt')
```

### 监听消息

```ts
sdk.on('connected', () => {
  console.log('IM 已连接')
})

sdk.on('message', (msg) => {
  console.log('收到消息:', msg.msgType, msg.content)
})

sdk.on('read', (msg) => {
  console.log('已读回执:', msg.id)
})

sdk.on('revoke', (data) => {
  console.log('消息被撤回:', data.msgId)
})

sdk.on('disconnected', (reason) => {
  console.log('断开连接:', reason)
})

sdk.on('error', (error) => {
  console.error('IM 错误:', error)
})
```

### 发送消息

```ts
const msg = await sdk.send({
  toId: 'user_002',
  chatType: 'SINGLE',
  msgType: 'TEXT',
  content: 'Hello!',
})
```

### 发送文本消息（快捷方法）

```ts
await sdk.sendTextMessage('user_002', 'SINGLE', 'Hello!')
```

### 历史消息

```ts
const history = await sdk.fetchHistory('user_002')
const groupHistory = await sdk.fetchGroupHistory('group_xxx')
```

### 会话列表

```ts
const conversations = await sdk.listConversations()
await sdk.markRead('user_002')
await sdk.setConversationPinned('user_002', 'SINGLE', true)
await sdk.setConversationMuted('user_002', 'SINGLE', true)
```

### 群聊

```ts
const groups = await sdk.listGroups()
const group = await sdk.getGroupInfo('group_xxx')
const members = await sdk.listGroupMembers('group_xxx')
```

### 好友管理

```ts
const friends = await sdk.listFriends()
await sdk.addFriend('user_002')
await sdk.removeFriend('user_002')
```

### 离线消息同步

```ts
const count = await sdk.offlineMessageCount()
const messages = await sdk.syncOfflineMessages()
```

---

## Update 接入（小程序自带更新机制）

微信小程序的更新由微信客户端自动管理，开发者可通过微信 API 检查更新：

```ts
const updateManager = wx.getUpdateManager()

updateManager.onCheckForUpdate((res) => {
  console.log('是否有新版本:', res.hasUpdate)
})

updateManager.onUpdateReady(() => {
  wx.showModal({
    title: '更新提示',
    content: '新版本已准备好，是否重启应用？',
    success: (res) => {
      if (res.confirm) {
        updateManager.applyUpdate()
      }
    },
  })
})
```

> XuqmGroup 小程序 SDK 不额外提供 Update 模块，直接使用微信小程序原生更新能力即可。

---

## 消息类型

| MsgType | 说明 |
|---------|------|
| `TEXT` | 纯文本 |
| `IMAGE` | 图片 |
| `VIDEO` | 视频 |
| `AUDIO` | 语音 |
| `FILE` | 文件 |
| `LOCATION` | 位置 |
| `CUSTOM` | 自定义 |
| `NOTIFY` | 系统通知 |
| `RICH_TEXT` | 富文本 |
| `CALL_AUDIO` | 语音通话信令 |
| `CALL_VIDEO` | 视频通话信令 |
| `QUOTE` | 引用 |
| `MERGE` | 合并转发 |
| `FORWARD` | 转发 |
| `REVOKED` | 撤回 |

[→ Server API 文档 →](/server/api)