HarmonyOS

最近更新时间:2026-05-13 17:21:11

我的收藏
TUIRoomKit 是腾讯云提供的一站式多人音视频房间解决方案,集成了完整的 UI 组件和核心功能。通过本文档,开发者可以快速了解如何将 TUIRoomKit 集成到项目中,实现多人音视频房间功能。本文还将详细介绍如何快速替换图片资源、本地化文案等个性化配置,帮助开发者打造符合品牌特色的音视频应用。
房间准备页
标准房间主页
大型研讨会房间主页
成员管理











前提条件

开通服务

请参考 开通服务 领取 TUIRoomKit 体验版,并在 应用管理 页面获取以下信息:
SDKAppID:应用标识(必填),腾讯云基于 SDKAppID 完成计费统计。
SDKSecretKey:应用密钥,用于初始化配置文件的密钥信息。

环境准备

集成开发环境:6.0.0.858 或以上。
手机操作系统:HarmonyOS 5.0.5 或以上。
API Version:17 或以上。

快速接入

步骤1:集成 TUIRoomKit 组件

下载源码

从 GitHub 下载 TUIKit Harmony 源码:
git clone https://github.com/Tencent-RTC/TUIKit_Harmony.git

集成组件

1. 将组件目录完整复制到您的鸿蒙项目中,如下图所示,其中 application 是示例项目,room 和 atomic_x 是从 GitHub 上下载的组件源码。

2. 在您的工程 entryoh-package.json5 文件中,添加以下插件依赖。
"dependencies": {
"@tencentcloud/atomicxcore": "^4.1.0",
"@tencentcloud/atomicx": "file:../../../atomic_x",
"@tencentcloud/tuiroomkit": "file:../../../room",
}
说明:
room 和 atomic_x 可以放在任何位置,只要在 oh-package.json5 中正确设置相对路径即可。
3. oh-package.json5 修改完毕后,执行以下命令,安装本地 TUIKit 组件。示例:
ohpm install
ohpm install 会自动安装所需的依赖库。
注意:
使用本地集成方案时,如需升级时需要从 GitHub 获取最新的组件代码,覆盖您本地项目的 atomic_x 目录。
当私有化修改和远端有冲突时,需要手动合并,处理冲突。

步骤2:工程配置

1. 权限配置:您需要在您工程 entry 的 module.json5 的 module 模块中,声明以下所需要的权限:
"requestPermissions":[
{
"name" : "ohos.permission.INTERNET"
},
{
"name" : "ohos.permission.USE_BLUETOOTH"
},
{
"name" : "ohos.permission.GET_BUNDLE_INFO"
},
{
"name" : "ohos.permission.GET_NETWORK_INFO"
},
{
"name" : "ohos.permission.GET_WIFI_INFO"
},
{
"name" : "ohos.permission.MODIFY_AUDIO_SETTINGS"
},
{
"name" : "ohos.permission.MICROPHONE",
"reason": "$string:module_desc",
"usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
},
{
"name" : "ohos.permission.CAMERA",
"reason": "$string:module_desc",
"usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
},
]
2. 模块声明:已有项目集成源码后,需在 build-profile.json5 文件声明模块:
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": [
"default"
]
}
]
},
{
"name": "tuiroomkit",
"srcPath": "../room", // 根据实际目录调整
"targets": [
{
"name": "default",
"applyToProducts": [
"default"
]
}
]
},
{
"name": "atomic_x",
"srcPath": "../atomic_x", // 根据实际目录调整
"targets": [
{
"name": "default",
"applyToProducts": [
"default"
]
}
]
}
]

步骤3:登录

代码集成完成后,需要完成登录操作,这是使用 TUIRoomKit 的关键步骤。只有在登录成功后,才能正常使用 TUIRoomKit 的各项功能,因此请仔细检查相关参数配置是否正确:
说明:
在示例代码中,直接进行了登录接口的调用。但在实际项目场景下,强烈推荐您在完成自己的用户身份验证等相关登录操作后,再调用 TUIRoomKit 的登录服务。这样可以避免因过早调用登录服务,导致业务逻辑混乱或数据不一致的问题,同时也能更好地适配您项目中现有的用户管理和权限控制体系。
ArkTS
import { LoginStore } from '@tencentcloud/atomicxcore'

try {
await LoginStore.shared().login(
1400000000, // 替换为您的 SDKAPPID
'userID', // 替换为您的 UserID
'userSig', // 替换为您的 UserSig
);
// login success
} catch (error) {
// login error
}
登录接口参数说明:
参数
类型
说明
sdkAppID
number
控制台 获取,通常是以 140160 开头的 10 位整数。
userID
string
当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1123 等简单 ID
userSig
string
用于腾讯云鉴权的票据。更多信息请参见 如何计算及使用 UserSig
【注意事项】
开发环境:可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 UserSig 辅助工具 生成临时的 userSig。
生产环境:为了防止密钥泄露,请务必采用服务端生成 userSig 的方式。详细信息请参考 服务端生成 UserSig

步骤4:设置头像和昵称

首次登录的用户没有头像和昵称信息,需要通过 LoginStoresetSelfInfo 接口设置个人信息:
import { LoginStore, UserProfile, ErrorInfo } from '@tencentcloud/atomicxcore';

try {
await LoginStore.shared().setSelfInfo(new UserProfile('userID', 'userName', 'avatarURL'));
console.info("setSelfInfo success");
} catch (error) {
const err = error as ErrorInfo;
console.error(`setSelfInfo failed [code: ${err.code}] ${err.message}`);
}
setSelfInfo 接口参数/返回值说明:
参数/返回值
类型
说明
userProfile
UserProfile
个人用户信息核心模型,包含:
userID:要设置用户信息的用户 ID。
nickname:昵称信息。
avatarURL:头像链接。

步骤5:创建房间

TUIRoomKit 组件中,RoomMainPage 是集成了完整的多人音视频房间功能的核心界面,以下将向开发者演示如何以房主身份将 RoomMainPage 嵌入到应用中。

实现方式:

1. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
2. 配置房间创建选项:配置房间名称等信息。
3. 初始化房间主页面:通过房主身份初始化房间主页面。
4. 导航到房间页面:将 RoomMainPage 推入导航栈。
说明:
Harmony 目前仅支持创建标准房间,如您需要创建大型研讨会房间,请参考 Web 快速接入 使用 Web 端创建。

示例代码:

import {
RoomMainPage,
RoomBehavior,
ConnectConfig,
EnterRoomParams,
} from '@tencentcloud/tuiroomkit';
import { CreateRoomOptions } from '@tencentcloud/atomicxcore';

@Entry
@Component
struct YourMainPage {
private navStack: NavPathStack = new NavPathStack();

build() {
Navigation(this.navStack) {
Column() {
Button('创建房间')
.onClick(() => this.createRoom())
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
.navDestination(this.routerMap)
.hideTitleBar(true)
}

private createRoom(): void {
// 1. 构造进房的配置项
const config = new ConnectConfig(
true, // autoEnableMicrophone: 进房后是否自动开启麦克风
true, // autoEnableCamera: 进房后是否自动开启摄像头
true, // autoEnableSpeaker: 进房后是否自动开启扬声器
);

// 2. 配置房间创建选项
const options = new CreateRoomOptions();
options.roomName = 'roomName'; // 房间名称

// 3. 配置进房行为(创建房间)
const behavior = RoomBehavior.create(options);

// 4. 导航到房间页面
const params = new EnterRoomParams('123456', behavior, config);
this.navStack.pushPath({ name: 'RoomMain', param: params });
}

@Builder
routerMap(name: string, param: Object) {
if (name === 'RoomMain') {
RoomMainDestination({ navStack: this.navStack, params: param as EnterRoomParams })
}
}
}

@Component
struct RoomMainDestination {
navStack: NavPathStack = new NavPathStack();
params?: EnterRoomParams;

build() {
NavDestination() {
RoomMainPage({
roomID: this.params?.roomID ?? '',
behavior: this.params?.behavior ?? RoomBehavior.join(),
config: this.params?.config ?? new ConnectConfig(),
onExit: () => {
this.navStack.pop();
},
})
}
.hideTitleBar(true)
.width('100%')
.height('100%')
.onBackPressed(() => true)
}
}

RoomMainPage 构造函数参数详细说明:

参数
类型
说明
roomID
string
字符串类型的房间唯一标识符。
限制长度为 0-48 字节。
建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。
behavior
RoomBehavior
房间主页面初始化来源。
参数含义:
create: 房主身份创建房间,此方式需要构造创建房间配置项 CreateRoomOptions。
join:参与者身份加入房间。
config
ConnectConfig
进房后音视频设备控制的配置项。

ConnectConfig 参数详细说明
参数
类型
说明
autoEnableMicrophone
boolean
进房后是否自动开启麦克风。
参数含义:
true: 自动开启 (默认值)。
false: 不自动开启。
autoEnableCamera
boolean
进房后是否自动开启摄像头。
参数含义:
true: 自动开启 (默认值)。
false: 不自动开启。
autoEnableSpeaker
boolean
进房后是否自动开启扬声器。
参数含义:
true: 自动开启 (默认值)。
false: 不自动开启。

步骤6:加入房间

以下示例将向开发者演示如何以参与者身份将 RoomMainPage 嵌入到应用中。

实现方式:

1. 构造进房的配置项:进入房间后是否需要自动打开音视频设备的配置项。
2. 初始化房间主页面:通过参与者身份初始化房间主页面。
3. 导航到房间页面:将 RoomMainPage 推入导航栈。

代码示例:

import {
RoomMainPage,
RoomBehavior,
ConnectConfig,
EnterRoomParams,
} from '@tencentcloud/tuiroomkit';

@Entry
@Component
struct YourMainPage {
private navStack: NavPathStack = new NavPathStack();

build() {
Navigation(this.navStack) {
Column() {
Button('加入房间')
.onClick(() => this.enterRoom())
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
.navDestination(this.routerMap)
.hideTitleBar(true)
}

private enterRoom(): void {
// 1. 构造进房的配置项
const config = new ConnectConfig(
true, // autoEnableMicrophone: 进房后是否自动开启麦克风
true, // autoEnableCamera: 进房后是否自动开启摄像头
true, // autoEnableSpeaker: 进房后是否自动开启扬声器
);

// 2. 配置进房行为(加入房间)
const behavior = RoomBehavior.join();

// 3. 导航到房间页面
const params = new EnterRoomParams('roomID', behavior, config);
this.navStack.pushPath({ name: 'RoomMain', param: params });
}

@Builder
routerMap(name: string, param: Object) {
if (name === 'RoomMain') {
RoomMainDestination({ navStack: this.navStack, params: param as EnterRoomParams })
}
}
}

@Component
struct RoomMainDestination {
navStack: NavPathStack = new NavPathStack();
params?: EnterRoomParams;

build() {
NavDestination() {
RoomMainPage({
roomID: this.params?.roomID ?? '',
behavior: this.params?.behavior ?? RoomBehavior.join(),
config: this.params?.config ?? new ConnectConfig(),
onExit: () => {
this.navStack.pop();
},
})
}
.hideTitleBar(true)
.width('100%')
.height('100%')
.onBackPressed(() => true)
}
}
说明:
使用 TUIRoomKit 组件进入大型研讨会房间时,需确保 Web 端创建的研讨会房间的房间 ID 以 webinar_ 开头。

核心功能

接入 RoomMainPage 代码后,开发者将得到一个完整的多人音视频页面,内部包含成员管理,音视频设备控制,房间信息展示等功能,这是 TUIRoomKit 组件的核心。
标准房间
大型研讨会房间



界面定制

RoomMainPage 房间主页面内功能丰富,可定制化度高,开发者可以根据实际产品需求,对 UI 进行定制化修改,以适配业务交互场景。以下将详细为开发者展示 RoomMainPage 中视图组件,便于开发者快速修改。
标准房间
大型研讨会房间


RoomMainPage 中组件详细说明
组件
功能描述
定制化建议
房间主视图容器,负责协调各子组件的布局与数据流转。
可调整整体背景、安全区域适配、组件显隐逻辑。
顶部导航栏,包含房间信息、摄像头和声音控制、退出房间功能入口。
可替换图标、调整背景透明度、添加自定义按钮(例如录制、 窗口化)。
RoomView
视频流展示区域,采用瀑布流布局管理多个用户视频画面。
可修改布局算法(行列数、间距)、分页指示器样式、空状态视图。
单个视频流单元格,承载用户视频画面与基本信息。
可自定义视频渲染层、用户信息面板(头像、徽章)、互动控件(语音波形)。
底部工具栏,集成麦克风、摄像头、成员管理操作按钮。
可重新排列按钮顺序、修改按钮样式(颜色、尺寸)、添加业务相关功能(例如屏幕分享、会中呼叫、美颜)。

图标定制

接入 TUIRoomKit 组件后,开发者可以根据实际 UI 交互需求直接替换组件下的图标资源,以适配开发者的业务场景。
TUIRoomKit 使用 src/main/resources/base/media 目录管理 UI 所需的图片资源,您可以直接替换该目录下的图片文件来自定义界面所需的图标。

常用的图片文件列表
图标
文件名
说明



room_camera_off.png
摄像头关闭图标



room_camera_on.png
摄像头开启图标



room_mic_off.png
麦克风关闭图标



room_mic_on_empty.png
麦克风开启图标



room_administrator_icon.png
管理员身份标识图标



room_owner_icon.png
房主身份标识图标

文案定制

TUIRoomKit 使用 HarmonyOS 标准的资源文件来管理 UI 所需的文案显示,您可以直接修改 atomic_x/src/main/resources/ 目录下对应语言文件夹中的 string.json 等 JSON 资源文件来调整需要的文案。


常见问题

每次进房都需要调用登录吗?

不需要。通常您只需要完成一次 LoginStore.shared.login 调用即可,我们建议您将 LoginStore.shared.login
LoginStore.shared.logout 与自己的登录业务关联。

oh-package.json5 文件有没有示例配置可以参考?

您可以参考 GitHub TUIKit_Harmony application 工程中的 oh-package.json5 示例文件。