一、组件构成
| 组件名称 | 具体内容 |
| 观众列表组件（LiveAudienceList） | 负责实时展示直播间在线观众的组件，提供头像、昵称展示、自定义观众标识和完整列表项定制等能力，支持通过插槽和属性进行灵活配置。 |
二、步骤1：环境配置及开通服务
在进行快速接入之前，请参考 准备工作，完成相关环境配置及开通对应服务。
三、步骤2：安装依赖
npmpnpmyarnnpm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 –savepnpm add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3yarn 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;}