uni-app x 鸿蒙开发指南(UTS 插件)
更新时间: 2026/09/02 16:51:32
本文介绍如何在 uni-app x 框架中集成 NERTC UTS 插件并编译至鸿蒙平台。
- NERTC UTS 插件仅面向
uni-app x鸿蒙宿主,通过uni-app x + UTS + native-view承载 RTC 能力,不适用于 Android/iOS 原生插件宿主方式。 - 若某些底层能力尚未由鸿蒙原生 SDK 支持,则不对外承诺该能力可用。
功能概述
Harmony 侧当前对外提供的核心能力包括:
- 引擎初始化与销毁
- 加入/离开房间
- 本地音视频开关
- 远端主视频/屏幕共享渲染
- 伴音、悬浮窗、截图等已支持能力
开发环境要求
开始集成前,请确保开发环境满足以下要求:
| 环境要求 | 说明 |
|---|---|
| HBuilderX | 建议 4.75 及以上版本 |
| uni-app x | 建议 3.1.0 及以上版本 |
| DevEco Studio | 用于 Harmony 工程签名、编译与安装 |
| 鸿蒙真机 | 用于最终联调与验收 |
工程结构
接入时建议重点关注以下目录和文件:
| 路径 | 说明 |
|---|---|
uni_modules/netease-nertc/ |
Harmony RTC UTS 插件主体 |
uni_modules/netease-nertc/utssdk/app-harmony/index.uts |
Harmony 引擎适配层 |
uni_modules/netease-nertc/components/nertc-view/nertc-view.uvue |
视频渲染视图组件示例 |
pages/demo/one-to-one.uvue |
一对一通话示例 |
pages/demo/multi.uvue |
多人通话示例 |
pages/demo/config.uvue |
配置中心示例 |
集成 SDK
步骤 1:(可选)创建 uni-app x 项目
如果需要在已有项目中集成 SDK,可跳过此步骤。
在 HBuilderX 中创建一个新的 uni-app x 项目。详细操作步骤请参见 uni-app x 快速上手。
步骤 2:引入 UTS 插件
将 netease-nertc 插件接入工程后,在业务代码中直接使用:
tsimport { NERtcHarmonyEngine, NERtcNativeView } from '@/uni_modules/netease-nertc'
其中:
| 类 | 说明 |
|---|---|
NERtcHarmonyEngine |
Harmony RTC 引擎封装 |
NERtcNativeView |
Harmony 视频承载桥接类 |
步骤 3:配置 Harmony 工程
在宿主工程中完成以下配置:
- 应用包名
- 应用签名证书
- 摄像头权限
- 麦克风权限
- 相册权限(如需截图保存)
步骤 4:配置视频渲染
Harmony 视频渲染基于 native-view,推荐使用封装好的 nertc-view 组件进行绑定。
本地主视频、远端主视频、远端屏幕共享建议使用不同的 canvasId:
| 视频类型 | 建议 canvasId |
|---|---|
| 本地主视频 | local-main |
| 远端主视频 | remote-{uid}-main |
| 远端屏幕共享 | remote-{uid}-sub |
步骤 5:初始化与加入房间
推荐流程如下:
- 创建引擎实例
- 注册事件回调
- 申请摄像头和麦克风权限
- 初始化引擎
- 配置音频和视频参数
- 绑定本地预览画布
- 加入房间
- 收到远端用户事件后绑定远端画布
- 结束通话时离开房间并销毁引擎
tsconst engine = new NERtcHarmonyEngine()
engine.setEventSink((event, payload) => {
console.log('rtc event', event, payload)
})
await engine.requestPermission()
engine.init({
appKey: 'your-app-key',
logLevel: 3
})
engine.setAudioProfile({
profile: 0,
scenario: 1
})
engine.enableLocalAudio(true)
engine.enableLocalVideo({ enabled: true, streamType: 0 })
engine.setupLocalVideoCanvas({
canvasId: 'local-main',
renderMode: 2,
mirrorMode: 0
})
engine.joinChannel({
token: '',
channelName: 'demo-room',
uid: 10001
})
步骤 6:运行与调试
- 使用 HBuilderX 运行到 Harmony 设备。
- 首次运行时完成 DevEco Studio 签名配置。
- 真机验证时,建议同时使用同一房间的另一端设备进行互通测试。
此文档是否对你有帮助?





