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

观众列表组件 (Web React)

最近更新时间：2026-01-29 11:14:13

我的收藏

本页目录：

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


核心功能

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

组件接入

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

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

步骤2：安装依赖

npm
pnpm
yarn
npm install tuikit-atomicx-react @tencentcloud/uikit-base-component-react --save
npm install sass --save-dev
pnpm add tuikit-atomicx-react @tencentcloud/uikit-base-component-react
pnpm add sass --dev
yarn add tuikit-atomicx-react @tencentcloud/uikit-base-component-react
yarn add sass --dev

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

在您的项目中引入并使用观众列表组件，可直接复制如下代码示例至您的项目中展示直播间观众列表。
AudienceList.tsx
AudienceList.module.scss
import React from "react";
import { useUIKit } from "@tencentcloud/uikit-base-component-react";
import { useLiveAudienceState, LiveAudienceList } from "tuikit-atomicx-react";
import styles from "./AudienceList.module.scss";

const AudienceList: React.FC = () => {
  const { t } = useUIKit();
  const { audienceCount } = useLiveAudienceState();

  return (
    <div className={styles.livePlayer__audienceList}>
      <div className={styles.livePlayer__audienceListTitle}>
        <span>{t('live_player_view.audience_list_title')} </span>
        <span className={styles.livePlayer__audienceCount}>({audienceCount})</span>
      </div>
      <div className={styles.livePlayer__audienceListContent}>
        <LiveAudienceList height="100%" />
      </div>
    </div>
  );
};

export default AudienceList;
.livePlayer__audienceList {
  display: flex;
  flex-direction: column;
  flex-shrink: 0;
  height: 30%;
  padding: 8px;
  background: var(--uikit-bg-color-operate);

  .livePlayer__audienceListTitle {
    padding: 12px 0;
    border-bottom: 1px solid var(--uikit-stroke-color-primary);
    @include text-size-16;
  }

  .livePlayer__audienceCount {
    font-weight: 400;
    color: var(--uikit-text-color-secondary);
  }

  .livePlayer__audienceListContent {
    flex: 1;
    overflow: hidden;
  }
}

组件定制化

组件属性

LiveAudienceList 组件属性

Props 属性
类型
默认值
是否必填
说明
children
(params: { audience: AudienceInfo; }) => React.ReactNode
-
否
自定义观众标记（例如徽章、身份标识等），显示在头像和昵称之间。
className
String
-
否
自定义 CSS class 类型名
style
CSSProperties
-
否
自定义 CSS 样式
height
String
-
否
观众列表高度。

AudienceInfo 数据类型

属性
类型
默认值
说明
userId
String
-
观众 ID
userName
String
-
观众名称（昵称）
avatarUrl
String
-
观众头像地址
userRole
Number
2
观众角色。
0：直播间房主
1：直播间管理员
2：普通观众
isMessageDisabled
Boolean
false
是否被禁止发送文字、表情消息。
joinedTimestamp
Number
0
观众进入直播间的时间。
customInfo
Record<String, any>
-
用户自定义属性

自定义示例 

import { LiveAudienceList } from 'tuikit-atomicx-react';
import type { AudienceInfo } from 'tuikit-atomicx-react';

// 自定义组件属性，必须与 LiveAudienceList 组件 children 属性相同
interface CustomAudienceProps {
  params: {audience: AudienceInfo} 
}

// 用户自定义组件，显示用户角色
const CustomAudience: React.FC<CustomAudienceProps> = ({ params }) => {
  return (
    <div className="custom-audience-item">
      {
        params.audience.userRole === 2 ? "[观众]" : (params.audience.userRole === 1 ? "[管理员]" : "[主播]")
      }
    </div>
  );
};

const LivePlayer: React.FC<LivePlayerProps> = ({ className }) => {
  return (
    <div className={`${styles.livePlayer} ${className || ''}`}>
          <div className={styles.livePlayer__audienceListContent}>
            {/* 设置 height、className、style 属性 */}
            <LiveAudienceList height="100%" className="my-class-name" style={{backgroundColor: "transparent"}}>
              {(params) => <CustomAudience params={params} />} {/* 在播放页观众列表中，使用自定义组件， 显示用户角色 */}
            </LiveAudienceList>
          </div>
    </div>
  );
};

下一步

接入直播视频组件后，您可能还想继续接入弹幕消息、礼物等功能，可以参阅下表指引文档，继续接入这些功能。
功能
描述
集成指引
聊天弹幕组件
支持发送、接收并显示文字、表情消息。
聊天弹幕组件 (Web React)
直播送礼组件
展示配置的礼物列表，支持发送礼物、礼物播放。
直播送礼组件 (Web React)

中国站
目录