BattleStore

简介
PK 功能实现主播之间的实时互动对战。BattleStore 提供了一套全面的 API 来管理整个 PK 生命周期。
重要：
请始终使用工厂方法 BattleStore.create 并提供有效的直播间 ID 来创建 BattleStore 实例。不要尝试直接初始化。
说明：
PK 状态更新通过 battleState 发布者传递。订阅它以接收有关 PK 信息、参与用户和分数的实时更新。
警告：
如果 PK 请求在指定的超时时间内未收到响应，将触发超时事件。请始终在 UI 中处理超时场景。
功能特性
PK 请求管理：主播可以发起 PK 请求，被邀请方可以接受或拒绝。
状态管理：实时跟踪 PK 信息、参与用户和分数。
事件驱动架构：提供完整的 PK 事件回调。
超时处理：为 PK 请求提供内置超时机制。
可订阅数据
BattleState 的字段描述如下：
属性名
类型
描述
currentBattleInfo
StateFlow<BattleInfo?>
当前 PK 信息。
battleUsers
StateFlow<List<SeatUserInfo>>
PK 用户列表。
battleScore
StateFlow<Map<String, Int>>
PK 分数的映射。
API 列表
函数名
描述
BattleStore.create
创建 BattleStore 实例。
addBattleListener
新增 PK 事件回调。
removeBattleListener
移除 PK 事件回调。
requestBattle
发起 PK 请求。
cancelBattleRequest
取消 PK 请求。
acceptBattle
接受 PK 请求。
rejectBattle
拒绝 PK 请求。
exitBattle
退出 PK。
创建实例
BattleStore.create
创建 BattleStore 实例。
观察状态和事件
addBattleListener
新增 PK 事件回调
abstract fun addBattleListener(listener: BattleListener?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
listener
BattleListener?
必填
监听器。
removeBattleListener
移除 PK 事件回调
abstract fun removeBattleListener(listener: BattleListener?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
listener
BattleListener?
必填
监听器。
PK 操作
requestBattle
发起 PK 请求
abstract fun requestBattle(
    config: BattleConfig,
    userIDList: List<String>,
    timeout: Int,
    completion: BattleRequestCallback?
)
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
config
BattleConfig
必填
PK 配置。
userIDList
List<String>
必填
需要进入PK的用户 ID 列表。
timeout
Int
必填
请求超时时间。
completion
BattleRequestCallback?
必填
发起请求成功的回调。
cancelBattleRequest
取消PK请求
abstract fun cancelBattleRequest(
    battleID: String?,
    userIDList: List<String>,
    completion: CompletionHandler?
)
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
battleID
String?
必填
PK ID。
userIDList
List<String>
必填
用户ID列表。
completion
CompletionHandler?
必填
取消请求成功的回调。
acceptBattle
接受PK请求
abstract fun acceptBattle(
    battleID: String?,
    completion: CompletionHandler?
)
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
battleID
String?
必填
PK ID。
completion
CompletionHandler?
必填
接受成功的回调。
rejectBattle
拒绝PK请求
abstract fun rejectBattle(
    battleID: String?,
    completion: CompletionHandler?
)
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
battleID
String?
必填
PK ID。
completion
CompletionHandler?
必填
拒绝成功的回调。
exitBattle
退出PK
abstract fun exitBattle(
    battleID: String?,
    completion: CompletionHandler?
)
版本信息
从 3.5 版本开始支持。
参数说明
参数名
类型
是否必填
描述
battleID
String?
必填
PK ID。
completion
CompletionHandler?
必填
退出 PK 成功的回调。
数据结构
BattleEndedReason
正在 PK 中用户收到 PK 结束的原因。
枚举值
值
说明
TIME_OVER
0
PK 倒计时结束。
ALL_MEMBER_EXIT
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
Boolean
被邀请用户是否需要回复同意/拒绝。
extensionInfo
String
扩展信息。
BattleInfo
PK 信息。
属性
类型
说明
battleID
String
PK ID。
config
BattleConfig
发送 PK 请求时，设置的 PK 配置信息。
startTime
Long
PK 开始标记时间戳（单位：秒）。
endTime
Long
PK 结束标记时间戳（单位：秒）。
BattleState
BattleStore 对外提供的 PK 相关状态数据。
属性
类型
说明
currentBattleInfo
StateFlow<BattleInfo?>
当前 PK 信息。
battleUsers
StateFlow<List<SeatUserInfo>>
PK 用户列表。
battleScore
StateFlow<Map<String, Int>>
PK 分数的映射。
BattleRequestCallback
PK 请求回调。
PK 请求的回调接口，用于处理 PK 请求的成功或失败结果。
方法
onSuccess: 成功回调。
fun onSuccess(battleInfo: BattleInfo, resultMap: Map<String, Int>)
参数名
类型
说明
battleInfo
BattleInfo
PK 信息，包含 PK 的详细配置和状态。
resultMap
Map<String, Int>
PK 请求的响应结果回调。
onError: 失败回调。
fun onError(code: Int, desc: String)
参数名
类型
说明
code
Int
错误码。
desc
String
错误描述。
使用示例
// 创建 store 实例
val store = BattleStore.create("live_room_123")
﻿
// 订阅状态变化
lifecycleScope.launch {
    store.battleState.currentBattleInfo.collect { battleInfo ->
        battleInfo?.let {
            println("当前 PK ID: ${it.battleID}")
        }
    }
}
﻿
// 添加 PK 事件监听器
store.addBattleListener(object : BattleListener() {
    override fun onBattleStarted(battleInfo: BattleInfo, inviter: SeatUserInfo, invitees: List<SeatUserInfo>) {
        println("PK 开始，发起者: ${inviter.userName}")
    }
    override fun onBattleEnded(battleInfo: BattleInfo, reason: BattleEndedReason?) {
        println("PK 结束，原因: $reason")
    }
})
﻿
// 发起 PK 请求
val config = BattleConfig(duration = 300, needResponse = true)
store.requestBattle(config, listOf("user_456"), 30, object : BattleRequestCallback {
    override fun onSuccess(battleInfo: BattleInfo, resultMap: Map<String, Int>) {
        println("PK 请求成功: ${battleInfo.battleID}")
    }
    override fun onError(code: Int, desc: String) {
        println("PK 请求失败: $desc")
    }
})
﻿

属性名	类型	描述
currentBattleInfo	StateFlow<BattleInfo?>	当前 PK 信息。
battleUsers	StateFlow<List<SeatUserInfo>>	PK 用户列表。
battleScore	StateFlow<Map<String, Int>>	PK 分数的映射。

函数名	描述
BattleStore.create	创建 BattleStore 实例。
addBattleListener	新增 PK 事件回调。
removeBattleListener	移除 PK 事件回调。
requestBattle	发起 PK 请求。
cancelBattleRequest	取消 PK 请求。
acceptBattle	接受 PK 请求。
rejectBattle	拒绝 PK 请求。
exitBattle	退出 PK。

参数名	类型	是否必填	描述
listener	BattleListener?	必填	监听器。

枚举值	值	说明
TIME_OVER	0	PK 倒计时结束。
ALL_MEMBER_EXIT	1	所有 PK 成员退出。

方法名	说明
onBattleStarted	当 PK 正式开始时触发此回调，通知所有参与者 PK 已经开始。
onBattleEnded	当 PK 结束时触发此回调。
onUserJoinBattle	当有用户加入 PK 时触发此回调。
onUserExitBattle	当有用户退出 PK 时触发此回调。
onBattleRequestReceived	当收到 PK 请求时触发此回调。
onBattleRequestCancelled	当 PK 请求被取消时触发此回调。
onBattleRequestTimeout	当 PK 请求超时时触发此回调。
onBattleRequestAccept	当 PK 请求被接受时触发此回调。
onBattleRequestReject	当 PK 请求被拒绝时触发此回调。

属性	类型	说明
duration	Int	PK 持续时间（单位：秒）。
needResponse	Boolean	被邀请用户是否需要回复同意/拒绝。
extensionInfo	String	扩展信息。