即时通信 IM HarmonyOS（快速接入 含 UI ）

二、开通服务

请参考 开通服务 领取 TUIRoomKit 体验版，并在 应用管理 页面获取以下信息：

·SDKAppID：应用标识（必填），腾讯云基于 SDKAppID 完成计费统计。

·SDKSecretKey：应用密钥，用于初始化配置文件的密钥信息。

三、环境准备

·集成开发环境：6.0.0.858 或以上。

·手机操作系统：HarmonyOS 5.0.5 或以上。

·API Version：17 或以上。

六、下载源码

从 GitHub 或者 CNB 下载 TUIKit Harmony 源码：

github:git clone https://github.com/Tencent-RTC/TUIKit_Harmony.gitcnb:git clone https://cnb.cool/tencent/cloud/trtc/TUIKit_Harmony

七、集成组件

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 会自动安装所需的依赖库。

八、步骤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" } }, { "name" : "ohos.permission.KEEP_BACKGROUND_RUNNING" },]

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. 声明 backgroundModes。在承载会议界面的 UIAbility（通常是 EntryAbility）下，给 module.json5 的 abilities 节点添加 backgroundModes：

"abilities": [ { "name": "EntryAbility", // … 其他配置保持不变 "backgroundModes": [ "audioRecording", "audioPlayback" ] }]

九、步骤3：登录

代码集成完成后，需要完成登录操作，这是使用 TUIRoomKit 的关键步骤。只有在登录成功后，才能正常使用 TUIRoomKit 的各项功能，因此请仔细检查相关参数配置是否正确：

注意：说明：

注意：在示例代码中，直接进行了登录接口的调用。但在实际项目场景下，强烈推荐你在完成自己的用户身份验证等相关登录操作后，再调用 TUIRoomKit 的登录服务。这样可以避免因过早调用登录服务，导致业务逻辑混乱或数据不一致的问题，同时也能更好地适配你项目中现有的用户管理和权限控制体系。

ArkTSimport { LoginStore } from '@tencentcloud/atomicxcore'try { await LoginStore.shared().login( 1400000000, // 替换为你的 SDKAPPID 'userID', // 替换为你的 UserID 'userSig', // 替换为你的 UserSig ); // login success} catch (error) { // login error}

登录接口参数说明：

十、步骤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 接口参数/返回值说明：

十一、步骤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@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 }); } @Builder routerMap(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 构造函数参数详细说明：

ConnectConfig 参数详细说明：

十四、步骤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 }); } @Builder routerMap(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 构造函数参数详细说明 和 ConnectConfig 参数详细说明。

注意：说明：

注意：使用 TUIRoomKit 组件进入大型研讨会房间时，需确保 Web 端创建的研讨会房间的房间 ID 以 webinar_ 开头。

十七、AI 助手：知识咨询与代码集成

你在接入视频会议 SDK 过程中，可以通过 MCP 使用 AI 助手，快速完成知识咨询、报错排查和集成代码生成。支持 Web/Android/iOS/Flutter/uni-app/HarmonyOS 等平台，答案基于产品文档。适用于查询 Room 组件和 AtomicXCore SDK 用法以及集成文档等场景，立即体验，提出你的第一个问题。

十八、核心功能

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

十九、界面定制

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

RoomMainPage 中组件详细说明

20、图标定制

接入 TUIRoomKit 组件后，开发者可以根据实际 UI 交互需求直接替换组件下的图标资源，以适配开发者的业务场景。

TUIRoomKit 使用 src/main/resources/base/media 目录管理 UI 所需的图片资源，你可以直接替换该目录下的图片文件来自定义界面所需的图标。

常用的图片文件列表

21、文案定制

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

23、每次进房都需要调用登录吗？

不需要。通常你只需要完成一次 LoginStore.shared.login 调用即可，我们建议你将 LoginStore.shared.login 和

LoginStore.shared.logout 与自己的登录业务关联。

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

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