BattleStore
简介
PK 功能实现主播之间的实时互动对战。BattleStore 提供了一套全面的 API 来管理整个 PK 生命周期。
重要：
请始终使用工厂方法 create(liveID:) 并提供有效的直播间 ID 来创建 BattleStore 实例。不要尝试直接初始化。
说明：
PK 状态更新通过 battleState 发布者传递。订阅它以接收有关 PK 信息、参与用户和分数的实时更新。
警告：
如果 PK 请求在指定的超时时间内未收到响应，将触发超时事件。请始终在 UI 中处理超时场景。
功能特性
PK 请求管理：主播可以发起 PK 请求，被邀请方可以接受或拒绝。
状态管理：实时跟踪 PK 信息、参与用户和分数。
事件驱动架构：提供完整的 PK 事件回调。
超时处理：为 PK 请求提供内置超时机制。
可订阅数据
BattleState 的字段描述如下：
属性名 | 类型 | 描述 |
currentBattleInfo | 当前 PK 信息。 | |
battleUsers | PK 用户列表。 | |
battleScore | ValueListenable<Map<String, int>> | PK 分数的映射。 |
API 列表
函数名 | 描述 |
创建 BattleStore 实例。 | |
新增 PK 事件回调。 | |
移除 PK 事件回调。 | |
发起 PK 请求。 | |
取消 PK 请求。 | |
接受 PK 请求。 | |
拒绝 PK 请求。 | |
退出 PK。 |
创建实例
BattleStore.create
创建 BattleStore 实例。
观察状态和事件
addBattleListener
新增 PK 事件回调
void addBattleListener(BattleListener listener);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
listener | 必填 | 监听器。 |
removeBattleListener
移除 PK 事件回调
void removeBattleListener(BattleListener listener);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
listener | 必填 | 监听器。 |
PK 操作
requestBattle
发起 PK 请求
Future<BattleRequestCompletionHandler> requestBattle({required BattleConfig config,required List<String> userIDList,required int timeout,});
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
config | 必填 | PK 配置。 | |
userIDList | List<String> | 必填 | 需要进入PK的用户 ID 列表。 |
timeout | int | 必填 | 请求超时时间。 |
cancelBattleRequest
取消PK请求
Future<CompletionHandler> cancelBattleRequest({required String battleID,required List<String> userIDList,});
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
battleID | String | 必填 | PK ID。 |
userIDList | List<String> | 必填 | 用户ID列表。 |
acceptBattle
接受PK请求
Future<CompletionHandler> acceptBattle(String battleID);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
battleID | String | 必填 | PK ID。 |
rejectBattle
拒绝PK请求
Future<CompletionHandler> rejectBattle(String battleID);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
battleID | String | 必填 | PK ID。 |
exitBattle
退出PK
Future<CompletionHandler> exitBattle(String battleID);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
battleID | String | 必填 | PK ID。 |
数据结构
BattleEndedReason
正在 PK 中用户收到 PK 结束的原因。
枚举值 | 值 | 说明 |
timeOver | 0 | PK 倒计时结束。 |
allMemberExit | 1 | 所有 PK 成员退出。 |
BattleListener
收到 PK 相关的回调事件。
方法
方法名 | 说明 |
onBattleStarted | 当 PK 正式开始时触发此回调，通知所有参与者 PK 已经开始。 |
onBattleEnded | 当 PK 结束时触发此回调。 |
onUserJoinBattle | 当有用户加入 PK 时触发此回调。 |
onUserExitBattle | 当有用户退出 PK 时触发此回调。 |
onBattleRequestReceived | 当收到 PK 请求时触发此回调。 |
onBattleRequestCancelled | 当 PK 请求被取消时触发此回调。 |
onBattleRequestTimeout | 当 PK 请求超时时触发此回调。 |
onBattleRequestAccept | 当 PK 请求被接受时触发此回调。 |
onBattleRequestReject | 当 PK 请求被拒绝时触发此回调。 |
BattleConfig
发送 PK 请求时，设置的 PK 配置信息。
属性 | 类型 | 说明 |
duration | int | PK 持续时间（单位：秒）。 |
needResponse | bool | 被邀请用户是否需要回复同意/拒绝。 |
extensionInfo | String | 扩展信息。 |
BattleInfo
PK 信息。
属性 | 类型 | 说明 |
battleID | String | PK ID。 |
config | 发送 PK 请求时，设置的 PK 配置信息。 | |
startTime | int | PK 开始标记时间戳（单位：秒）。 |
endTime | int | PK 结束标记时间戳（单位：秒）。 |
BattleState
BattleStore 对外提供的 PK 相关状态数据。
属性 | 类型 | 说明 |
currentBattleInfo | 当前 PK 信息。 | |
battleUsers | PK 用户列表。 | |
battleScore | ValueListenable<Map<String, int>> | PK 分数的映射。 |
BattleRequestCompletionHandler
PK 请求完成处理器。
Dart 中 PK 请求的完成处理器，包含 PK 请求的结果。
属性
属性 | 类型 | 说明 |
battleInfo | 成功时返回的 PK 信息。 | |
resultMap | Map<String, int>? | PK 请求的响应结果映射。 |
使用示例
// 创建 store 实例final store = BattleStore.create('live_room_123');// 定义监听器late final VoidCallback battleInfoListener = _onBattleInfoChanged;late final VoidCallback battleUsersListener = _onBattleUsersChanged;void _onBattleInfoChanged() {final battleInfo = store.battleState.currentBattleInfo.value;if (battleInfo != null) {print('当前 PK ID: ${battleInfo.battleID}');}}void _onBattleUsersChanged() {print('PK 用户数: ${store.battleState.battleUsers.value.length}');}// 订阅状态变化store.battleState.currentBattleInfo.addListener(battleInfoListener);store.battleState.battleUsers.addListener(battleUsersListener);// 添加 PK 事件监听器final battleListener = BattleListener(onBattleStarted: (battleInfo, inviter, invitees) {print('PK 开始，发起者: ${inviter.userName}');},onBattleEnded: (battleInfo, reason) {print('PK 结束，原因: $reason');},);store.addBattleListener(battleListener);// 发起 PK 请求final config = BattleConfig(duration: 300, needResponse: true);final result = await store.requestBattle(config: config,userIDList: ['user_456'],timeout: 30,);if (result.code == 0) {print('PK 请求成功: ${result.battleInfo?.battleID}');} else {print('PK 请求失败: ${result.message}');}// 取消订阅store.battleState.currentBattleInfo.removeListener(battleInfoListener);store.battleState.battleUsers.removeListener(battleUsersListener);store.removeBattleListener(battleListener);
