观众列表

LiveAudienceStateAtomicXCore 中专门负责管理直播间观众信息的模块。通过 LiveAudienceState 您可以为您的直播应用构建一套完整的观众列表及管理系统。


核心功能

实时观众列表:获取并展示当前在直播间内的所有观众信息。
观众人数统计:实时获取当前直播间的准确观众总数。
观众动态监听:通过事件订阅,实时感知观众的加入和离开。
管理员权限:主播可设置或取消管理员权限。
房间管理:主播或管理员可将普通观众踢出直播间。

示例项目

您可参考我们在 Github 上提供的 LiveAudienceList 组件来查看完整实现。

实现步骤

步骤1:组件集成

请参考 快速接入 集成 AtomicXCore,完成接入。

步骤2:初始化并获取观众列表

获取 LiveAudienceState 实例,并主动拉取一次当前的观众列表,用于首次展示。该模块内部会自动监听当前直播间状态的变化,当切换直播间时会自动更新观众列表。
import { onMounted, watch } from 'vue';
import { useLiveAudienceState } from "tuikit-atomicx-vue3";

// 获取 LiveAudienceState 的实例
const { fetchAudienceList, audienceList } = useLiveAudienceState();

onMounted(async () => {
try {
// 获取观众列表,返回 Promise
await fetchAudienceList();
console.log('首次拉取观众列表成功');
} catch (error) {
console.error('首次拉取观众列表失败', error);
}
});

// 监听 audienceList 的实时变更,用于驱动 UI 变更
watch(audienceList, (newVal) => {
console.log('观众列表更新:', newVal);
});

步骤3:监听观众列表状态与实时动态

订阅和监听 audienceStateevent响应式数据,用来接收全量列表快照和实时的观众进出事件,从而驱动 UI 更新。
import { onMounted, onUnmounted, watch } from 'vue';
import { useLiveAudienceState, LiveAudienceEvent } from "tuikit-atomicx-vue3";

const {
audienceList,
audienceCount,
subscribeEvent,
unsubscribeEvent
} = useLiveAudienceState();

// 监听 audienceCount 的实时变更,用于驱动 UI 更新人数显示
watch(audienceCount, (newCount) => {
console.log(`当前在线人数: ${newCount}`);
});

// 定义回调函数
const onAudienceJoined = (eventInfo) => {
console.log(`观众 ${eventInfo.audience.userName} 加入了直播间`);
};

const onAudienceLeft = (eventInfo) => {
console.log(`观众 ${eventInfo.audience.userName} 离开了直播间`);
};

onMounted(() => {
// 订阅观众进入事件
subscribeEvent(LiveAudienceEvent.onAudienceJoined, onAudienceJoined);
// 订阅观众离开事件
subscribeEvent(LiveAudienceEvent.onAudienceLeft, onAudienceLeft);
});

onUnmounted(() => {
// 组件卸载时取消订阅
unsubscribeEvent(LiveAudienceEvent.onAudienceJoined, onAudienceJoined);
unsubscribeEvent(LiveAudienceEvent.onAudienceLeft, onAudienceLeft);
});

步骤4:管理观众(踢出直播间与设置管理员)

作为主播或管理员,对直播间内的观众进行管理操作。

4.1 主播或管理员可将普通观众踢出直播间

调用 kickUserOutOfRoom 接口可以将指定用户请出直播间。
import { useLiveAudienceState } from "tuikit-atomicx-vue3";

const { kickUserOutOfRoom } = useLiveAudienceState();

const handleKickUser = async (targetUserId: string) => {
try {
await kickUserOutOfRoom({ userId: targetUserId });
console.log(`主播或管理员将 ${targetUserId} 踢出直播间`);
} catch (error) {
console.error(`主播或管理员将 ${targetUserId} 踢出直播间失败`, error);
}
};

4.2 主播可设置或取消管理员权限

通过 setAdministratorrevokeAdministrator 接口可以管理用户的管理员身份。
import { useLiveAudienceState } from "tuikit-atomicx-vue3";

const { setAdministrator, revokeAdministrator } = useLiveAudienceState();

// 主播可设置或取消管理员权限
const promoteToAdmin = async (targetUserId: string) => {
try {
await setAdministrator({ userId: targetUserId });
console.log(`成功将用户 ${targetUserId} 设置管理员`);
} catch (error) {
console.error(`将用户 ${targetUserId} 设置管理员失败`, error);
}
};

// 主播可设置或取消管理员权限
const revokeAdmin = async (targetUserId: string) => {
try {
await revokeAdministrator({ userId: targetUserId });
console.log(`成功将用户 ${targetUserId} 的管理员身份撤销`);
} catch (error) {
console.error(`撤销用户 ${targetUserId} 管理员身份失败`, error);
}
};

4.3 禁言/解除禁言

管理员可以禁用或启用指定用户在房间中发送消息的权限。
import { useLiveAudienceState } from "tuikit-atomicx-vue3";

const { disableSendMessage } = useLiveAudienceState();

// 禁言用户
const muteUser = async (targetUserId: string) => {
await disableSendMessage({ userId: targetUserId, isDisable: true });
};

// 解除禁言
const unmuteUser = async (targetUserId: string) => {
await disableSendMessage({ userId: targetUserId, isDisable: false });
};

功能进阶

在弹幕区展示观众入场欢迎语

当有新观众进入直播间时,弹幕/聊天区域会在本地自动显示一条欢迎消息,例如:“欢迎 [用户昵称] 进入直播间”。

实现方式

当有新观众进入直播间时,可以通过订阅观众加入事件onAudienceJoined,在弹幕/聊天区域显示一条欢迎消息,例如:"欢迎 [用户昵称] 进入直播间"。

import { onMounted, onUnmounted } from 'vue';
import { useLiveAudienceState, useBarrageState, LiveAudienceEvent } from "tuikit-atomicx-vue3";

const { subscribeEvent, unsubscribeEvent } = useLiveAudienceState();
// 假设 useBarrageState 提供了 appendLocalTip 方法
const { appendLocalTip } = useBarrageState();

const handleAudienceJoin = (eventInfo) => {
const { audience } = eventInfo;
// 创建一条本地提示消息
const welcomeTip = {
messageType: 'text',
textContent: `欢迎 ${audience.userName || audience.userId} 进入直播间!`
};
// 插入本地弹幕
appendLocalTip({ message: welcomeTip });
console.log(`观众 ${audience.userName} 加入了直播间`);
};

onMounted(() => {
subscribeEvent(LiveAudienceEvent.onAudienceJoined, handleAudienceJoin);
});

onUnmounted(() => {
unsubscribeEvent(LiveAudienceEvent.onAudienceJoined, handleAudienceJoin);
});

API 文档

关于 LiveAudienceState 及其相关类的所有公开接口、属性和方法的详细信息,请参阅随 AtomicXCore 框架的官方 API 文档。本文档使用到的相关 State 如下:
State
功能描述
API 文档
LiveAudienceState
观众管理:获取实时观众列表(ID / 名称 / 头像),统计观众数量,监听观众进出事件。
BarrageState
弹幕功能:发送文本 / 自定义弹幕,维护弹幕列表,实时监听弹幕状态。

常见问题

LiveAudienceState 中的在线人数(audienceCount)是如何更新的?时机和频率是怎样的?

audienceCount 的更新并非总是实时的,其机制如下:
主动进出房间:当用户主动加入或正常退出直播间时,在线人数的变更通知会即时触发。您会很快在 LiveAudienceState 中观察到 audienceCount 的变化。
异常掉线:当用户因网络问题、应用崩溃等原因异常掉线时,系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后,系统才会判定其为离线,并触发人数变更通知。
更新机制与频率控制:
无论是即时触发还是延迟触发,所有的人数变更通知都是以消息的形式在房间内广播的。
房间内每秒的消息总量有上限,单房间消息频控是每秒 40 条消息
关键点:在“弹幕风暴”或礼物刷屏等消息流量极高的场景下,如果房间内的消息速率超过了 40条/秒 的阈值,为了保证核心消息(例如弹幕)的送达,人数变更的消息可能会被频控策略丢弃
这对开发者意味着什么?
audienceCount 是一个非常接近实时的高精度估算值,但在极端高并发场景下,它可能存在短暂的延迟或数据丢失。因此,我们建议您将其用于 UI 展示,而不应作为计费、统计等需要绝对精准场景的唯一依据。
管理员