TUIRoomKit 是腾讯云提供的一站式多人音视频房间解决方案,集成了完整的 UI 组件和核心功能。通过本文档,开发者可以快速了解如何将 TUIRoomKit 集成到项目中,实现多人音视频房间功能。本文还将详细介绍如何快速替换图片资源、本地化文案等个性化配置,帮助开发者打造符合品牌特色的音视频应用。
房间准备页 | 标准房间主页 | 大型研讨会房间主页 | 成员管理 |
![]() | ![]() | ![]() | ![]() |
前提条件
开通服务
SDKAppID:应用标识(必填),腾讯云基于 SDKAppID 完成计费统计。
SDKSecretKey:应用密钥,用于初始化配置文件的密钥信息。
环境准备
集成开发环境:6.0.0.858 或以上。
手机操作系统:HarmonyOS 5.0.5 或以上。
API Version:17 或以上。
快速接入
步骤1:集成 TUIRoomKit 组件
下载源码
git clone https://github.com/Tencent-RTC/TUIKit_Harmony.git
集成组件
1. 将组件目录完整复制到您的鸿蒙项目中,如下图所示,其中 application 是示例项目,room 和 atomic_x 是从 GitHub 上下载的组件源码。

2. 在您的工程
entry 的 oh-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 的登录服务。这样可以避免因过早调用登录服务,导致业务逻辑混乱或数据不一致的问题,同时也能更好地适配您项目中现有的用户管理和权限控制体系。
import { LoginStore } from '@tencentcloud/atomicxcore'try {await LoginStore.shared().login(1400000000, // 替换为您的 SDKAPPID'userID', // 替换为您的 UserID'userSig', // 替换为您的 UserSig);// login success} catch (error) {// login error}
登录接口参数说明:
参数 | 类型 | 说明 |
sdkAppID | number | |
userID | string | 当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1、123 等简单 ID。 |
userSig | string | 【注意事项】 开发环境:可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 UserSig 辅助工具 生成临时的 userSig。生产环境:为了防止密钥泄露,请务必采用服务端生成 userSig 的方式。详细信息请参考 服务端生成 UserSig。 |
步骤4:设置头像和昵称
首次登录的用户没有头像和昵称信息,需要通过
LoginStore 的 setSelfInfo 接口设置个人信息: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 推入导航栈。说明:
示例代码:
import {RoomMainPage,RoomBehavior,ConnectConfig,EnterRoomParams,} from '@tencentcloud/tuiroomkit';import { CreateRoomOptions } from '@tencentcloud/atomicxcore';@Entry@Componentstruct 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 });}@BuilderrouterMap(name: string, param: Object) {if (name === 'RoomMain') {RoomMainDestination({ navStack: this.navStack, params: param as EnterRoomParams })}}}@Componentstruct 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@Componentstruct 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 });}@BuilderrouterMap(name: string, param: Object) {if (name === 'RoomMain') {RoomMainDestination({ navStack: this.navStack, params: param as EnterRoomParams })}}}@Componentstruct 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 中组件详细说明组件 | 功能描述 | 定制化建议 |
房间主视图容器,负责协调各子组件的布局与数据流转。 | 可调整整体背景、安全区域适配、组件显隐逻辑。 | |
顶部导航栏,包含房间信息、摄像头和声音控制、退出房间功能入口。 | 可替换图标、调整背景透明度、添加自定义按钮(例如录制、 窗口化)。 | |
视频流展示区域,采用瀑布流布局管理多个用户视频画面。 | 可修改布局算法(行列数、间距)、分页指示器样式、空状态视图。 | |
单个视频流单元格,承载用户视频画面与基本信息。 | 可自定义视频渲染层、用户信息面板(头像、徽章)、互动控件(语音波形)。 | |
底部工具栏,集成麦克风、摄像头、成员管理操作按钮。 | 可重新排列按钮顺序、修改按钮样式(颜色、尺寸)、添加业务相关功能(例如屏幕分享、会中呼叫、美颜)。 |
图标定制
接入 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 文件有没有示例配置可以参考?













