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

# HarmonyOS IM 接入

基于 `@xuqm/harmony-sdk` 实现即时通讯功能。

---

## 初始化与登录

### 初始化

```ts
import { XuqmSDK } from '@xuqm/harmony-sdk'
import common from '@ohos.app.ability.common'

const context = getContext(this) as common.UIAbilityContext
await XuqmSDK.init(context, {
  appKey: 'your_app_key',
})
```

### 登录

```ts
const session = await XuqmSDK.login('user_001', 'your_user_sig_jwt')
```

### 登出

```ts
await XuqmSDK.logout()
```

---

## 消息收发

### 设置事件代理

```ts
const im = XuqmSDK.im

im.delegate = {
  onConnected: () => {
    console.log('IM 已连接')
  },
  onDisconnected: (code: number, reason: string) => {
    console.log('断开连接:', code, reason)
  },
  onMessage: (msg: ImMessage) => {
    console.log('收到消息:', msg.msgType, msg.content)
  },
  onRead: (msg: ImMessage) => {
    console.log('已读回执:', msg.id)
  },
  onRevoke: (data: RevokeData) => {
    console.log('消息被撤回:', data.msgId)
  },
  onError: (message: string) => {
    console.error('IM 错误:', message)
  },
}

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')
```

### 获取历史消息

```ts
const result = await im.fetchHistory('user_002', 0, 20)
// result.content  — 消息列表
// result.totalElements — 总数量

const groupResult = await im.fetchGroupHistory('group_xxx', 0, 50)
```

---

## 会话列表

```ts
const conversations = await im.listConversations(20)

// 标记已读
await im.markRead('user_002', 'SINGLE')

// 草稿
await im.setDraft('user_002', 'SINGLE', '草稿内容')

// 置顶
await im.setConversationPinned('user_002', 'SINGLE', true)

// 免打扰
await im.setConversationMuted('user_002', 'SINGLE', true)

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

---

## 群聊

```ts
// 创建群
const group = await im.createGroup('项目讨论', ['user_002', 'user_003'], 'WORK')

// 群列表
const groups = await im.listGroups()

// 群详情
const groupInfo = await im.getGroupInfo('group_xxx')

// 群成员
const members = await im.listGroupMembers('group_xxx')

// 添加/移除成员
await im.addGroupMember('group_xxx', 'user_004')
await im.removeGroupMember('group_xxx', 'user_004')

// 退出群聊
await im.leaveGroup('group_xxx')
```

---

## 好友管理

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

---

## 消息类型

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