XuqmGroup-Web/docs-site/docs/vue3/im.md

# Vue3 IM 接入

基于 `@xuqm/vue3-sdk` 实现即时通讯功能，支持原生 WebSocket + STOMP 协议。

---

## 初始化与登录

### 初始化

```ts
import { init } from '@xuqm/vue3-sdk'

init({
  appKey: 'your_app_key',
  appSecret: 'your_app_secret',
})
```

### 登录

```ts
import { login } from '@xuqm/vue3-sdk'

login('user_001', 'your_user_sig_jwt')
```

---

## 消息收发

### 使用 ImClient

```ts
import { ImClient } from '@xuqm/vue3-sdk'

const im = new ImClient()

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

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

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

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

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

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

im.connect()
```

### 发送消息

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

### 发送多媒体消息

```ts
// 图片
im.send({
  toId: 'user_002',
  chatType: 'SINGLE',
  msgType: 'IMAGE',
  content: JSON.stringify({ url: 'https://...', width: 800, height: 600 }),
})

// 位置
im.send({
  toId: 'user_002',
  chatType: 'SINGLE',
  msgType: 'LOCATION',
  content: JSON.stringify({ lat: 31.2304, lng: 121.4737, title: '上海' }),
})
```

### 撤回消息

```ts
im.revoke('message_id')
```

---

## 使用 Vue Composable（useIm）

```ts
import { useIm } from '@xuqm/vue3-sdk'

const im = useIm()

// 连接
im.connect()

// 发送消息
im.send({ toId: 'user_002', chatType: 'SINGLE', msgType: 'TEXT', content: 'Hello' })

// 响应式状态
console.log(im.connected.value)     // boolean
console.log(im.messages.value)      // ImMessage[]
console.log(im.conversations.value) // ConversationView[]
console.log(im.error.value)         // Event | null

// 历史消息
const history = await im.loadHistory('user_002')

// 标记已读
await im.setConversationRead('user_002')

// 置顶/免打扰
await im.setConversationPinnedState('user_002', 'SINGLE', true)
await im.setConversationMutedState('user_002', 'SINGLE', true)

// 删除会话
await im.removeConversation('user_002', 'SINGLE')

// 断开
im.disconnect()
```

> `useIm` 在组件卸载时会自动调用 `disconnect()`。

---

## 会话列表

```ts
import { listConversations } from '@xuqm/vue3-sdk'

const conversations = await listConversations()
```

会话数据类型：

```ts
interface ConversationView {
  targetId: string
  chatType: 'SINGLE' | 'GROUP'
  lastMsgContent?: string | null
  lastMsgType?: string | null
  lastMsgTime: number
  unreadCount: number
  isMuted: boolean
  isPinned: boolean
}
```

---

## 离线消息同步

```ts
import { offlineMessageCount, syncOfflineMessages } from '@xuqm/vue3-sdk'

const count = await offlineMessageCount()
const messages = await syncOfflineMessages()
```

---

## 群聊

```ts
import { createGroup, listGroups, addGroupMember, removeGroupMember } from '@xuqm/vue3-sdk'

const group = await createGroup('项目讨论', ['user_002', 'user_003'])
const groups = await listGroups()
await addGroupMember('group_xxx', 'user_004')
await removeGroupMember('group_xxx', 'user_004')
```

---

## 好友管理

```ts
import { listFriends, addFriend, removeFriend, sendFriendRequest } from '@xuqm/vue3-sdk'

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

---

## 消息类型

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

[→ 完整 API Reference](./api)