实时音视频观众列表组件 (Web Vue3)

TUILiveKit 观众列表组件为直播场景提供实时在线观众展示方案，帮助开发者直观掌握直播间观众构成。通过本文档，可快速集成观众列表功能，并支持深度定制以满足业务需求。
﻿
组件构成
组件名称
具体内容
观众列表组件（LiveAudienceList）
负责实时展示直播间在线观众的组件，提供头像、昵称展示、自定义观众标识和完整列表项定制等能力，支持通过插槽和属性进行灵活配置。
组件接入
步骤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>
自定义组件
观众列表组件提供了灵活的自定义能力，您可以根据业务需求选择不同的定制方式：
定制场景
推荐方式
说明
仅调整组件容器的高度、样式等
Props: height / style
最简单，几行属性配置即可实现。
在观众头像和昵称之间添加自定义标识（如 VIP 徽章、禁言标识）
Slot: audience-mark
通过插槽注入自定义标识元素，保留默认的列表项布局。
完全替换整个观众列表项的渲染，实现排名、自定义布局等
Slot: audience-item
最灵活，完全接管每个列表项的渲染逻辑。优先级高于 audience-mark。
修改前
修改后
﻿
﻿
自定义观众标识（audience-mark）
完全接管列表项渲染（audience-item）
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
自定义观众标识（audience-mark 插槽）
通过 audience-mark 插槽，您可以在观众头像和昵称之间插入自定义标识元素（例如 VIP 徽章、禁言状态等），同时保留组件默认的列表项布局。
插槽参数
插槽名
参数名
参数类型
说明
audience-mark
audience
﻿AudienceInfo﻿
当前观众信息对象，包含 userId、userName、avatarUrl、isMessageDisabled 等字段。
以下示例演示了如何根据观众数据动态渲染 VIP 身份徽章和禁言状态标识：
<template>
  <LiveAudienceList>
    <template #audience-mark="{ audience }">
      <div class="custom-mark">
        <span v-if="isVip(audience.userId)" class="vip-badge">VIP</span>
        <span v-if="audience.isMessageDisabled" class="muted-badge">🔇</span>
      </div>
    </template>
  </LiveAudienceList>
</template>
﻿
<script setup lang="ts">
import { LiveAudienceList } from 'tuikit-atomicx-vue3';
﻿
const vipUserIds = ['user_vip_001', 'user_vip_002'];
const isVip = (userId: string) => vipUserIds.includes(userId);
</script>
﻿
<style scoped>.custom-mark{display:flex;align-items:center;gap: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}</style>
完全接管列表项渲染（audience-item 插槽）
使用 audience-item 插槽可获取观众的完整信息和列表索引，自由实现排名、自定义布局等效果。
插槽参数
插槽名
参数名
参数类型
说明
audience-item
index
number
当前观众在列表中的索引位置。
﻿
audience
﻿AudienceInfo﻿
当前观众信息对象，包含 userId、userName、avatarUrl 等字段。
以下示例演示了如何利用 index 和 audience 数据实现带排名奖牌的观众列表：
<template>
  <LiveAudienceList>
    <template #audience-item="{ index, audience }">
      <div class="custom-audience-item">
        <span v-if="index === 0" class="medal">🥇</span>
        <span v-else-if="index === 1" class="medal">🥈</span>
        <span v-else-if="index === 2" class="medal">🥉</span>
        <span v-else class="rank-number">{{ index + 1 }}</span>
        <img :src="audience.avatarUrl" class="avatar" />
        <span class="name">{{ audience.userName || audience.userId }}</span>
      </div>
    </template>
  </LiveAudienceList>
</template>
﻿
<script setup lang="ts">
import { LiveAudienceList } from 'tuikit-atomicx-vue3';
</script>
﻿
<style scoped>.custom-audience-item{display:flex;align-items:center;gap:10px;padding:8px 12px;border-radius:10px;background:rgba(255,255,255,0.05)}.medal{font-size:20px}.rank-number{font-size:14px;font-weight:600;color:rgba(255,255,255,0.5);min-width:24px;text-align:center}.avatar{width:36px;height:36px;border-radius:50%;object-fit:cover}.name{font-size:14px;color:rgba(255,255,255,0.85);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}</style>
props 速查表
参数名
参数类型
默认值
说明
height
String
'500px'
组件高度，支持 CSS 单位（px、%、vh 等）。
style
CSSProperties
{}
自定义样式对象，用于覆盖组件默认样式。
常见问题
如何区分房主和观众？
您可以通过 useLiveListState 获取当前直播间信息，将观众的 userId 与直播间 ownerId 对比来判断：
import { useLiveListState } from 'tuikit-atomicx-vue3';
﻿
const { currentLive } = useLiveListState();
﻿
function isLiveOwner(userId: string): boolean {
  return userId === currentLive.value?.liveOwner.userId;
}

组件名称	具体内容
观众列表组件（LiveAudienceList）	负责实时展示直播间在线观众的组件，提供头像、昵称展示、自定义观众标识和完整列表项定制等能力，支持通过插槽和属性进行灵活配置。

修改前	修改后
修改前		自定义观众标识（audience-mark）	完全接管列表项渲染（audience-item）

定制场景	推荐方式	说明
仅调整组件容器的高度、样式等	Props: `height` / `style`	最简单，几行属性配置即可实现。
在观众头像和昵称之间添加自定义标识（如 VIP 徽章、禁言标识）	Slot: `audience-mark`	通过插槽注入自定义标识元素，保留默认的列表项布局。
完全替换整个观众列表项的渲染，实现排名、自定义布局等	Slot: `audience-item`	最灵活，完全接管每个列表项的渲染逻辑。优先级高于 `audience-mark`。

插槽名	参数名	参数类型	说明
audience-mark	audience	AudienceInfo	当前观众信息对象，包含 `userId`、`userName`、`avatarUrl`、`isMessageDisabled` 等字段。

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

观众列表组件 (Web Vue3)

本页目录：

组件构成

组件接入

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

步骤2：安装依赖

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

自定义组件

自定义观众标识（audience-mark 插槽）

插槽参数

完全接管列表项渲染（audience-item 插槽）

插槽参数

props 速查表

常见问题

如何区分房主和观众？