文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>直播与语聊 SDK>无 UI 集成>搭建视频直播>观众连线>观众连线（Web）

观众连线（Web）

最近更新时间：2025-11-27 15:16:31

我的收藏

本页目录：

AtomicXCore 提供了 CoGuestState 模块，专门用于管理观众连麦的完整业务流程。您无需关心复杂的状态同步和信令交互，只需调用几个简单的方法，即可为您的直播添加强大的观众与主播音视频互动功能。

核心场景

CoGuestState 支持以下两种最主流的连麦场景：
观众申请上麦：观众主动发起连麦请求，主播在收到请求后进行同意或拒绝。
主播邀请上麦：主播可以主动向直播间内的任意一位观众发起连麦邀请。

实现步骤

步骤1：组件集成

请参考 开始直播 集成 AtomicXCore，并完成 LiveCoreView 的接入。
注意：
下列步骤需要参考 开始直播 中先创建房间或加入房间，随后执行下列步骤中的方法。

步骤2：实现观众申请上麦

观众端实现

作为观众，您的核心任务是发起申请、接收结果和主动下麦。
1. 发起连麦申请
当用户点击界面上的"申请连麦"按钮时，调用 applyForSeat 方法。
import { useCoGuestState } from "tuikit-atomicx-vue3";

const { applyForSeat } = useCoGuestState();

// 用户点击“申请连麦”
const handleRequestToConnect = async () => {
    try {
        await applyForSeat({ 
          seatIndex: -1, // 申请的麦位，-1 表示随机分配
          timeout: 30,   // 请求超时时间（秒），注意：TS定义单位若为毫秒请传入 30000
        });
        console.log('申请已发送');
    } catch (error) {
        console.error('申请失败', error);
    }
}
2. 监听主播的响应
通过 subscribeEvent 订阅 GuestEvent.onGuestApplicationResponded 事件，您可以接收到主播的处理结果。
import { onMounted, onUnmounted } from 'vue';
import { useCoGuestState, useDeviceState, CoGuestEvent } from "tuikit-atomicx-vue3";

const { subscribeEvent, unsubscribeEvent } = useCoGuestState();
const { openLocalMicrophone, openLocalCamera } = useDeviceState();

const handleGuestApplicationResponded = (eventInfo: any) => {
    if (eventInfo.isAccept) {
        console.log('上麦申请被同意');
        // 1. 打开麦克风和摄像头
        openLocalMicrophone();
        openLocalCamera();
        // 2. 在此更新 UI，例如变更申请按钮状态，显示为连麦中
    } else {
        console.log('上麦申请被拒绝');
        // 弹窗提示用户申请被拒绝
    }
};

// 在组件挂载时订阅事件
onMounted(() => {
    subscribeEvent(GuestEvent.onGuestApplicationResponded, handleGuestApplicationResponded);
});

// 在组件卸载时取消订阅
onUnmounted(() => {
    unsubscribeEvent(GuestEvent.onGuestApplicationResponded, handleGuestApplicationResponded);
});
3. 主动下麦
当连麦观众想结束互动时，调用 disConnect 方法即可返回普通观众状态。
import { useCoGuestState } from "tuikit-atomicx-vue3";

const { disConnect } = useCoGuestState();

// 用户点击“下麦”按钮
const leaveSeat = async () => {
    try {
        await disConnect();
        console.log('下麦成功');
    } catch (error) {
        console.log('下麦失败', error);
    }
}
4.(可选) 取消申请
如果观众在主播处理前想撤回申请，可以调用 cancelApplication。

import { useCoGuestState } from "tuikit-atomicx-vue3";

const { cancelApplication } = useCoGuestState();

// 用户在等待时，点击“取消申请”
const handleCancelRequest = async () => {
    await cancelApplication();
    console.log('取消申请成功');
}

主播端实现

作为主播，您的核心任务是接收申请、展示申请列表和处理申请。
1. 监听新的连麦申请
通过 subscribeEvent 订阅 CoHostEvent.onGuestApplicationReceived 事件后，您可以在有新观众申请时立即收到通知。
import { onMounted, onUnmounted } from 'vue';
import { useCoGuestState, CoHostEvent } from "tuikit-atomicx-vue3";

const { subscribeEvent, unsubscribeEvent } = useCoGuestState();

const handleGuestApplicationReceived = (eventInfo: any) => {
    console.log('收到观众的连麦申请:', eventInfo.guestUser);
    // 在此更新 UI，例如在"申请列表"按钮上显示红点
};

onMounted(() => {
    subscribeEvent(HostEvent.onGuestApplicationReceived, handleGuestApplicationReceived);
});

onUnmounted(() => {
    unsubscribeEvent(HostEvent.onGuestApplicationReceived, handleGuestApplicationReceived);
});
2.展示申请列表
CoGuestState 会实时维护当前的申请者列表 applicants，这是一个 Vue 的 ComputedRef，您可以直接在模板中使用。
<template>
    <div v-for="audience in applicants" :key="audience.userId" class="applicant-item">
      <span>{{ audience.userName }}</span>
      <button @click="handleAccept(audience.userId)">同意</button>
      <button @click="handleReject(audience.userId)">拒绝</button>
    </div>
</template>

<script setup lang="ts">
import { useCoGuestState } from "tuikit-atomicx-vue3";
const { applicants, acceptApplication, rejectApplication } = useCoGuestState();

const handleAccept = async (userId: string) => {
    await acceptApplication({ userId });
};

const handleReject = async (userId: string) => {
    await rejectApplication({ userId });
};
</script>

步骤3：实现主播邀请上麦

主播端实现

1. 向观众发起邀请
当主播在观众列表中选择某人并点击"邀请连麦"时，调用 inviteToSeat 方法。
import { useCoGuestState } from "tuikit-atomicx-vue3";

const { inviteToSeat } = useCoGuestState();

// 主播选择观众并发起邀请
const handleInviteToSeat = async (userId: string) => {
    try {
        await inviteToSeat({
            userId,
            seatIndex: -1, // 随机分配麦位
            timeout: 30,
        });
        console.log(`已向观众 ${userId} 发送上麦邀请`);
    } catch (error) {
        console.error('邀请失败', error);
    }
}
2.监听观众的回应
通过 subscribeEvent 订阅 CoHostEvent.onHostInvitationResponded 事件。
import { onMounted } from 'vue';
import { useCoGuestState, CoHostEvent } from "tuikit-atomicx-vue3";

const { subscribeEvent } = useCoGuestState();

onMounted(() => {
    subscribeEvent(HostEvent.onHostInvitationResponded, (eventInfo) => {
        if(eventInfo.isAccept){
            console.log(`观众 ${eventInfo.guestUser.userName} 接受了您的邀请`);
        } else {
            console.log(`观众 ${eventInfo.guestUser.userName} 拒绝了您的邀请`);
        }
    });
});

观众端实现

1.接收主播的邀请
通过 subscribeEvent 订阅 CoGuestEvent.onHostInvitationReceived 事件。
import { onMounted } from 'vue';
import { useCoGuestState, CoGuestEvent } from "tuikit-atomicx-vue3";

const { subscribeEvent } = useCoGuestState();

onMounted(() => {
    subscribeEvent(GuestEvent.onHostInvitationReceived, (eventInfo) => {
        // 在此弹出一个 Modal 对话框，让用户选择“接受”或“拒绝”
        // 保存 eventInfo.hostUser.userId 作为 inviterId
        showInviteDialog(eventInfo.hostUser.userId);
    });
});
2.响应邀请
当用户在弹出的对话框中做出选择后，调用相应的方法。
import { useCoGuestState, useDeviceState } from "tuikit-atomicx-vue3";

const { acceptInvitation, rejectInvitation } = useCoGuestState();
const { openLocalMicrophone, openLocalCamera } = useDeviceState();

// 用户点击“接受”
const handleAccept = async (inviterId: string) => {
    try {
        await acceptInvitation({ inviterId });
        // 接受后通常需要自动打开设备
        openLocalMicrophone();
        openLocalCamera();
    } catch (error) {
        console.error('接受邀请失败', error);
    }
}

// 用户点击“拒绝”
const handleReject = async (inviterId: string) => {
    await rejectInvitation({ inviterId });
}

运行效果

当您集成以上功能后，请分别使用两个观众与主播进行连麦操作，观众 A 同时打开摄像头和麦克风，观众 B 只打开麦克风，运行效果如下。


API 文档

关于 CoGuestState 及其相关类的所有公开接口、属性和方法的详细信息，请您参阅 AtomicXCore 框架的官方 API 文档。本指南使用到的相关 State 如下：
State
功能描述
API 文档
DeviceState
音视频设备控制：麦克风（开关 / 音量）、摄像头（开关 / 切换 / 画质）、屏幕共享，设备状态实时监听。
CoGuestState
观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风 / 摄像头），状态同步。
LiveSeatState
麦位信息管理：麦位列表管理、麦序管理。

常见问题

连麦功能无响应（申请/邀请/接受/拒绝均失败）

问题描述：调用 applyForSeat, acceptApplication, inviteToSeat 等方法后，没有任何效果。
原因分析：CoGuestState 依赖于底层的房间引擎状态。通常是因为并未成功加入房间，或者 useCoGuestState 调用时上下文的环境尚未初始化完成。
解决方案：请确保在调用这些方法之前，用户已经成功加入了直播间（Logged In & Entered Room）。

无法接收到连麦相关的事件通知

问题描述：观众端收不到主播的邀请，或者主播端收不到观众的申请。
原因分析：
没有正确调用 subscribeEvent。
使用了错误的 Event 枚举值（例如 HostEvent 和 GuestEvent 混用）。
解决方案：
主播端：订阅 HostEvent.onGuestApplicationReceived, HostEvent.onHostInvitationResponded。
观众端：订阅 GuestEvent.onGuestApplicationResponded, GuestEvent.onHostInvitationReceived。

连麦成功后，对方看不到我的画面或听不到我的声音

问题描述：上麦成功后，麦位列表已更新，但没有画面或声音。
原因分析：CoGuestState 仅负责信令层面的“上麦”操作（分配麦位）。推流（打开麦克风/摄像头）需要显式调用 DeviceState 的方法。
解决方案：在收到“接受申请”或“接受邀请”的回调中，务必调用 openLocalMicrophone() 和 openLocalCamera()。并且要注意浏览器的自动播放策略，确保用户与页面有过交互。
中国站
目录