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

# HarmonyOS SDK 概览

**包名**：`@xuqm/harmony-sdk` · **版本**：0.1.0 · **支持**：HarmonyOS NEXT（API 12+）、ArkTS

## 功能模块

| 模块 | 功能 |
|------|------|
| `XuqmSDK` | 全局初始化 |
| `ImSDK` | 单聊、群聊、消息收发 |
| `UpdateSDK` | App 版本检查、RN Bundle 热更新 |

## 安装

在 `oh-package.json5` 中添加：

```json
{
  "dependencies": {
    "@xuqm/harmony-sdk": "0.1.0"
  }
}
```

配置私有仓库（`.ohpmrc`）：

```
registry=https://nexus.xuqinmin.com/repository/ohpm-hosted/
```

执行安装：

```bash
ohpm install
```

## 快速接入

### 1. 初始化（EntryAbility.onCreate）

```typescript
import { XuqmSDK } from '@xuqm/harmony-sdk'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    XuqmSDK.init({
      appId:      'your_app_id',
      appKey:     'your_app_id',
      appSecret:  'your_app_secret',
      apiBaseUrl: 'https://dev.xuqinmin.com',
      imWsUrl:    'wss://dev.xuqinmin.com/ws/im',
      debug:      true,
    })
  }
}
```

### 2. IM 登录

```typescript
import { ImSDK } from '@xuqm/harmony-sdk'

await ImSDK.login('user_001', '张三')
```

### 3. 监听消息

```typescript
ImSDK.addListener({
  onConnected():         void { console.log('WS connected') },
  onDisconnected(reason: string | null): void { },
  onMessage(msg: ImMessage):  void { /* 处理消息 */ },
  onError(err: string):       void { },
})
```

### 4. 发送消息

```typescript
// 文本消息
const sent = await ImSDK.sendMessage({
  toId:     'user_002',
  chatType: 'SINGLE',
  msgType:  'TEXT',
  content:  'Hello from HarmonyOS!',
})

// 图片消息
const sent = await ImSDK.sendMessage({
  toId: 'user_002', chatType: 'SINGLE',
  msgType: 'IMAGE',
  content: JSON.stringify({ url: 'https://cdn.example.com/img.jpg', width: 800, height: 600 }),
})
```

### 5. 撤回消息

```typescript
const revoked = await ImSDK.revokeMessage(msg.id)
```

### 6. 群聊

```typescript
const group = await ImSDK.createGroup('鸿蒙群', ['user_001', 'user_002'])
ImSDK.subscribeGroup(group.id)
const sent = await ImSDK.sendMessage({ toId: group.id, chatType: 'GROUP', msgType: 'TEXT', content: '大家好' })
```

### 7. 检查更新

```typescript
import { UpdateSDK } from '@xuqm/harmony-sdk'

const appInfo = await UpdateSDK.checkAppUpdate(1)
if (appInfo?.forceUpdate) {
  // 跳转应用市场
}

const bundle = await UpdateSDK.checkRNUpdate('home', '1.0.0')
if (bundle) {
  const content = await UpdateSDK.downloadBundle(bundle.downloadUrl)
  // 缓存至本地，由 BundleRuntime 加载
}
```

## ArkUI 示例

```typescript
@Component
struct ChatView {
  @State messages: ImMessage[] = []

  aboutToAppear() {
    ImSDK.addListener({
      onMessage: (msg) => { this.messages = [...this.messages, msg] },
      onConnected: () => {},
      onDisconnected: () => {},
      onError: () => {},
    })
  }

  build() {
    Column() {
      List() {
        ForEach(this.messages, (msg: ImMessage) => {
          ListItem() {
            Text(`${msg.fromUserId}: ${msg.content}`)
              .fontSize(16)
              .padding(8)
          }
        })
      }
    }
  }
}
```

## 权限配置

在 `module.json5` 中添加必要权限：

```json
{
  "requestPermissions": [
    { "name": "ohos.permission.INTERNET" },
    { "name": "ohos.permission.GET_NETWORK_INFO" }
  ]
}
```