233 行
5.2 KiB
Markdown
233 行
5.2 KiB
Markdown
# XuqmGroup HarmonyOS SDK 文档
|
||
|
||
> ArkTS · HarmonyOS 5 (API 12) · 发布至 ohpm
|
||
|
||
## 模块结构
|
||
|
||
```
|
||
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` 中声明：
|
||
```json5
|
||
"requestPermissions": [
|
||
{ "name": "ohos.permission.INTERNET" },
|
||
{ "name": "ohos.permission.GET_BUNDLE_INFO" }
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 添加依赖
|
||
|
||
```json5
|
||
// oh-package.json5
|
||
{
|
||
"dependencies": {
|
||
"@xuqm/harmony-sdk": "0.1.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
ohpm install
|
||
```
|
||
|
||
### 2. 初始化（EntryAbility.onCreate）
|
||
|
||
```typescript
|
||
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
|
||
|
||
```typescript
|
||
// 登录后
|
||
await XuqmSDK.setToken('eyJ...')
|
||
|
||
// 登出
|
||
await XuqmSDK.setToken(null)
|
||
```
|
||
|
||
Token 通过 `@ohos.data.preferences` 持久化，App 重启后自动恢复。
|
||
|
||
---
|
||
|
||
## IM 模块
|
||
|
||
### 连接与收发消息
|
||
|
||
```typescript
|
||
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 结构
|
||
|
||
```typescript
|
||
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()` 后停止重连。
|
||
|
||
---
|
||
|
||
## 推送模块
|
||
|
||
```typescript
|
||
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 更新
|
||
|
||
```typescript
|
||
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 热更新
|
||
|
||
```typescript
|
||
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）
|
||
|
||
```bash
|
||
# 确认 xuqm-sdk/oh-package.json5 中 version 字段正确
|
||
cd xuqm-sdk
|
||
ohpm publish
|
||
```
|
||
|
||
发布至 `https://ohpm.openharmony.cn/ohpm/`（OpenHarmony 官方仓库）。
|
||
私有部署可在 `publishConfig.registry` 中配置自定义仓库地址。
|
