RoomStore 是 AtomicXCore 的房间管理核心模块,涵盖了预定房间体系。本章节详细介绍了如何利用 RoomStore 高效完成预定房间功能的开发与接入。核心功能
预定、取消预定房间:任何用户均可完成预定房间,取消预定房间功能。
更新预定房间信息:对已预定的房间进行房间信息更新,包含:房间名称,开始时间,结束时间。
获取预定房间列表:获取当前账户下所有预定的房间列表信息。
获取预定房间的参与成员列表:获取指定预定房间的参与成员列表信息。
添加、移除预定房间参与成员:对已预定的房间可以添加、移除参与成员。
核心概念
在开始集成之前,您可能需要通过下表了解一下
RoomStore中与预订房间相关的几个核心概念:核心概念 | 类型 | 核心职责与描述 |
enum | 代表当前房间的状态,包含: scheduled(预定状态)。 running(进行中)。 | |
struct | 代表预定房间的核心数据结构,包含:开始时间,结束时间,预定成员列表等。 | |
struct | 代表房间状态管理的核心数据结构,负责维护用户的房间相关状态信息。 核心属性: scheduledRoomList存储了当前账号下所有预定的房间列表信息。scheduledRoomListCursor 则代表预定房间列表的分页游标。 | |
enum | 代表房间动态的实时事件。其中包含预定房间相关的事件。 | |
class | 这是与房间全生命周期相关的核心类。通过它,您可以主动发起预定房间,获取预定房间列表等功能,并通过订阅其 roomEventPublisher 来接收与预定房间相关的实时动态事件。 |
实现步骤
步骤1:组件集成
步骤2:预定房间功能
一、预定房间
实现方式:
1. 配置预定房间初始化参数:初始化
ScheduleRoomOptions预定房间配置项设置房间命名,房间密码、开始时间、结束时间、参与者、房间信息等。2. 房间权限预设:设置房间内全场成员权限,例如全体静音,全体禁画等。
3. 预定房间:调用
RoomStore的scheduleRoom接口执行核心操作。示例代码:
import AtomicXCoreimport Foundation// 预定房间func scheduleRoom() {let startTime = Int(Date().timeIntervalSince1970) + 60 * 15 // 计算预定时间:当前时间 + 15分钟后开始let endTime = startTime + 60 * 30 // 计算结束时间:开始时间 + 30分钟(房间持续30分钟)let reminderSeconds = 60 * 5 // 设置提醒时间:房间开始前5分钟提醒// 创建预定房间选项配置var options = ScheduleRoomOptions()options.roomName = "房间名称"options.scheduleStartTime = startTimeoptions.scheduleEndTime = endTimeoptions.reminderSecondsBeforeStart = reminderSecondsoptions.scheduleAttendees = ["user01", "user02", "user03"] // 设置预定参与者列表(用户ID数组)options.password = "房间密码" // 设置房间密码(可选,空字符串表示无密码)options.isAllMicrophoneDisabled = false // 设置是否默认禁用所有参与者的麦克风(false = 允许开启麦克风)options.isAllCameraDisabled = false // 设置是否默认禁用所有参与者的摄像头(false = 允许开启摄像头)options.isAllScreenShareDisabled = false // 设置是否默认禁用所有参与者的屏幕共享(false = 允许屏幕共享)options.isAllMessageDisabled = false // 设置是否默认禁用所有参与者的消息功能(false = 允许发送消息)RoomStore.shared.scheduleRoom(roomID: "roomID", options: options) { result inswitch result {case .success:print("预定房间成功")case .failure(let error):print("预定房间失败: [错误码: \\(error.code)] \\(error.message)")}}}
scheduleRoom 接口参数详细说明
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
options | ScheduleRoomOptions | 是 | 创建房间配置对象。 详细用法请参考:ScheduleRoomOptions 结构体详细说明 |
completion | CompletionClosure | 否 | 操作完成回调,用于返回预定房间的结果。若预定失败则会返回错误码和错误信息。 |
ScheduleRoomOptions 结构体详细说明
参数名 | 类型 | 必填 | 说明 |
roomName | String | 否 | 房间名称,可以不设置,默认为空字符串。 限制长度为 0-60 字节。 支持中英文、数字、特殊字符。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |
scheduleStartTime | Int | 是 | 预定的房间开始时间(Unix 时间戳,单位:秒)。 取值必须大于当前时间。 推荐设置为未来的整分时间。例如:1736164800(代表 2025-01-06 20:00:00)。 |
scheduleEndTime | Int | 是 | 预定的房间结束时间(Unix 时间戳,单位:秒)。 取值必须大于 scheduleStartTime。建议根据预期时长设置。例如: scheduleStartTime + 3600(预定 1 小时时长的房间)。 |
reminderSecondsBeforeStart | Int | 否 | 房间开始前的提醒时间(单位:秒)。用于系统触发开始提醒。 推荐设置为 300(5分钟)或 900(15分钟),用于在 App 端触发本地通知。 |
scheduleAttendees | [String] | 否 | 预定参与者的用户 ID 列表,在预定房间时设置,系统将向这些用户发送预约邀请。 获取请参考获取指定预定房间的参与成员列表。 |
isAllMicrophoneDisabled | Bool | 否 | 是否全员禁止打开麦克风。开启后,除房主/管理员外,普通参与者默认禁止打开麦克风。 true : 禁止 false :取消禁止 (默认值) |
isAllCameraDisabled | Bool | 否 | 是否全员禁止打开摄像头。开启后,除房主/管理员外,普通参与者默认禁止打开摄像头。 true : 禁止 false :取消禁止(默认值) |
isAllScreenShareDisabled | Bool | 否 | 是否全员禁止发起屏幕共享。开启后,仅房主/管理员可进行屏幕共享。 true : 禁止 false :取消禁止(默认值) |
isAllMessageDisabled | Bool | 否 | 是否全员禁止发送聊天消息(禁言)。开启后,普通参与者无法在房间内发送文字消息。 true : 禁止 false :取消禁止(默认值) |
二、取消房间预定
房间预定者调用
RoomStore的cancelScheduledRoom接口,实现取消预定房间功能。import AtomicXCoreimport Foundation// 取消房间预定func cancelScheduledRoom(roomID: String) {RoomStore.shared.cancelScheduledRoom(roomID: roomID) { result inswitch result {case .success:print("取消预定房间成功")case .failure(let error):print("取消预定房间失败: [错误码: \\(error.code)] \\(error.message)")}}}
三、更新预定房间
房间预定者调用
RoomStore的updateScheduledRoom接口,实现更新预约房间名称、开始时间、结束时间。import AtomicXCoreimport Foundation// 更新预定房间func updateScheduledRoom() {let newStartTime = Int(Date().timeIntervalSince1970) + 60 * 30 // 计算预定时间:当前时间 + 30分钟后开始let newEndTime = newStartTime + 60 * 45 // 计算结束时间:开始时间 + 45分钟(房间持续30分钟)var options = ScheduleRoomOptions()options.roomName = "房间名称"options.scheduleStartTime = newStartTimeoptions.scheduleEndTime = newEndTimevar modifyFlag: ScheduleRoomOptions.ModifyFlag = []modifyFlag.insert(.roomName)modifyFlag.insert(.scheduleStartTime)modifyFlag.insert(.scheduleEndTime)RoomStore.shared.updateScheduledRoom(roomID: "roomID", options: options, modifyFlag: modifyFlag) { result inswitch result {case .success:print("更新预定房间成功")case .failure(let error):print("更新预定房间失败: [错误码: \\(error.code)] \\(error.message)")}}}
updateScheduledRoom 接口参数详细说明
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
options | ScheduleRoomOptions | 是 | 预定房间配置对象。 详细用法请参考:ScheduleRoomOptions 结构体详细说明 |
modifyFlag | ScheduleRoomOptions.ModifyFlag | 是 | 更新房间属性修改标志位。目前支持更新房间名称、开始时间、结束时间。 详细用法请参考:ScheduleRoomOptions.ModifyFlag 详细说明。 |
completion | CompletionClosure | 否 | 操作完成回调,用于返回更新预定房间的结果。若更新失败则会返回错误码和错误信息。 |
ScheduleRoomOptions.ModifyFlag 详细说明
参数名 | 类型 | 说明 |
roomName | UInt | 修改预定房间名称时的标识位。 当修改 ScheduleRoomOptions中的roomName后,需要同步设置ModifyFlag的roomName标识位。 |
scheduleStartTime | UInt | 修改预定房间开始时间时的标识位。 当修改 ScheduleRoomOptions中的scheduleStartTime后,需要同步设置ModifyFlag的scheduleStartTime标识位。 |
scheduleEndTime | UInt | 修改预定房间结束时间时的标识位。 当修改 ScheduleRoomOptions中的scheduleEndTime后,需要同步设置ModifyFlag的scheduleEndTime标识位。 |
四、添加、删除参与成员
房间预定者调用
RoomStore的addScheduledAttendees或者removeScheduledAttendees接口,可以为已预约的房间内批量添加或移除预约参与者。import AtomicXCoreimport Foundation// 添加参与成员func addScheduledAttendees(roomID: String, userIDList: [String]) {RoomStore.shared.addScheduledAttendees(roomID: roomID, userIDList: userIDList) { result inguard let self = self else { return }switch result {case .success:print("添加预定参与者成功")case .failure(let error):print("添加预定参与者失败: [错误码: \\(error.code)] \\(error.message)")}}}// 移除参与成员func removeScheduledAttendees(roomID: String, userIDList: [String]) {RoomStore.shared.removeScheduledAttendees(roomID: roomID, userIDList: userIDList) { result inswitch result {case .success:print("移除预定参与者成功")case .failure(let error):print("移除预定参与者失败: [错误码: \\(error.code)] \\(error.message)")}}}
步骤3:获取预定房间列表
任意用户调用
RoomStore的getScheduledRoomList接口,均可获取到自己账号下所有预约的房间列表信息。import AtomicXCoreimport Foundation// 获取预定房间列表func getScheduledRoomList(cursor: String? = nil) {// cursor 为分页游标,首次调用时传入 null,获取第一页数据, 后续调用时传入上次返回的 nextCursor 值RoomStore.shared.getScheduledRoomList(cursor: cursor) { result inswitch result {case .success(let (roomList, nextCursor)):print("获取预定房间列表成功")case .failure(let error):print("获取预定房间列表失败: [错误码: \\(error.code)] \\(error.message)")}}}
步骤4:获取指定预定房间的参与成员列表
任意用户调用
RoomStore的getScheduledAttendees接口,可获取到指定预约房间的参与成员列表信息。import AtomicXCoreimport Foundation// 获取预定房间的参与者列表func getScheduledAttendees(roomID: String, cursor: String? = nil) {// cursor 为分页游标,首次调用时传入 null,获取第一页数据, 后续调用时传入上次返回的 nextCursor 值RoomStore.shared.getScheduledAttendees(roomID: roomID, cursor: cursor) { result inswitch result {case .success(let (attendees, nextCursor)):print("获取预定房间参与者列表成功")case .failure(let error):print("获取预定房间参与者列表失败: [错误码: \\(error.code)] \\(error.message)")}}}
步骤5:监听预定房间实时事件及状态变化
订阅
RoomEvent预定房间相关的被动事件,示例代码如下:import AtomicXCoreimport Foundationimport Combineprivate var cancellableSet = Set<AnyCancellable>()/// 订阅预定房间相关事件private func subscribeScheduledRoomEvents() {RoomStore.shared.roomEventPublisher.receive(on: DispatchQueue.main).sink { event inswitch event {case .onAddedToScheduledRoom(let roomInfo):print("已被添加到预定房间 房间信息: \\(roomInfo)")case .onRemovedFromScheduledRoom(let roomInfo, let operatorUser):print("已被移除预定房间 房间信息: \\(roomInfo), 移除者: \\(operatorUser)")case .onScheduledRoomCancelled(let roomInfo, let operatorUser):print("预定房间被取消 房间信息: \\(roomInfo), 取消者: \\(operatorUser)")case .onScheduledRoomStartingSoon(let roomInfo):print("预定房间即将开始 房间信息: \\(roomInfo)")default:// 处理其他非预定房间相关事件break}}.store(in: &cancellableSet)}
订阅
RoomState预定房间列表状态变化,示例代码如下:import AtomicXCoreimport Foundationimport Combineprivate var cancellableSet = Set<AnyCancellable>()/// 订阅预定房间列表状态变化private func subscribeScheduledRoomListState() {RoomStore.shared.state.subscribe(StatePublisherSelector(keyPath: \\.scheduledRoomList)).receive(on: DispatchQueue.main).sink { scheduledRoomList inprint("预定房间列表变化 房间列表信息: \\(scheduledRoomList)")}.store(in: &cancellableSet)}
API 文档
Store/Component | 功能描述 | API文档 |
RoomStore | 房间全生命周期管理:创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 房间预定 / 呼叫房间外成员 / 监听房间内被动事件(例如房间解散,房间信息更新等)。 |
常见问题
当预约房间后,无法收到RoomEvent的onScheduledRoomStartingSoon事件。
如果您在预约房间后未收到即将开始的事件通知,请按照以下两个核心要点进行检查:
1. 检查提醒参数配置 (
reminderSecondsBeforeStart)触发机制:
onScheduledRoomStartingSoon 事件的触发高度依赖于预约配置类 ScheduleRoomOptions 中的 reminderSecondsBeforeStart 属性。默认行为:该属性的默认值为 0,代表“不开启提醒”。
解决建议:请确保在预约房间时明确设置该参数。该参数单位为秒,表示在房间开始前多少秒推送事件通知。
2. 验证预约时间逻辑
计算公式:系统触发提醒的前提是:预约开始时间 (
scheduleStartTime) - 当前时间 > 提醒偏移量 (reminderSecondsBeforeStart)。场景说明:如果您的房间开始时间设置得过近(例如 5 分钟后开始),而提醒时间设置得过大(例如设置 10 分钟前提醒),系统将无法捕捉到触发时机,从而导致事件丢失。
解决建议:请确保预约的开始时间距离当前时刻,大于您所设置的提醒秒数。