产品动态
产品近期公告
关于 TRTC Live 正式上线的公告
关于TRTC Conference 正式版上线的公告
Conference 商业化版本即将推出
关于多人音视频 Conference 开启内测公告
关于音视频通话 Call 正式版上线的公告
关于腾讯云音视频终端 SDK 播放升级及新增授权校验的公告
关于 TRTC 应用订阅套餐服务上线的相关说明
观众列表（Web）
LiveAudienceState 是 AtomicXCore 中专门负责管理直播间观众信息的模块。通过 LiveAudienceState 您可以为您的直播应用构建一套完整的观众列表及管理系统。
核心功能
实时观众列表：获取并展示当前在直播间内的所有观众信息。
观众人数统计：实时获取当前直播间的准确观众总数。
观众动态监听：通过事件订阅，实时感知观众的加入和离开。
管理员权限：主播可设置或取消管理员权限。
房间管理：主播或管理员可将普通观众踢出直播间。
示例项目
实现步骤
步骤1：组件集成
步骤2：初始化并获取观众列表
获取
LiveAudienceState 实例，并主动拉取一次当前的观众列表，用于首次展示。该模块内部会自动监听当前直播间状态的变化，当切换直播间时会自动更新观众列表。import { onMounted, watch } from 'vue';import { useLiveAudienceState } from "tuikit-atomicx-vue3";// 获取 LiveAudienceState 的实例const { fetchAudienceList, audienceList } = useLiveAudienceState();onMounted(async () => {try {// 获取观众列表，返回 Promiseawait fetchAudienceList();console.log('首次拉取观众列表成功');} catch (error) {console.error('首次拉取观众列表失败', error);}});// 监听 audienceList 的实时变更，用于驱动 UI 变更watch(audienceList, (newVal) => {console.log('观众列表更新:', newVal);});
步骤3：监听观众列表状态与实时动态
订阅和监听
audienceState 的 event 和 响应式数据，用来接收全量列表快照和实时的观众进出事件，从而驱动 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 主播可设置或取消管理员权限
通过
setAdministrator 和 revokeAdministrator 接口可以管理用户的管理员身份。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 中的在线人数（audienceCount）是如何更新的？时机和频率是怎样的？
audienceCount 的更新并非总是实时的，其机制如下：主动进出房间：当用户主动加入或正常退出直播间时，在线人数的变更通知会即时触发。您会很快在
LiveAudienceState 中观察到 audienceCount 的变化。异常掉线：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。
更新机制与频率控制：
无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。
房间内每秒的消息总量有上限，单房间消息频控是每秒 40 条消息。
关键点：在“弹幕风暴”或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，人数变更的消息可能会被频控策略丢弃。
这对开发者意味着什么？
audienceCount 是一个非常接近实时的高精度估算值，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 UI 展示，而不应作为计费、统计等需要绝对精准场景的唯一依据。管理员
文档反馈