XuqmGroup HarmonyOS SDK 文档

ArkTS · HarmonyOS 5 (API 12) · 发布至 ohpm 当前工程已可成功执行 hvigorw assembleHap

模块结构

XuqmGroup-HarmonySDK/
├── build-profile.json5          # 工程构建配置
├── hvigorfile.ts                # Hvigor 构建入口
├── oh-package.json5             # Workspace 包描述
├── xuqm-sdk/                    # SDK HAR 模块（可发布）
│   ├── Index.ets                # 统一导出入口
│   ├── oh-package.json5         # SDK 包信息（@xuqm/harmony-sdk）
│   └── src/main/ets/
│       ├── XuqmSDK.ets          # 入口类
│       ├── core/
│       │   ├── Types.ets        # 全部类型定义
│       │   ├── SDKContext.ets   # 配置 & Preferences Token 存储
│       │   └── HttpClient.ets   # HTTP 客户端（@ohos.net.http）
│       ├── im/
│       │   └── ImClient.ets     # WebSocket IM 客户端
│       ├── push/
│       │   └── PushSDK.ets      # 推送 Token 注册
│       └── update/
│           └── UpdateSDK.ets    # 版本检查 / Bundle 下载
└── entry/                       # 示例 HAP（演示用）
    └── src/main/ets/
        ├── entryability/EntryAbility.ets
        └── pages/Index.ets

环境要求

• DevEco Studio 5.0+
• HarmonyOS SDK API 12 (5.0.0.12)
• 设备/模拟器 HarmonyOS 5+

权限声明

在 module.json5 中声明：

"requestPermissions": [
  { "name": "ohos.permission.INTERNET" },
  { "name": "ohos.permission.GET_BUNDLE_INFO" }
]

---

快速开始

1. 添加依赖

// oh-package.json5
{
  "dependencies": {
    "@xuqm/harmony-sdk": "0.1.0"
  }
}

ohpm install

2. 初始化（EntryAbility.onCreate）

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

export default class EntryAbility extends UIAbility {
  async onCreate(): Promise<void> {
    await XuqmSDK.init(this.context, {
      appKey: 'ak_your_app_key',
      appSecret: 'as_your_app_secret',
      apiBaseUrl: 'https://api.xuqm.com',
      imBaseUrl: 'wss://im.xuqm.com',
      debug: true,
    })
  }
}

3. 设置 Token

// 登录后
await XuqmSDK.setToken('eyJ...')

// 登出
await XuqmSDK.setToken(null)

Token 通过 @ohos.data.preferences 持久化，App 重启后自动恢复。

---

IM 模块

连接与收发消息

import { XuqmSDK, ImEventDelegate, ImMessage } from '@xuqm/harmony-sdk'

// 实现事件委托
class MyChatDelegate implements ImEventDelegate {
  onConnected(): void {
    console.log('IM 已连接')
  }
  onDisconnected(code: number, reason: string): void {
    console.log(`断开 ${code}: ${reason}`)
  }
  onMessage(msg: ImMessage): void {
    console.log('收到消息', msg.content)
  }
  onRevoke(data: { msgId: string; operatorId: string }): void {
    console.log('消息撤回', data.msgId)
  }
  onError(message: string): void {
    console.error('IM 错误', message)
  }
}

// 在页面 aboutToAppear 中
const im = XuqmSDK.im
im.delegate = new MyChatDelegate()
im.connect()

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

// 撤回消息
im.revoke('msg-uuid')

// 页面销毁时
im.disconnect()

消息类型（MsgType）

TEXT / IMAGE / VIDEO / AUDIO / FILE / CUSTOM / LOCATION / NOTIFY / RICH_TEXT / CALL_AUDIO / CALL_VIDEO / FORWARD

ImMessage 结构

interface ImMessage {
  id: string
  fromId: string
  toId: string
  chatType: 'SINGLE' | 'GROUP'
  msgType: MsgType
  content: string
  extra?: string
  revoked: boolean
  createdAt: string
}

自动重连

断线后指数退避重连：3s → 6s → 12s → 最大 30s。disconnect() 后停止重连。

---

推送模块

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

// 在 HarmonyOS Push 服务返回 Token 后调用
// vendor 固定为 'HARMONY'
await XuqmSDK.push.registerToken('harmony_push_token', 'user_001')

// 登出时注销
await XuqmSDK.push.unregisterToken('harmony_push_token')

---

版本管理模块

检查 App 更新

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

const result = await XuqmSDK.update.checkAppUpdate('ak_xxx')

if (result.hasUpdate && result.info) {
  const { latestVersionName, downloadUrl, forceUpdate } = result.info
  console.log(`发现新版本 ${latestVersionName}`)
  // platform 'harmony': 通常引导用户跳转应用市场
}

checkAppUpdate 内部通过 bundleManager.getBundleInfoForSelfSync 获取当前 versionCode。

检查 RN Bundle 热更新

const rnResult = await XuqmSDK.update.checkRnUpdate('ak_xxx', 'main', 100)

if (rnResult.hasUpdate && rnResult.info) {
  const filePath = await XuqmSDK.update.downloadRnBundle(
    context,
    rnResult.info.downloadUrl,
    'main.harmony.bundle'
  )
  // 文件下载至 context.cacheDir/main.harmony.bundle
  // 通知 RN 引擎重新加载
}

---

发版（ohpm）

# 确认 xuqm-sdk/oh-package.json5 中 version 字段正确
cd xuqm-sdk
ohpm publish

发布至 https://ohpm.openharmony.cn/ohpm/（OpenHarmony 官方仓库）。
私有部署可在 publishConfig.registry 中配置自定义仓库地址。