即时通信 IM 预定房间（Flutter）

一、核心功能

·预定、取消预定房间：任何用户均可完成预定房间，取消预定房间功能。

·更新预定房间信息：对已预定的房间进行房间信息更新，包含：房间名称，开始时间，结束时间。

·获取预定房间列表：获取当前账户下所有预定的房间列表信息。

·获取预定房间的参与成员列表：获取指定预定房间的参与成员列表信息。

·添加、移除预定房间参与成员：对已预定的房间可以添加、移除参与成员。

二、核心概念

在开始集成之前，你可能需要通过下表了解一下RoomStore中与预定房间相关的几个核心概念：

三、步骤1：组件集成

请参考 接入概览 集成 AtomicXCore SDK，并已完成 实现登录逻辑 部分接入。

四、一、预定房间

实现方式：

1. 配置预定房间初始化参数：初始化 ScheduleRoomOptions 预定房间配置项设置房间名称，房间密码、开始时间、结束时间、参与者、房间信息等。

2. 房间权限预设：设置房间内全场成员权限，例如全体静音，全体禁画等。

3. 预定房间：调用 RoomStore 的 scheduleRoom 接口执行核心操作。

示例代码：

import 'package:atomic_x_core/atomicxcore.dart';Future<void> scheduleRoom() async { final startTime = DateTime.now().millisecondsSinceEpoch ~/ 1000 + 60 * 15; // 计算开始时间：当前时间 + 15分钟后开始 final endTime = startTime + 60 * 30; // 计算结束时间：开始时间 + 30分钟（房间持续30分钟） final reminderSeconds = 60 * 5; // 设置提醒时间：房间开始前5分钟提醒 // 创建预定房间选项配置 final options = ScheduleRoomOptions( roomName: "房间名称", scheduleStartTime: startTime, scheduleEndTime: endTime, reminderSecondsBeforeStart: reminderSeconds, scheduleAttendees: ["user01", "user02", "user03"], // 设置预定参与者列表（用户ID数组） password: "房间密码", // 设置房间密码（可选，空字符串表示无密码） isAllMicrophoneDisabled: false, // 设置是否默认禁用所有参与者的麦克风（false = 允许开启麦克风） isAllCameraDisabled: false, // 设置是否默认禁用所有参与者的摄像头（false = 允许开启摄像头） isAllScreenShareDisabled: false, // 设置是否默认禁用所有参与者的屏幕共享（false = 允许屏幕共享） isAllMessageDisabled: false, // 设置是否默认禁用所有参与者的消息功能（false = 允许发送消息） ); final result = await RoomStore.shared.scheduleRoom( roomID: "roomID", options: options, ); if (result.isSuccess) { print("预定房间成功"); } else { print("预定房间失败: [错误码: ${result.errorCode}] ${result.errorMessage}"); }}

scheduleRoom 接口参数详细说明

ScheduleRoomOptions 结构体详细说明

五、二、取消房间预定

·预定房间者：调用RoomStore的cancelScheduledRoom接口，实现取消预定房间功能。

import 'package:atomic_x_core/atomicxcore.dart';Future<void> cancelScheduledRoom(String roomID) async { final result = await RoomStore.shared.cancelScheduledRoom(roomID); if (result.isSuccess) { print("取消预定房间成功"); } else { print("取消预定房间失败: [错误码: ${result.errorCode}] ${result.errorMessage}"); }}

六、三、更新预定房间

·房间预定者：调用RoomStore的updateScheduledRoom接口，实现更新预定房间名称、开始时间、结束时间。

import 'package:atomic_x_core/atomicxcore.dart';Future<void> updateScheduledRoom() async { final newStartTime = DateTime.now().millisecondsSinceEpoch ~/ 1000 + 60 * 30; // 计算预定时间：当前时间 + 30分钟后开始 final newEndTime = newStartTime + 60 * 45; // 计算结束时间：开始时间 + 45分钟（房间持续45分钟） final options = ScheduleRoomOptions( roomName: "房间名称", scheduleStartTime: newStartTime, scheduleEndTime: newEndTime, ); final modifyFlagList = [ ScheduleRoomOptionsModifyFlag.roomName, ScheduleRoomOptionsModifyFlag.scheduleStartTime, ScheduleRoomOptionsModifyFlag.scheduleEndTime, ]; final result = await RoomStore.shared.updateScheduledRoom( roomID: "roomID", options: options, modifyFlagList: modifyFlagList, ); if (result.isSuccess) { print("更新预定房间成功"); } else { print("更新预定房间失败: [错误码: ${result.errorCode}] ${result.errorMessage}"); }}

updateScheduledRoom 接口参数详细说明

ScheduleRoomOptionsModifyFlag 详细说明

七、四、添加、删除参与成员

·预定房间者：调用 RoomStore 的 addScheduledAttendees 或者 removeScheduledAttendees 接口，可以为已预定的房间内批量添加或移除预定参与者。

import 'package:atomic_x_core/atomicxcore.dart';Future<void> addScheduledAttendees(String roomID, List<String> userIDList) async { final result = await RoomStore.shared.addScheduledAttendees( roomID: roomID, userIDList: userIDList, ); if (result.isSuccess) { print("添加预定参与者成功"); } else { print("添加预定参与者失败: [错误码: ${result.errorCode}] ${result.errorMessage}"); }}Future<void> removeScheduledAttendees(String roomID, List<String> userIDList) async { final result = await RoomStore.shared.removeScheduledAttendees( roomID: roomID, userIDList: userIDList, ); if (result.isSuccess) { print("移除预定参与者成功"); } else { print("移除预定参与者失败: [错误码: ${result.errorCode}] ${result.errorMessage}"); }}

八、步骤3：获取预定房间列表

·任意用户：调用RoomStore的getScheduledRoomList接口，均可获取到自己账号下所有预定的房间列表信息。

import 'package:atomic_x_core/atomicxcore.dart';/// 获取预定房间列表Future<void> getScheduledRoomList({String? cursor}) async { /// [cursor] 为分页游标，首次调用时传入 null，获取第一页数据， 后续调用时传入上次返回的 nextCursor 值 final result = await RoomStore.shared.getScheduledRoomList(cursor); if (result.isSuccess) { final roomList = result.data; final nextCursor = result.cursor; print("获取预定房间列表成功"); } else { print("获取预定房间列表失败: [错误码: ${result.errorCode}] ${result.errorMessage}"); }}

九、步骤4：获取指定预定房间的参与成员列表

·任意用户：调用RoomStore的getScheduledAttendees接口，可获取到指定预定房间的参与成员列表信息。

import 'package:atomic_x_core/atomicxcore.dart';/// 获取预定房间的参与者列表/// – [roomID]: 房间ID，用于标识要查询参与者列表的预定房间/// – [cursor] 为分页游标，首次调用时传入 null，获取第一页数据， 后续调用时传入上次返回的 nextCursor 值Future<void> getScheduledAttendees(String roomID, {String? cursor}) async { final result = await RoomStore.shared.getScheduledAttendees( roomID: roomID, cursor: cursor, ); if (result.isSuccess) { final attendees = result.data; final nextCursor = result.cursor; print("获取预定房间参与者列表成功"); } else { print("获取预定房间参与者列表失败: [错误码: ${result.errorCode}] ${result.errorMessage}"); }}

十、步骤5：监听预定房间事件及状态

·订阅RoomEvent预定房间相关的被动事件，示例代码如下：

import 'package:atomic_x_core/atomicxcore.dart';late RoomListener _roomListener;/// 订阅预定房间相关事件void subscribeScheduledRoomEvents() { _roomListener = RoomListener( onAddedToScheduledRoom: (roomInfo) { print("已被添加到预定房间 房间信息: $roomInfo"); }, onRemovedFromScheduledRoom: (roomInfo, operatorUser) { print("已被移除预定房间 房间信息: $roomInfo, 移除者: $operatorUser"); }, onScheduledRoomCancelled: (roomInfo, operatorUser) { print("预定房间被取消 房间信息: $roomInfo, 取消者: $operatorUser"); }, onScheduledRoomStartingSoon: (roomInfo) { print("预定房间即将开始 房间信息: $roomInfo"); }, onRoomEnded: (roomInfo) { print("房间已结束 房间信息: $roomInfo"); }, ); RoomStore.shared.addRoomListener(_roomListener);}/// 取消订阅预定房间相关事件void unsubscribeScheduledRoomEvents() { RoomStore.shared.removeRoomListener(_roomListener);}

·订阅RoomState预定房间列表状态变化，示例代码如下：

import 'package:flutter/material.dart';import 'package:atomic_x_core/atomicxcore.dart';/// 订阅预定房间列表状态变化Widget buildScheduledRoomListWidget() { return ValueListenableBuilder( valueListenable: RoomStore.shared.state.scheduledRoomList, builder: (context, scheduledRoomList, child) { print("预定房间列表变化 房间列表信息: $scheduledRoomList"); // 根据 scheduledRoomList 构建 UI return Container(); }, );}

十一、API 文档

十二、当预定房间后，无法收到RoomEvent的onScheduledRoomStartingSoon事件。

如果你在预定房间后未收到即将开始的事件通知，请按照以下两个核心要点进行检查：

1. 检查提醒参数配置 (reminderSecondsBeforeStart)

·触发机制：onScheduledRoomStartingSoon 事件的触发高度依赖于预定配置类 ScheduleRoomOptions 中的 reminderSecondsBeforeStart 属性。

·默认行为：该属性的默认值为 0，代表“不开启提醒”。

·解决建议：请确保在预定房间时明确设置该参数。该参数单位为秒，表示在房间开始前多少秒推送事件通知。

2. 验证预定时间逻辑

·计算公式：系统触发提醒的前提是：预定开始时间 (scheduleStartTime) – 当前时间 > 提醒偏移量 (reminderSecondsBeforeStart)。

·场景说明：如果你的房间开始时间设置得过近（例如 5 分钟后开始），而提醒时间设置得过大（例如设置 10 分钟前提醒），系统将无法捕捉到触发时机，从而导致事件丢失。

·解决建议：请确保预定的开始时间距离当前时刻，大于你所设置的提醒秒数。

十三、联系我们

如果你在接入或使用过程中有任何疑问或者建议，欢迎 联系我们 提交反馈。