帮你快速理解、总结文档立即下载

快速跑通云渲染鸿蒙 SDK

最近更新时间:2026-07-16 11:21:00

我的收藏

1. 接入 SDK

oh-package.json5 中添加 SDK 依赖:
{
"dependencies": {
"virtualman-stream-sdk": "file:../sdk"
}
}
同时确保 TRTC HarmonyOS SDK 已放入 sdk/libs/ 目录下,并在 SDK 的 oh-package.json5 中配置:
{
"dependencies": {
"@tencentcloud/liteavsdk_trtc": "file:./libs/LiteAVSDK_TRTC_13.4.0.8928.har"
}
}
注意:
使用的是专为数智人场景定制的 TRTC 版本,包含 Alpha 通道视频等数智人专属能力,请勿替换为通用版本。

2. 配置权限

SDK 需要网络权限和麦克风权限(语音驱动时),请在 module.json5 中配置:
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" },
{
"name": "ohos.permission.MICROPHONE",
"reason": "$string:permission_microphone_reason",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
}
]

3. 配置凭证

Config.ets 中填入您的数智人项目凭证:
export class Config {
static readonly APP_KEY: string = 'xxx'
static readonly ACCESS_TOKEN: string = 'xxx'
static readonly ASSET_VIRTUALMAN_KEY: string = 'xxx' // Asset 建流时使用
static readonly VIRTUALMAN_PROJECT_ID: string = 'xxx' // Project 建流时使用
}

4. 初始化及使用

import {
VirtualmanView, Virtualman,
VirtualmanParams, VirtualmanProjectParams, AssetVirtualmanParams, ExtraInfo
} from 'virtualman-stream-sdk'
import { Config } from '../Config'

@Entry
@Component
struct Index {
private virtualman: Virtualman = new Virtualman()
@State isReady: boolean = false

aboutToAppear(): void {
// 第一步:初始化(配置鉴权参数和建流参数,不建流)
// 注意:ArkTS 严格模式要求使用 new,不可使用匿名对象字面量
const params = new VirtualmanParams()
params.appkey = Config.APP_KEY
params.accesstoken = Config.ACCESS_TOKEN

// 方式一:项目建流参数
const projectParams = new VirtualmanProjectParams()
projectParams.virtualmanProjectId = Config.VIRTUALMAN_PROJECT_ID
const projectExtra = new ExtraInfo()
projectExtra.alphaChannelEnable = true
projectParams.extraInfo = projectExtra
params.virtualmanProjectParams = projectParams

// 方式二:资产建流参数
const assetParams = new AssetVirtualmanParams()
assetParams.assetVirtualmanKey = Config.ASSET_VIRTUALMAN_KEY
const assetExtra = new ExtraInfo()
assetExtra.alphaChannelEnable = true
assetParams.extraInfo = assetExtra
params.assetVirtualmanParams = assetParams

this.virtualman.init(params)

// 第二步:设置事件回调(挂在 controller 上,而非 VirtualmanView)
this.virtualman.onError = (error: string): void => {
console.error(`错误: ${error}`)
}
this.virtualman.onMessage = (text: string): void => {
console.info(`收到WS消息: ${text}`)
}
this.virtualman.onWsOpen = (): void => {
console.info('WebSocket 已连接,可以发送消息')
}
this.virtualman.onWsClose = (code: number, reason: string): void => {
console.info(`WebSocket 已断开: code=${code}`)
}
}

build() {
Stack() {
// 第三步:挂载渲染视图(始终挂载,内部管理生命周期)
VirtualmanView({
controller: this.virtualman
})
.width('100%')
.height('100%')

Column() {
// 方式一:通过 ProjectId 建流
Button('项目建流')
.onClick(async (): Promise<void> => {
const result = await this.virtualman.open()
if (result.success) {
this.isReady = true
console.info(`建流成功, sessionId: ${result.sessionId ?? ''}`)
} else {
console.error(`建流失败: ${result.error ?? ''}`)
}
})

// 方式二:通过 AssetVirtualmanKey 建流
Button('资产建流')
.onClick(async (): Promise<void> => {
const result = await this.virtualman.openByAsset()
if (result.success) {
this.isReady = true
console.info(`建流成功, sessionId: ${result.sessionId ?? ''}`)
} else {
console.error(`建流失败: ${result.error ?? ''}`)
}
})

// 建流成功后:发送指令
if (this.isReady) {
Button('发送对话')
.onClick((): void => {
this.virtualman.chat({ text: '你好', isNewChat: true })
})

Button('关流')
.onClick((): void => {
this.virtualman.close()
this.isReady = false
})
}
}
}
}
}

5. 运行 Demo

5.1 打开工程

使用 DevEco Studio 打开 harmony 目录。

5.2 配置签名

1. File → Project Structure → Signing Configs。
2. 勾选 Automatically generate signature。
3. 选择您的开发者证书。

5.3 选择设备并运行

1. 在 DevEco Studio 顶部工具栏选择目标设备。
2. 单击 ▶️ 运行按钮。

5.4 常见问题

问题
解决方法
运行后黑屏无画面
确认 Config.ets 中的凭证填写正确,且网络可用
编译时找不到 SDK
确认 oh-package.json5 中 dependencies 路径配置正确
透明通道不生效
确认 open 时传入了 extraInfo.alphaChannelEnable = true
建流失败后无法重试
建流失败后 open() 返回 success: false,按钮仍可点击重新 open