文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>视频会议 SDK>无 UI 集成>搭建多人会议>成员管理>成员管理（Flutter）

成员管理（Flutter）

最近更新时间：2026-01-28 17:25:01

我的收藏

本页目录：

RoomParticipantStore 是 AtomicXCore 中专用于房间参与者管理的模块。该模块为多人房间场景提供了核心能力，支持构建完整的成员管理体系。




核心功能

获取参与者列表：获取并展示当前房间内所有参与者信息。
房主转移：房主可以将房主身份转移给房间内任意一名参与者。
设置/撤销管理员：房主可以设置参与者为管理员，同时也可撤销房间内的管理员。
将参与者移除房间：房主或者管理员可以将房间内任意一名参与者踢出房间。
参与者信息更新：房间内所有人都可以更新自己的参与者信息。
音视频设备管理：支持申请/邀请打开摄像头、麦克风，关闭远端摄像头、麦克风，以及房主和管理员设置全体静音，全体禁画功能。

核心概念

在开始集成之前，需要通过下表了解 RoomParticipantStore 相关的核心概念：
核心概念
核心职责与描述
代表参与者的核心数据模型，封装了参与者的完整信息和状态管理能力。
核心功能包括：
参与者基本信息管理（用户 ID、用户名称、用户头像、房间内角色身份）。
参与者设备状态管理（麦克风状态，摄像头状态，屏幕分享状态，消息状态）。
代表参与者状态管理的核心数据结构，负责维护房间内与参与者相关状态信息。
核心属性：
participantList 存储了当前所在房间的所有参与者信息集合。
participantListCursor 则代表房间内参与者列表的分页快照。
localParticipant则代表自身所在房间内的参与者信息。
代表房间内和参与者相关的实时事件。主要事件分为三大类：参与者进退房事件、 参与者身份改变事件，参与者设备控制事件。
这是参与者控制相关的核心类。功能包含：控制房间内参与者音视频状态、执行参与者管理操作，并通过 addRoomParticipantListener 方法来接收实时事件。

实现步骤

步骤1：组件集成

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

步骤2：获取参与者列表

在加入房间后，调用RoomParticipantStore的getParticipantList接口获取到房间内参与者列表。
import 'package:atomic_x_core/atomicxcore.dart';

Future<void> getParticipantList() async {
  // 1. 业务逻辑说明
  // 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
  final participantStore = RoomParticipantStore.create("your_room_id");

  // 2. 首次获取参与者列表（从头开始）
  // 支持分页加载，可以通过 cursor 参数实现增量获取
  final String? initialCursor = null;  // null 表示从第一页开始获取

  final result = await participantStore.getParticipantList(initialCursor);

  if (result.isSuccess) {
    print("成功获取参与者列表，数量: ${result.data?.length ?? 0}");
  } else {
    print("获取参与者列表失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}

步骤3：房主转移

作为房主：调用RoomParticipantStore的transferOwner接口可以将房主身份直接转移给房间内任意一位参与者，转移后原房主身份将变为普通参与者，一个房间内有且仅有一名房主。
import 'package:atomic_x_core/atomicxcore.dart';

Future<void> transferOwner(String userID) async {
  // 1. 业务逻辑说明
  // 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
  final participantStore = RoomParticipantStore.create("your_room_id");

  // 2. 调用 RoomParticipantStore 转移房主接口
  // 注意：只有当前房主才有权限执行此操作，转移后原房主将变为普通用户
  final result = await participantStore.transferOwner(userID);

  if (result.isSuccess) {
    print("房主权限转移成功，新房主: $userID");
  } else {
    print("转移房主权限失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}
作为参与者：监听RoomParticipantListener中的onOwnerChanged事件，被动接收房主变化通知。
import 'package:atomic_x_core/atomicxcore.dart';

void subscribeParticipantEvent() {
  late RoomParticipantListener _participantListener;

  // 1. 业务逻辑说明
  // 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
  final participantStore = RoomParticipantStore.create("your_room_id");

  // 2. 创建参与者事件监听器
  // RoomParticipantListener 用于接收所有参与者相关的事件
  _participantListener = RoomParticipantListener(
    onOwnerChanged: (RoomUser newOwner, RoomUser oldOwner) {
      print("房主变更通知，newOwner: ${newOwner.userName}, oldOwner: ${oldOwner.userName}");
    },
  );

  // 3. 添加监听器
  participantStore.addRoomParticipantListener(_participantListener);
}

void unsubscribeParticipantEvent() {
  // 4. 移除监听器，避免内存泄漏
  final participantStore = RoomParticipantStore.create("your_room_id");
  participantStore.removeRoomParticipantListener(_participantListener);
}


步骤4：设置/撤销管理员

作为房主：调用RoomParticipantStore的setAdmin接口指定房间内任意成员成为管理员，也可以调用revokeAdmin接口将管理员身份撤销。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

/// 设置用户为管理员
Future<void> setUserAsAdmin(String userID) async {
  final result = await participantStore.setAdmin(userID);

  if (result.isSuccess) {
    print("成功设置用户 $userID 为管理员");
  } else {
    print("设置管理员失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}

/// 撤销用户的管理员权限
Future<void> revokeUserAdmin(String userID) async {
  final result = await participantStore.revokeAdmin(userID);

  if (result.isSuccess) {
    print("成功撤销用户 $userID 的管理员权限");
  } else {
    print("撤销管理员失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}

作为参与者：监听RoomParticipantListener中的onAdminSet和onAdminRevoked事件，被动接收参与者身份变化通知。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

late RoomParticipantListener _participantListener;

/// 订阅参与者相关事件
void subscribeParticipantEvents() {
  _participantListener = RoomParticipantListener(
    onAdminSet: (RoomUser userInfo) {
      print("设置管理员事件通知，userInfo: ${userInfo.userName}");
    },
    onAdminRevoked: (RoomUser userInfo) {
      print("撤销管理员事件通知，userInfo: ${userInfo.userName}");
    },
  );

  participantStore.addRoomParticipantListener(_participantListener);
}

/// 取消订阅参与者相关事件
void unsubscribeParticipantEvents() {
  participantStore.removeRoomParticipantListener(_participantListener);
}

步骤5：将参与者移除房间

作为房主和管理员：调用RoomParticipantStore的 kickUser 可以将房间内参与者踢出房间。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

Future<void> kickUser(String userID) async {
  // 1. 业务逻辑说明
  // kickUser 接口用于将指定用户踢出房间
  // 注意：只有房主或管理员才有权限执行此操作
  // 被踢出的用户将立即离开房间，并收到相应的通知

  // 2. 调用 RoomParticipantStore 踢出用户接口
  final result = await participantStore.kickUser(userID);

  if (result.isSuccess) {
    print("用户踢出成功，被踢出用户: $userID");
  } else {
    print("踢出用户失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}
作为参与者：监听RoomParticipantListener中的onKickedFromRoom事件，被动接收参与者被踢出房间通知。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

late RoomParticipantListener _participantListener;

/// 订阅参与者相关事件
void subscribeParticipantEvent() {
  _participantListener = RoomParticipantListener(
    onKickedFromRoom: (KickedOutOfRoomReason reason, String message) {
      print("已被踢出房间，被踢出原因：$reason, 额外信息：$message");
    },
  );

  participantStore.addRoomParticipantListener(_participantListener);
}

/// 取消订阅参与者相关事件
void unsubscribeParticipantEvent() {
  participantStore.removeRoomParticipantListener(_participantListener);
}

步骤6：更新参与者信息

在加入房间后，调用RoomParticipantStore的updateParticipantNameCard、updateParticipantMetaData更新您在房间里的参与者信息，包含：参与者名片信息，参与者自定义信息。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

Future<void> updateParticipantNameCard(String userID, String nameCard) async {
  // 1. 业务逻辑说明
  // updateParticipantNameCard 接口用于更新指定参与者的名片信息
  // 名片通常用于显示用户的自定义昵称或标识
  // 注意：通常只有管理员或用户本人才能修改名片

  // 2. 调用 RoomParticipantStore 更新名片接口
  final result = await participantStore.updateParticipantNameCard(
    userID: userID,
    nameCard: nameCard,
  );

  if (result.isSuccess) {
    print("名片更新成功，用户: $userID, 新名片: $nameCard");
  } else {
    print("名片更新失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}

Future<void> updateParticipantMetaData(String userID, Map<String, String> metaData) async {
  // 1. 业务逻辑说明
  // updateParticipantMetaData 接口用于更新指定参与者的自定义信息
  // 存储自定义的业务数据，如用户标签、扩展属性等
  // 注意：自定义信息的键值对数量和大小有限制，具体可见常见问题

  // 2. 调用 RoomParticipantStore 更新自定义信息接口
  final result = await participantStore.updateParticipantMetaData(
    userID: userID,
    metaData: metaData,
  );

  if (result.isSuccess) {
    print("自定义信息数据更新成功，用户: $userID, 键数量: ${metaData.length}");
  } else {
    print("自定义信息更新失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}

步骤7：邀请打开设备

作为房主和管理员：调用RoomParticipantStore的inviteToOpenDevice接口，邀请房间内参与者打开摄像头，麦克风。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

Future<void> inviteUserToOpenDevice(String userID, DeviceType device, {int timeout = 30}) async {
  // 1. 业务逻辑说明
  // inviteToOpenDevice 接口用于邀请指定用户开启某个设备
  // 通常用于管理员邀请参与者开启麦克风、摄像头或屏幕共享
  // 被邀请的用户会收到邀请通知，可以选择接受或拒绝

  // 2. 调用 RoomParticipantStore 邀请开启设备接口
  final result = await participantStore.inviteToOpenDevice(
    userID: userID,
    device: device,
    timeout: timeout,
  );

  if (result.isSuccess) {
    print("设备邀请发送成功，用户: $userID, 设备: $device");
  } else {
    print("设备邀请发送失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}
作为参与者：
监听RoomParticipantListener中的onDeviceInvitationReceived事件，被动接收邀请打开设备通知。
接收到邀请打开设备通知后调用RoomParticipantStore的acceptOpenDeviceInvitation或者declineOpenDeviceInvitation接口接受或拒绝邀请。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");
late RoomParticipantListener _participantListener;

/// 订阅参与者相关事件
void subscribeDeviceInvitationEvent() {
  _participantListener = RoomParticipantListener(
    onDeviceInvitationReceived: (invitation) {
      print("收到设备邀请 - 设备: ${invitation.device}, 发送者: ${invitation.senderUserName}");
      // 处理接受、拒绝设备邀请
    },
  );
  participantStore.addRoomParticipantListener(_participantListener);
}

/// 取消订阅（在不需要时调用）
void unsubscribeDeviceInvitationEvent() {
  participantStore.removeRoomParticipantListener(_participantListener);
}

Future<void> acceptOpenDeviceInvitation(String userID, DeviceType device) async {
  // 处理接受邀请
  final result = await participantStore.acceptOpenDeviceInvitation(
    userID: userID,
    device: device,
  );

  if (result.isSuccess) {
    print("接受设备邀请成功 - 设备: $device");
  } else {
    print("接受设备邀请失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}

Future<void> declineOpenDeviceInvitation(String userID, DeviceType device) async {
  // 处理拒绝邀请
  final result = await participantStore.declineOpenDeviceInvitation(
    userID: userID,
    device: device,
  );

  if (result.isSuccess) {
    print("拒绝设备邀请成功 - 设备: $device");
  } else {
    print("拒绝设备邀请失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}

步骤8：关闭远端参与者设备

作为房主和管理员：调用RoomParticipantStore的closeParticipantDevice可以主动关闭远端参与者的摄像头，麦克风。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

Future<void> closeParticipantDevice(String userID, DeviceType device) async {
  // 1. 业务逻辑说明
  // closeParticipantDevice 接口用于房主或管理员关闭指定参与者的某个设备
  // 被关闭的用户会收到设备被关闭通知

  // 2. 调用 RoomParticipantStore 关闭参与者设备接口
  final result = await participantStore.closeParticipantDevice(
    userID: userID,
    device: device,
  );

  if (result.isSuccess) {
    print("关闭参与者设备成功 - 用户: $userID, 设备: $device");
  } else {
    print("关闭参与者设备失败: [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}
作为参与者：监听RoomParticipantListener中的onParticipantDeviceClosed事件，被动接收设备被关闭通知，并在 UI 上做出提示。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");
late RoomParticipantListener _participantListener;

/// 订阅参与者相关事件
void subscribeDeviceClosedEvent() {
  _participantListener = RoomParticipantListener(
    onParticipantDeviceClosed: (device, operatorUser) {
      print("设备被关闭 - 设备: $device, 操作者: ${operatorUser.userName}");
    },
  );
  participantStore.addRoomParticipantListener(_participantListener);
}

/// 取消订阅（在不需要时调用）
void unsubscribeDeviceClosedEvent() {
  participantStore.removeRoomParticipantListener(_participantListener);
}

步骤9：申请打开设备

作为参与者：调用RoomParticipantStore的requestToOpenDevice接口，可以在房间被房主或管理员设置全体静音，全体禁画的场景下，主动申请打开摄像头，麦克风。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

Future<void> requestToOpenDevice(DeviceType device, {int timeout = 30}) async {
  // 1. 业务逻辑说明
  // requestToOpenDevice 接口用于请求开启某个设备
  // 通常用于参与者申请开启麦克风、摄像头或屏幕共享
  // 房主和管理员会收到申请通知，可以选择同意或拒绝

  // 2. 调用 RoomParticipantStore 请求开启设备接口
  final result = await participantStore.requestToOpenDevice(
    device: device,
    timeout: timeout,
  );

  if (result.isSuccess) {
    print("设备开启请求发送成功 - 设备: $device");
  } else {
    print("设备开启请求发送失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}
作为房主和管理员：
监听RoomParticipantListener中的onDeviceRequestReceived事件，被动接收申请打开设备通知。
接收到申请打开设备通知后，调用RoomParticipantStore的approveOpenDeviceRequest或者rejectOpenDeviceRequest接口，批准或者拒绝申请。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");
late RoomParticipantListener _participantListener;

/// 订阅参与者相关事件
void subscribeDeviceRequestEvent() {
  _participantListener = RoomParticipantListener(
    onDeviceRequestReceived: (request) {
      print("收到设备请求 - 用户: ${request.senderUserName}, 设备: ${request.device}");
      // 批准、拒绝开启设备请求操作
    },
  );
  participantStore.addRoomParticipantListener(_participantListener);
}

/// 取消订阅（在不需要时调用）
void unsubscribeDeviceRequestEvent() {
  participantStore.removeRoomParticipantListener(_participantListener);
}

Future<void> approveOpenDeviceRequest(DeviceType device, String userID) async {
  // 批准开启请求
  final result = await participantStore.approveOpenDeviceRequest(
    device: device,
    userID: userID,
  );

  if (result.isSuccess) {
    print("批准设备请求成功 - 用户: $userID, 设备: $device");
  } else {
    print("批准设备请求失败: ${result.errorMessage}");
  }
}

Future<void> rejectOpenDeviceRequest(DeviceType device, String userID) async {
  // 拒绝开启请求
  final result = await participantStore.rejectOpenDeviceRequest(
    device: device,
    userID: userID,
  );

  if (result.isSuccess) {
    print("拒绝设备请求成功 - 用户: $userID, 设备: $device");
  } else {
    print("拒绝设备请求失败: [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}

步骤10：全体静音、全体禁画

作为房主和管理员：调用RoomParticipantStore的disableAllDevices接口设置全员静音与全员禁用摄像头。开启后，房间内参与者的音视频开启权限将被限制，无法自主打开麦克风或摄像头设备。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

Future<void> disableAllDevices(DeviceType device, bool disable) async {
  // 1. 业务逻辑说明
  // disableAllDevices 接口用于房主或管理员设置房间禁用、解禁房间内全体成员麦克风，摄像头
  // 设置后房间内参与者会收到禁用、解禁通知

  // 2. 调用 RoomParticipantStore 禁用、解禁全体设备接口
  final result = await participantStore.disableAllDevices(
    device: device,
    disable: disable,
  );

  final action = disable ? "禁用" : "启用";
  if (result.isSuccess) {
    print("$action所有$device成功");
  } else {
    print("$action所有$device失败 [错误码: ${result.errorCode}]: ${result.errorMessage}");
  }
}
作为参与者：监听RoomParticipantListener中的onAllDevicesDisabled事件，可以监听全员静音或禁画指令，并在 UI 界面同步受控状态。受限状态下，摄像头与麦克风的主动开启功能将被锁定，参与者需发起开启申请，待房主或管理员核准授权后方可使用。
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");
late RoomParticipantListener _participantListener;

/// 设置全局设备事件监听
void subscribeAllDevicesDisabledEvent() {
  _participantListener = RoomParticipantListener(
    onAllDevicesDisabled: (device, disable, operatorUser) {
      final action = disable ? "禁用" : "启用";
      print("所有$device被$action - 操作者: ${operatorUser.userName}");
    },
  );
  participantStore.addRoomParticipantListener(_participantListener);
}

/// 取消订阅（在不需要时调用）
void unsubscribeAllDevicesDisabledEvent() {
  participantStore.removeRoomParticipantListener(_participantListener);
}

步骤11：监听参与者事件及状态

订阅RoomParticipantEvent参与者相关的被动事件。以订阅参与者加入房间、离开房间为例，示例代码如下：
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");
late RoomParticipantListener _participantListener;

/// 设置参与者事件监听
void subscribeParticipantEvent() {
  _participantListener = RoomParticipantListener(
    onParticipantJoined: (participant) {
      print("参与者加入房间 - 用户: ${participant.userName}, ID: ${participant.userID}");
    },
    onParticipantLeft: (participant) {
      print("参与者离开房间 - 用户: ${participant.userName}, ID: ${participant.userID}");
    },
  );
  participantStore.addRoomParticipantListener(_participantListener);
}

/// 取消订阅（在不需要时调用）
void unsubscribeParticipantEvent() {
  participantStore.removeRoomParticipantListener(_participantListener);
}
订阅RoomParticipantState参与者相关的属性状态变化。以订阅房间内正在说话的用户为例，示例代码如下：
import 'package:atomic_x_core/atomicxcore.dart';

// 业务逻辑说明
// 前提：需要先完成进房操作,通过进房的roomID创建RoomParticipantStore实例
final participantStore = RoomParticipantStore.create("your_room_id");

/// 使用 ValueListenableBuilder 监听参与者状态
Widget buildSpeakingUsersWidget() {
  return ValueListenableBuilder(
    valueListenable: participantStore.state.speakingUsers,
    builder: (context, speakingUsers, child) {
      print("说话用户状态变更 - 当前说话用户数: ${speakingUsers.length}");
      // 根据 speakingUsers 构建 UI
      return Container();
    },
  );
}


API 文档

Store
功能描述
API文档
RoomParticipantStore
房间内参与者管理：设置管理员 / 转移房主 / 获取参与者列表 / 踢出房间 / 参与者设备控制（例如关闭、邀请打开摄像头、麦克风等）/ 申请打开设备（例如申请打开摄像头、麦克风等）。
API 文档

联系我们

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