文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>直播与语聊 SDK>含 UI 集成>UI 自定义>观众列表组件>观众列表组件 (Web 桌面浏览器)

观众列表组件 (Web 桌面浏览器)

最近更新时间：2026-01-08 17:44:02

我的收藏

本页目录：

本文对观众列表组件（LiveAudienceList）进行了详细的介绍，您可以在已有项目中直接参考本文示例集成我们开发好的组件，也可以根据您的需求按照文档中的组件定制化部分对样式，布局进行深度的定制。


核心功能

功能分类
具体能力
实时观众展示
实时显示直播间在线观众列表，支持头像、昵称展示，提供清晰的观众信息视图，让主播能够直观了解观众构成。
响应式设计
组件支持桌面端和移动端两套 UI 方案，自动适配不同设备屏幕尺寸，提供一致的用户体验，满足多平台直播需求。
可定制化 UI
提供灵活的插槽机制，支持自定义观众标记、头像样式等元素，让您能够根据业务需求定制观众列表的展示效果，打造独特的视觉体验。

组件接入

步骤1：环境配置及开通服务

在进行快速接入之前，您需要参见 准备工作，满足相关环境配置及开通对应服务。

步骤2：安装依赖

npm
pnpm
yarn
npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 --save
pnpm add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3
yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3

步骤3：集成观众列表组件

在您的项目中引入并使用观众列表组件，可直接复制如下代码示例至您的项目中展示直播间观众列表。
<template>
  <UIKitProvider theme="dark">
    <div class="app">
        <div class="live-audience-container">
          <LiveAudienceList class="live-audience-list"/>
      </div>
    </div>
  </UIKitProvider>
</template>

<script setup lang="ts">
import { onMounted } from 'vue';
import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
import { LiveAudienceList, useLoginState, useLiveListState } from 'tuikit-atomicx-vue3';

const { login } = useLoginState();
const { joinLive } = useLiveListState();

async function initLogin() {
  try {
    await login({
      sdkAppId: 0,        // SDKAppID, 可以参考步骤 1 获取
      userId: '',         // UserID, 可以参考步骤 1 获取
      userSig: '',        // userSig, 可以参考步骤 1 获取
    });
  } catch (error) {
    console.error('登录失败:', error);
  }
}

onMounted(async () => {
  await initLogin();                    
  await joinLive({
    liveId: '输入对应直播间 LiveId',     // 进入直播间
  });
});
</script>

<style>.live-audience-container{display:flex;height:100%;width:300px;padding:20px}.live-audience-list{width:100%;height:100%}</style>

组件定制化

观众列表组件提供了灵活的组件自定义插槽，该插槽支持您根据自己需求调整观众标记、特殊身份标识等元素的样式与布局。下列分别给出插槽使用示例

组件插槽

名称
参数
说明
audience-mark
audience: AudienceInfo
自定义观众标记（例如徽章、身份标识等），显示在头像和昵称之间
// audience-mark 插槽使用示例
<LiveAudienceList>
   <template #audience-mark="{ audience }">
     <CustomAudienceMark :audience="audience" />
   </template>
</LiveAudienceList>
AudienceInfo 定义了直播房间中每个观众的基本信息和状态：
参数
类型
说明
userId
string
观众的唯一标识符，在整个系统中保持唯一性。
userName
string
观众在直播中显示的名称，支持中文、英文等字符，为空时显示 userId。
avatarUrl
string
观众头像的完整 URL 地址，支持 HTTPS 协议。
isMessageDisabled
boolean
观众是否被禁言，true 表示已被禁言，false 表示可以正常发言。
joinTime
number
观众进入直播间的时间戳，用于排序和统计。
interface AudienceInfo {
  userId: string;              // 观众唯一标识
  userName?: string;           // 观众显示名称（可选）
  avatarUrl?: string;          // 观众头像URL（可选）
  isMessageDisabled?: boolean; // 是否被禁言（可选）
  joinTime?: number;           // 进入时间戳（可选）
}

组件属性

属性名
类型
默认值
说明
height
string
'500px'
组件高度，支持 CSS 单位（px、%、vh 等）。
style
CSSProperties
{}
自定义样式对象，用于覆盖组件默认样式。

自定义插槽示例

为了帮助您更直观地掌握 audience-mark 插槽的定制能力，我们提供了一个综合示例。该示例演示了如何利用 AudienceInfo 数据动态渲染观众标记，具体实现了 VIP 身份高亮（根据 userId 判断）、禁言状态提示（根据 isMessageDisabled 属性）以及通用测试标签的展示。您可以直接复制下方代码，快速实现差异化的观众身份标识逻辑。
<template>
  <UIKitProvider theme="dark">
    <div class="app">
      <div class="live-audience-container">
        <LiveAudienceList class="live-audience-list">
          <template #audience-mark="slotProps">
            <!-- 始终显示的测试标记 -->
            <div class="custom-mark">
              <span class="test-badge">TEST</span>
              <span v-if="slotProps.audience && isVip(slotProps.audience.userId)" class="vip-badge">VIP</span>
              <span v-if="slotProps.audience && slotProps.audience.isMessageDisabled" class="muted-badge">🔇</span>
            </div>
          </template>
        </LiveAudienceList>
      </div>
    </div>
  </UIKitProvider>
</template>

<script setup lang="ts">
import { onMounted } from 'vue';
import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
import { LiveAudienceList, useLoginState, useLiveListState } from 'tuikit-atomicx-vue3';

// 示例：判断是否为 VIP 用户
const vipUserIds = ['user_vip_001', 'user_vip_002']; // 添加当前用户ID用于测试
const isVip = (userId: string) => {
  console.log('检查VIP状态:', userId, vipUserIds.includes(userId));
  return vipUserIds.includes(userId);
};

const { login } = useLoginState();
const { joinLive } = useLiveListState();

async function initLogin() {
  try {
    await login({
      sdkAppId: 0,        // SDKAppID, 可以参考步骤 1 获取
      userId: '',         // UserID, 可以参考步骤 1 获取
      userSig: '',        // userSig, 可以参考步骤 1 获取
    });
  } catch (error) {
    console.error('登录失败:', error);
  }
}

onMounted(async () => {
  await initLogin();                    
  await joinLive({
    liveId: '输入对应直播间 LiveId',     // 进入直播间
  });
});
</script>

<style>.custom-mark{display:flex;align-items:center;gap:4px}.test-badge{background:#666;color:#fff;font-size:10px;font-weight:600;padding:2px 6px;border-radius:4px}.vip-badge{background:linear-gradient(135deg,#ffd700,#ffb347);color:#fff;font-size:10px;font-weight:600;padding:2px 6px;border-radius:4px}.muted-badge{font-size:14px;opacity:.7}.live-audience-container{display:flex;height:100%;width:300px;padding:20px}.live-audience-list{width:100%;height:100%}</style>
中国站
目录