CoHostStore
简介
跨房连线功能允许不同直播间的主播进行实时互动。CoHostStore 提供了一套全面的 API 来管理整个跨房连线生命周期。
重要:
请始终使用工厂方法 CoHostStore.create 并提供有效的直播间 ID 来创建 CoHostStore 实例。不要尝试直接初始化。
说明:
连线状态更新通过 coHostState 发布者传递。订阅它以接收有关连线状态、已连接主播、邀请和申请的实时更新。
警告:
如果连线请求在指定的超时时间内未收到响应,将触发超时事件。请始终在 UI 中处理超时场景。
功能特性
双向连线:主播可以向其他主播发起连线请求,也可以接收其他主播的连线请求。
状态管理:实时跟踪连线状态、已连接主播、邀请列表和申请者。
事件驱动架构:提供连线事件流用于监听各种连线状态变化。
布局模板:支持多种连线布局模板,如动态网格布局和1对6布局。
可订阅数据
CoHostState 的字段描述如下:
属性名 | 类型 | 描述 |
coHostStatus | 跨房连线的实时状态。 | |
connected | 正在和当前直播间连线的主播列表。 | |
invitees | 向其他直播间发出请求的主播列表。 | |
applicant | 向当前直播间发起连线请求的主播。 | |
candidatesCursor | ValueListenable<String> | 推荐用户列表游标。 |
candidates | 推荐用户列表。 |
API 列表
函数名 | 描述 |
创建对象实例。 | |
连线事件回调。 | |
连线事件回调。 | |
发起连线请求。 | |
取消连线请求。 | |
接受连线请求。 | |
拒绝连线请求。 | |
退出连线。 | |
获取推荐主播列表。 |
创建实例
CoHostStore.create
创建对象实例。
观察状态和事件
addCoHostListener
添加连线回调监听器
void addCoHostListener(CoHostListener listener);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
listener | 必填 | 监听器。 |
removeCoHostListener
移除连线回调监听器
void removeCoHostListener(CoHostListener listener);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
listener | 必填 | 监听器。 |
连线操作
requestHostConnection
发起主播连线请求
Future<CompletionHandler> requestHostConnection({required String targetHostLiveID,required CoHostLayoutTemplate layoutTemplate,required int timeout,String extraInfo = '',});
向目标主播发起跨房连线请求。
调用此方法后,会向目标主播发送连线请求。请求将保持活动状态,直到:
• 目标主播通过 acceptHostConnection(fromHostLiveID:completion:) 接受
• 目标主播通过 rejectHostConnection(fromHostLiveID:completion:) 拒绝
• 超时时间到期
• 您通过 cancelHostConnection(toHostLiveID:completion:) 取消
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
targetHostLiveID | String | 必填 | 目标主播的直播间ID。 |
layoutTemplate | 必填 | 连线布局模板。 | |
timeout | int | 必填 | 请求超时时间(单位:秒)。 |
extraInfo | String? | 必填 | 扩展信息。 |
cancelHostConnection
取消主播连线请求
Future<CompletionHandler> cancelHostConnection(String toHostLiveID);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
toHostLiveID | String | 必填 | 目标主播的直播间ID。 |
acceptHostConnection
接受主播连线请求
Future<CompletionHandler> acceptHostConnection(String fromHostLiveID);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
fromHostLiveID | String | 必填 | 发起连线请求的主播直播间ID。 |
rejectHostConnection
拒绝主播连线请求
Future<CompletionHandler> rejectHostConnection(String fromHostLiveID);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
fromHostLiveID | String | 必填 | 发起连线请求的主播直播间ID。 |
exitHostConnection
退出主播连线
Future<CompletionHandler> exitHostConnection();
版本信息
从 3.5 版本开始支持。
getCoHostCandidates
获取可以与当前主播连线的推荐主播列表
Future<CompletionHandler> getCoHostCandidates(String cursor);
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
cursor | String | 必填 | 游标。 |
数据结构
CoHostStatus
当前用户的跨房连线状态。
枚举值 | 值 | 说明 |
connected | 0 | 和其他主播正在连线中。 |
disconnected | 1 | 没有和其他主播连线。 |
CoHostLayoutTemplate
连线布局模板。
枚举值 | 值 | 说明 |
hostVoiceConnection | 2 | 语聊房连线布局。 |
hostDynamicGrid | 600 | 主播动态网格布局。 |
hostDynamic1v6 | 601 | 主播动态1对6布局。 |
CoHostListener
连线请求的回调事件。
方法
方法名 | 说明 |
onCoHostRequestReceived | 当收到连线请求时触发此回调。 |
onCoHostRequestCancelled | 当连线请求被取消时触发此回调。 |
onCoHostRequestAccepted | 当连线请求被接受时触发此回调。 |
onCoHostRequestRejected | 当连线请求被拒绝时触发此回调。 |
onCoHostRequestTimeout | 当连线请求超时时触发此回调。 |
onCoHostUserJoined | 当用户加入连线时触发此回调。 |
onCoHostUserLeft | 当用户离开连线时触发此回调。 |
CoHostState
CoHostStore 对外提供的跨房连线相关状态数据。
属性 | 类型 | 说明 |
coHostStatus | 跨房连线的实时状态。 | |
connected | 正在和当前直播间连线的主播列表。 | |
invitees | 向其他直播间发出请求的主播列表。 | |
applicant | 向当前直播间发起连线请求的主播。 | |
candidatesCursor | ValueListenable<String> | 推荐用户列表游标。 |
candidates | 推荐用户列表。 |
使用示例
// 创建 store 实例final store = CoHostStore.create('live_room_123');// 定义监听器late final VoidCallback statusListener = _onStatusChanged;late final VoidCallback connectedListener = _onConnectedChanged;void _onStatusChanged() {print('连线状态: ${store.coHostState.coHostStatus.value}');}void _onConnectedChanged() {print('已连接主播: ${store.coHostState.connected.value.length}');}// 订阅状态变化store.coHostState.coHostStatus.addListener(statusListener);store.coHostState.connected.addListener(connectedListener);// 添加连线事件监听器final coHostListener = CoHostListener(onCoHostRequestReceived: (inviter, extensionInfo) {print('收到来自 ${inviter.userName} 的连线请求');// 显示接受/拒绝的 UI},onCoHostRequestAccepted: (invitee) {print('连线请求被 ${invitee.userName} 接受');},onCoHostUserJoined: (userInfo) {print('主播 ${userInfo.userName} 加入连线');},);store.addCoHostListener(coHostListener);// 发起连线请求final result = await store.requestHostConnection(targetHostLiveID: 'target_live_id',layoutTemplate: CoHostLayoutTemplate.hostDynamicGrid,timeout: 30,extraInfo: '',);if (result.code == 0) {print('连线请求发送成功');}// 完成后取消订阅store.coHostState.coHostStatus.removeListener(statusListener);store.coHostState.connected.removeListener(connectedListener);store.removeCoHostListener(coHostListener);