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:初始化与加入房间

推荐流程如下:

  1. 创建引擎实例
  2. 注册事件回调
  3. 申请摄像头和麦克风权限
  4. 初始化引擎
  5. 配置音频和视频参数
  6. 绑定本地预览画布
  7. 加入房间
  8. 收到远端用户事件后绑定远端画布
  9. 结束通话时离开房间并销毁引擎
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:运行与调试

  1. 使用 HBuilderX 运行到 Harmony 设备。
  2. 首次运行时完成 DevEco Studio 签名配置。
  3. 真机验证时,建议同时使用同一房间的另一端设备进行互通测试。
此文档是否对你有帮助?
有帮助
去反馈
  • 功能概述
  • 开发环境要求
  • 工程结构
  • 集成 SDK
  • 步骤 1:(可选)创建 uni-app x 项目
  • 步骤 2:引入 UTS 插件
  • 步骤 3:配置 Harmony 工程
  • 步骤 4:配置视频渲染
  • 步骤 5:初始化与加入房间
  • 步骤 6:运行与调试