# 实现收发消息 (/zh-CN/realtime-media/rtm/get-started/quick-start/harmonyos) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文将指导你如何利用 RTM HarmonyOS SDK 构建简单的应用程序,内容涵盖了集成和开发的基础知识:开通声网账号、获取 SDK、发送消息、接收消息等。 ## 准备工作 [#准备工作-3] 开始构建项目前,你需要完成[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service),并检查你的开发环境是否满足[平台支持](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/platform-support)中的最低版本要求。 ## 构建项目 [#构建项目-3] ### 1. 获取 SDK [#1-获取-sdk] [点击此处](https://download.shengwang.cn/rtm2/release/RTM_ArkTS_SDK_for_HarmonyOS_v2.3.1.zip)下载最新版本的 HarmonyOS SDK。 下载完成后,解压 SDK 包,你将获得一个 `.har` 文件,这是 HarmonyOS 的静态共享包格式。 :::info[信息] 如果你同时集成了 2.2.0 及以上版本的 RTM SDK 和 4.3.0 及以上版本的 RTC SDK,请参考 [FAQ](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue) 处理集成问题。 ::: ### 2. 项目配置 [#2-项目配置] 根据以下步骤配置你的项目: 1. 在 DevEco Studio 中,创建一个新的 HarmonyOS 应用项目。 2. 将下载的 `.har` 文件导入到你的项目中: - 在项目根目录下创建 `libs` 文件夹(如果不存在) - 将 `.har` 文件复制到 `libs` 文件夹中 - 在模块的 `oh-package.json5` 文件中添加依赖: ```json { "dependencies": { "@shengwang/rtm-full": "file:./libs/AgoraRtmSDK.har" } } ``` 3. 在模块的 `module.json5` 文件中添加网络权限: ```json { "module": { "requestPermissions": [ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.GET_NETWORK_INFO" } ] } } ``` 4. 同步项目依赖,确保 SDK 正确导入。 ### 3. 创建并初始化 RTM [#3-创建并初始化-rtm] 调用 RTM SDK 的任何 API 之前,需要先创建一个 `RtmClient` 对象实例。在你的项目中创建一个 ArkTS 文件(例如 `RtmManager.ets`),添加以下代码作为程序模版。你会发现此程序并不完整,不用紧张,我们在后续步骤中将一步步指导你补充完善代码。 :::info[信息] 你需要在初始化时填入已开通 RTM 服务的项目的 App ID 和 Token。在测试阶段,为快速验证功能,我们建议你在创建声网项目时将鉴权模式设置为调试模式,然后在示例中填入项目的 App ID 即可。 ::: ```typescript import { RtmClient, RtmConfig, RtmChannelType, SubscribeOptions, PublishOptions } from '@shengwang/rtm-full'; import type { LinkStateEvent, MessageEvent, PresenceEvent } from '@shengwang/rtm-full'; import { RtmError } from '@shengwang/rtm-full'; // 填入你的 App ID const APP_ID = ''; // 填入你的 Token(测试阶段可以为空字符串) const TOKEN = ''; export class RtmManager { private rtmClient: RtmClient | null = null; private userId: string = ''; /** * 初始化 RTM 客户端 */ async initialize(userId: string): Promise { try { this.userId = userId; // 创建 RTM 配置 const config: RtmConfig = { appId: APP_ID, userId: userId }; // 创建 RTM 客户端实例 this.rtmClient = new RtmClient(config); // 添加事件监听(后续步骤中补充) console.log('RTM client initialized successfully'); } catch (error) { console.error('Failed to initialize RTM client:', error); if (error instanceof RtmError) { throw new Error(`初始化失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('RTM client initialization failed'); } } } /** * 登录 RTM 服务 */ async login(): Promise { // 后续步骤中补充 } /** * 订阅频道 */ async subscribe(channelName: string): Promise { // 后续步骤中补充 } /** * 取消订阅频道 */ async unsubscribe(channelName: string): Promise { // 后续步骤中补充 } /** * 发送消息 */ async publish(channelName: string, message: string): Promise { // 后续步骤中补充 } /** * 登出 RTM 服务 */ async logout(): Promise { // 后续步骤中补充 } /** * 释放资源 */ release(): void { if (this.rtmClient) { this.rtmClient.release(); this.rtmClient = null; } } } ``` ### 4. 添加事件监听 [#4-添加事件监听] 事件监听程序帮助你实现频道中消息、事件到达后的处理逻辑。在 `initialize` 方法中添加事件监听器,以显示收到的消息或事件通知: ```typescript showLineNumbers // 在 initialize 方法中,创建 RTM 客户端后添加以下代码 // 添加事件监听(替换之前的注释) // 监听连接状态变化 this.rtmClient.addEventListener('linkState', (event) => { console.log('Link state changed:', event); console.log(`State: ${event.previousState} -> ${event.currentState}`); console.log(`Reason: ${event.reason}`); }); // 监听接收到的消息 this.rtmClient.addEventListener('message', (event) => { console.log('Received message:', event); console.log(`From: ${event.publisher}`); console.log(`Channel: ${event.channelName}`); console.log(`Message: ${event.message}`); }); // 监听 Presence 事件(用户加入/离开) this.rtmClient.addEventListener('presence', (event) => { console.log('Presence event:', event); console.log(`Event type: ${event.eventType}`); console.log(`User: ${event.publisher}`); }); ``` ### 5. 登录服务 [#5-登录服务] 你需要执行登录操作才能建立与 RTM 服务器的连接,然后才能调用 SDK 的其他 API。在 `login` 方法中添加以下代码: ```typescript showLineNumbers // 在 login 方法中添加以下代码 async login(): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const response = await this.rtmClient.login(TOKEN); console.log('Login successful:', response); } catch (error) { console.error('Login failed:', error); if (error instanceof RtmError) { throw new Error(`登录失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Login failed'); } } } ``` :::info[信息] 你需要在登录时传入 Token。在测试阶段,为快速验证功能,我们建议你在创建声网项目时将鉴权模式设置为调试模式,然后在登录时传入空字符串即可。 ::: ### 6. 收发消息 [#6-收发消息] 调用 `publish` 方法向 Message Channel 发送消息后,RTM 会把该消息分发给该频道的所有订阅者。以下代码演示如何发送字符串类型的消息: :::info[信息] 你需要先对消息负载进行字符串序列化,才能调用 `publish` 方法发送消息。 ::: ```typescript showLineNumbers // 在 publish 方法中添加以下代码 async publish(channelName: string, message: string): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const options: PublishOptions = { channelType: RtmChannelType.MESSAGE, customType: '' }; const response = await this.rtmClient.publish(channelName, message, options); console.log('Message published successfully:', response); } catch (error) { console.error('Failed to publish message:', error); if (error instanceof RtmError) { throw new Error(`发送消息失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Publish failed'); } } } ``` 调用 `subscribe` 方法订阅此频道以接收此频道中的消息: ```typescript showLineNumbers // 在 subscribe 方法中添加以下代码 async subscribe(channelName: string): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const options: SubscribeOptions = { withMessage: true, withMetadata: false, withPresence: true, withLock: false }; const response = await this.rtmClient.subscribe(channelName, options); console.log('Subscribed to channel successfully:', response); } catch (error) { console.error('Failed to subscribe to channel:', error); if (error instanceof RtmError) { throw new Error(`订阅失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Subscribe failed'); } } } ``` 如果你不再需要在此频道收发消息,你可以调用 `unsubscribe` 方法取消订阅此频道: ```typescript showLineNumbers // 在 unsubscribe 方法中添加以下代码 async unsubscribe(channelName: string): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const response = await this.rtmClient.unsubscribe(channelName); console.log('Unsubscribed from channel successfully:', response); } catch (error) { console.error('Failed to unsubscribe from channel:', error); if (error instanceof RtmError) { throw new Error(`取消订阅失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Unsubscribe failed'); } } } ``` 如需了解更多收发消息的信息,查看[消息](/zh-CN/api-reference/rtm/harmonyos/message)。 ### 7. 登出服务 [#7-登出服务] 当不再需要使用 RTM 服务时,你可以调用 `logout` 方法登出 RTM 系统: ```typescript showLineNumbers // 在 logout 方法中添加以下代码 async logout(): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const response = await this.rtmClient.logout(); console.log('Logout successful:', response); } catch (error) { console.error('Logout failed:', error); if (error instanceof RtmError) { throw new Error(`登出失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Logout failed'); } } } ``` :::info[信息] 本操作会影响你账单中的 PCU 计费项。 ::: ### 8. 组合到一起 [#8-组合到一起] 经过上述步骤,你的完整代码应该如下所示: ```typescript import { RtmClient, RtmConfig, RtmChannelType, SubscribeOptions, PublishOptions } from '@shengwang/rtm-full'; import type { LinkStateEvent, MessageEvent, PresenceEvent } from '@shengwang/rtm-full'; import { RtmError } from '@shengwang/rtm-full'; // 填入你的 App ID const APP_ID = ''; // 填入你的 Token(测试阶段可以为空字符串) const TOKEN = ''; export class RtmManager { private rtmClient: RtmClient | null = null; private userId: string = ''; /** * 初始化 RTM 客户端 */ async initialize(userId: string): Promise { try { this.userId = userId; // 创建 RTM 配置 const config: RtmConfig = { appId: APP_ID, userId: userId }; // 创建 RTM 客户端实例 this.rtmClient = new RtmClient(config); // 监听连接状态变化 this.rtmClient.addEventListener('linkState', (event: object) => { const linkEvent = event as LinkStateEvent; console.log('Link state changed:', linkEvent); console.log(`State: ${linkEvent.previousState} -> ${linkEvent.currentState}`); console.log(`Reason: ${linkEvent.reason}`); }); // 监听接收到的消息 this.rtmClient.addEventListener('message', (event: object) => { const msgEvent = event as MessageEvent; console.log('Received message:', msgEvent); console.log(`From: ${msgEvent.publisher}`); console.log(`Channel: ${msgEvent.channelName}`); console.log(`Message: ${msgEvent.message}`); }); // 监听 Presence 事件(用户加入/离开) this.rtmClient.addEventListener('presence', (event: object) => { const presenceEvent = event as PresenceEvent; console.log('Presence event:', presenceEvent); console.log(`Event type: ${presenceEvent.eventType}`); console.log(`User: ${presenceEvent.publisher}`); }); console.log('RTM client initialized successfully'); } catch (error) { console.error('Failed to initialize RTM client:', error); if (error instanceof RtmError) { throw new Error(`初始化失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('RTM client initialization failed'); } } } /** * 登录 RTM 服务 */ async login(): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const response = await this.rtmClient.login(TOKEN); console.log('Login successful:', response); } catch (error) { console.error('Login failed:', error); if (error instanceof RtmError) { throw new Error(`登录失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Login failed'); } } } /** * 订阅频道 */ async subscribe(channelName: string): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const options: SubscribeOptions = { withMessage: true, withMetadata: false, withPresence: true, withLock: false }; const response = await this.rtmClient.subscribe(channelName, options); console.log('Subscribed to channel successfully:', response); } catch (error) { console.error('Failed to subscribe to channel:', error); if (error instanceof RtmError) { throw new Error(`订阅失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Subscribe failed'); } } } /** * 取消订阅频道 */ async unsubscribe(channelName: string): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const response = await this.rtmClient.unsubscribe(channelName); console.log('Unsubscribed from channel successfully:', response); } catch (error) { console.error('Failed to unsubscribe from channel:', error); if (error instanceof RtmError) { throw new Error(`取消订阅失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Unsubscribe failed'); } } } /** * 发送消息 */ async publish(channelName: string, message: string): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const options: PublishOptions = { channelType: RtmChannelType.MESSAGE, customType: '' }; const response = await this.rtmClient.publish(channelName, message, options); console.log('Message published successfully:', response); } catch (error) { console.error('Failed to publish message:', error); if (error instanceof RtmError) { throw new Error(`发送消息失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Publish failed'); } } } /** * 登出 RTM 服务 */ async logout(): Promise { if (!this.rtmClient) { throw new Error('RTM client not initialized'); } try { const response = await this.rtmClient.logout(); console.log('Logout successful:', response); } catch (error) { console.error('Logout failed:', error); if (error instanceof RtmError) { throw new Error(`登出失败: ${error.reason} (code: ${error.errorCode})`); } else { throw new Error('Logout failed'); } } } /** * 释放资源 */ release(): void { if (this.rtmClient) { this.rtmClient.release(); this.rtmClient = null; } } } ``` 现在,你可以在你的 HarmonyOS 应用中使用这个 `RtmManager` 类。以下是一个简单的页面示例,展示如何在 Index 页面中使用 RTM 功能: ```typescript // Index.ets import { RtmManager } from './RtmManager'; import { RtmChannelType } from '@shengwang/rtm-full'; @Entry @Component struct Index { @State userId: string = ''; @State channelName: string = ''; @State message: string = ''; @State messageHistory: string = ''; @State isLoggedIn: boolean = false; private rtmManager: RtmManager = new RtmManager(); build() { Column() { // 标题 Text('RTM 快速开始') .fontSize(24) .fontWeight(FontWeight.Bold) .margin({ top: 20, bottom: 20 }) // 用户 ID 输入 Row() { Text('用户 ID:') .width(80) TextInput({ placeholder: '请输入用户 ID' }) .layoutWeight(1) .onChange((value: string) => { this.userId = value; }) } .width('90%') .margin({ bottom: 10 }) // 登录/登出按钮 Row() { Button(this.isLoggedIn ? '登出' : '登录') .width('45%') .onClick(() => { if (this.isLoggedIn) { this.handleLogout(); } else { this.handleLogin(); } }) } .width('90%') .margin({ bottom: 20 }) Divider() .margin({ bottom: 20 }) // 频道名输入 Row() { Text('频道名:') .width(80) TextInput({ placeholder: '请输入频道名' }) .layoutWeight(1) .onChange((value: string) => { this.channelName = value; }) } .width('90%') .margin({ bottom: 10 }) // 订阅/取消订阅按钮 Row() { Button('订阅') .width('45%') .onClick(() => { this.handleSubscribe(); }) .enabled(this.isLoggedIn) Button('取消订阅') .width('45%') .onClick(() => { this.handleUnsubscribe(); }) .enabled(this.isLoggedIn) } .width('90%') .justifyContent(FlexAlign.SpaceBetween) .margin({ bottom: 20 }) // 消息输入 Row() { Text('消息:') .width(80) TextInput({ placeholder: '请输入消息内容' }) .layoutWeight(1) .onChange((value: string) => { this.message = value; }) } .width('90%') .margin({ bottom: 10 }) // 发送消息按钮 Button('发送消息') .width('90%') .onClick(() => { this.handlePublish(); }) .enabled(this.isLoggedIn) .margin({ bottom: 20 }) Divider() .margin({ bottom: 10 }) // 消息历史 Text('消息历史:') .fontSize(16) .fontWeight(FontWeight.Bold) .alignSelf(ItemAlign.Start) .margin({ left: '5%', bottom: 10 }) Scroll() { Text(this.messageHistory) .width('100%') .padding(10) } .width('90%') .height(200) .backgroundColor('#F0F0F0') .borderRadius(8) } .width('100%') .height('100%') .padding({ top: 20 }) } // 登录处理 async handleLogin() { if (!this.userId) { this.addMessage('请输入用户 ID'); return; } try { await this.rtmManager.initialize(this.userId); await this.rtmManager.login(); this.isLoggedIn = true; this.addMessage(`用户 ${this.userId} 登录成功`); } catch (error) { this.addMessage(`登录失败: ${error}`); } } // 登出处理 async handleLogout() { try { await this.rtmManager.logout(); this.rtmManager.release(); this.isLoggedIn = false; this.addMessage('登出成功'); } catch (error) { this.addMessage(`登出失败: ${error}`); } } // 订阅频道 async handleSubscribe() { if (!this.channelName) { this.addMessage('请输入频道名'); return; } try { await this.rtmManager.subscribe(this.channelName); this.addMessage(`订阅频道 ${this.channelName} 成功`); } catch (error) { this.addMessage(`订阅失败: ${error}`); } } // 取消订阅频道 async handleUnsubscribe() { if (!this.channelName) { this.addMessage('请输入频道名'); return; } try { await this.rtmManager.unsubscribe(this.channelName); this.addMessage(`取消订阅频道 ${this.channelName} 成功`); } catch (error) { this.addMessage(`取消订阅失败: ${error}`); } } // 发送消息 async handlePublish() { if (!this.channelName) { this.addMessage('请输入频道名'); return; } if (!this.message) { this.addMessage('请输入消息内容'); return; } try { await this.rtmManager.publish(this.channelName, this.message); this.addMessage(`发送消息到 ${this.channelName}: ${this.message}`); } catch (error) { this.addMessage(`发送消息失败: ${error}`); } } // 添加消息到历史记录 addMessage(msg: string) { const timestamp = new Date().toLocaleTimeString(); this.messageHistory += `[${timestamp}] ${msg}\n`; } } ``` 这个示例展示了如何: 1. **创建 RTM 管理器实例**:在组件中创建 `RtmManager` 实例 2. **用户登录**:输入用户 ID,点击登录按钮初始化并登录 RTM 3. **订阅频道**:输入频道名,点击订阅按钮订阅消息频道 4. **发送消息**:输入消息内容,点击发送按钮向频道发送消息 5. **取消订阅**:点击取消订阅按钮退出频道 6. **用户登出**:点击登出按钮断开 RTM 连接 你也可以使用更简单的方式来测试 RTM 功能: ```typescript // 在你的页面或组件中使用 import { RtmManager } from './RtmManager'; // 创建 RTM 管理器实例 const rtmManager = new RtmManager(); // 初始化并登录 await rtmManager.initialize('user123'); await rtmManager.login(); // 订阅频道 await rtmManager.subscribe('test-channel'); // 发送消息 await rtmManager.publish('test-channel', 'Hello, RTM!'); // 取消订阅 await rtmManager.unsubscribe('test-channel'); // 登出 await rtmManager.logout(); // 释放资源 rtmManager.release(); ``` 至此,你已经成功集成并正确使用了 RTM 服务。 ## 贯穿始终 [#贯穿始终-3] 相比于介绍如何写出代码,声网更愿意帮助你掌握上述程序编写的过程和逻辑。上述程序依次完成了以下操作,让你可以正确地收发消息: 1. 创建并初始化 RTM 对象。 2. 添加 `linkState`、`message` 和 `presence` 事件监听函数。 3. 调用 `login` 登录了 RTM 服务。 4. 调用 `subscribe` 订阅了一个 Message Channel。 5. 调用 `publish` 发送消息。 6. 调用 `unsubscribe` 取消订阅一个 Message Channel。 7. 调用 `logout` 登出 RTM 系统。 ## 下一步 [#下一步-3] 现在,你已经学会了如何使用 RTM HarmonyOS SDK 来实现 Message Channel 的收发消息功能。下一步,你可以通过 SDK 的 [API 参考](/zh-CN/api-reference/rtm/harmonyos/configuration)了解更多功能的使用方法。