通过本文,您将了解如何将 TUILiveKit 的观众观看页组件进行集成。接入该组件后,您将获得:
完整的 UI 界面:高清直播播放、实时弹幕互动、在线观众列表、全屏沉浸观看。
跨平台:支持 H5 移动端,多平台无缝兼容。
集成提示:
快速接入
前提条件
集成观众观看页面
新建
live-player.vue,作为观看页面的入口,负责播放直播画面、切换分辨率、画中画等,您根据指引按需引入观看端的各功能模块。将以下代码复制到该文件即可:<template><UIKitProvider language="zh-CN" theme="dark"><div class="container"><!-- 直播核心区域 --><section class="live"><header class="header"><IconArrowStrokeBack class="back-btn" size="20" /><Avatar :src="currentLive?.liveOwner.avatarUrl" :size="32" class="avatar" /><span class="user-name">{{ currentLive?.liveOwner.userName || currentLive?.liveOwner.userId }}</span></header><LiveView class="player" /></section><div class="sidebar"><!-- 在线观众列表 --><section class="audience"><header class="section-header"><h3> 在线观众 <span>({{ audienceList.length }})</span></h3></header><LiveAudienceList class="list" /></section><!-- 消息列表 & 消息输入框 --><section class="barrage"><header class="section-header"><h3>消息列表</h3></header><BarrageList class="list" /><BarrageInput class="input" height="48px" /></section></div></div></UIKitProvider></template><script setup lang="ts">import { onMounted } from 'vue';import { LiveAudienceList, BarrageList, BarrageInput, useLiveAudienceState, LiveView, useLiveListState, Avatar, useLoginState } from 'tuikit-atomicx-vue3';import { UIKitProvider, IconArrowStrokeBack } from '@tencentcloud/uikit-base-component-vue3';const { audienceList } = useLiveAudienceState();const { currentLive, joinLive } = useLiveListState();const { login, setSelfInfo } = useLoginState();const liveId = 'live_xxxx' // 填入您要观看的直播间的IDasync function initLogin() {try {await login({sdkAppId: 0, // SDKAppID, 可以参考前提条件进行获取userId: '', // UserID, 可以参考前提条件进行获取userSig: '', // userSig, 可以参考前提条件进行获取});} catch (error) {console.error('登录失败:', error);}}onMounted(async () => {await initLogin();await setSelfInfo({userName: '我的名字/昵称', // 用户名avatarUrl: '', // 头像 URL 地址});await joinLive({ liveId });});</script><style>html,body,#app{height:100%;width:100%;margin:0;padding:0;overflow:hidden}:global(body){font-size:15px;line-height:1.6;text-rendering:optimizeLegibility;}:global(*),:global(*::before),:global(*::after){box-sizing:border-box;margin:0;}.container{display:grid;grid-template-columns:1fr 320px;height:100%;width:100%;gap:16px;padding:16px;background:var(--bg-color-default);box-sizing:border-box;overflow:hidden;}.live{display:flex;flex-direction:column;background:var(--bg-color-operate);border-radius:12px;overflow:hidden;box-shadow:0 2px 8px var(--shadow-color);}.header{display:flex;align-items:center;gap:12px;padding:16px;border-bottom:1px solid var(--stroke-color-primary);}.back-btn{cursor:pointer;color:var(--text-color-tertiary);transition:color 0.2s;}.back-btn:hover{color:var(--text-color-link-hover);}.avatar{border:1px solid var(--uikit-color-white-7);}.user-name{color:var(--text-color-primary);font-weight:500;}.player{flex:1;background:var(--uikit-color-black-1);min-height:0;}.sidebar{display:flex;flex-direction:column;gap:16px;height:100%;overflow:hidden;}.audience{display:flex;flex-direction:column;background:var(--bg-color-operate);border-radius:12px;overflow:hidden;box-shadow:0 2px 8px var(--shadow-color);flex:1;min-height:0;}.barrage{display:flex;flex-direction:column;background:var(--bg-color-operate);border-radius:12px;overflow:hidden;box-shadow:0 2px 8px var(--shadow-color);flex:1;min-height:0;}.section-header{padding:16px;border-bottom:1px solid var(--stroke-color-primary);background:var(--bg-color-operate);}.section-header h3{margin:0;font-size:16px;font-weight:600;color:var(--text-color-primary);}.section-header span{font-weight:400;color:var(--text-color-secondary);font-size:14px;}.list{flex:1;min-height:0;overflow-y:auto;}.input{border-top:1px solid var(--stroke-color-primary);flex-shrink:0;height:48px;}@media (max-width:1200px){.container{grid-template-columns:1fr;grid-template-rows:60% 20% 20%;gap:12px;}.sidebar{gap:12px;}.audience,.barrage{min-height:200px;}}@media (max-width:768px){.container{padding:8px;gap:8px;grid-template-rows:50% 25% 25%;}.header,.section-header{padding:12px;}.sidebar{gap:8px;}}</style>
启动并运行示例
执行
npm run dev 成功后,在浏览器地址栏输入本地访问地址(例如 https://localhost:5173/live-player,具体端口号可能因项目配置不同而有所差异),即可看到观看页面,输入对应的房间号(liveId),即可观看对应的直播间画面。npm run dev
开启直播的两种方式:
集成观看页面成功后,可通过以下任一方式体验开播效果:
在线开播网站:打开在线开播网站,输入对应 sdkAppId 等信息,点击直播列表右上角的开始直播按钮进入开播页面,开始一场直播。
集成开播页面:在您的项目中接入 主播开播(Web 桌面浏览器)组件进行开播。
注意:
观看请使用与开播端不同的用户 ID,否则先登录的设备会被强制下线。
Web 端 | H5 端 |
![]() | ![]() |
UI 自由定制
配置皮肤主题及语言
通过配置
App.vue 中 UIKitProvider 的入参,修改主题及语言的默认值。UIKitProvider 参数 | 可选值 | 默认值 |
theme | "light" | "dark" | "light" |
language | "zh-CN" | "en-US" | "en-US" |
<UIKitProvider theme="light"><router-view /></UIKitProvider><script setup lang="ts">import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';</script>
深色主题 | 浅色主题 |
![]() | ![]() |
我们支持您根据项目需求对观众观看页面进行 UI 定制——除页面布局调整外,还可对颜色主题、字体、圆角、输入框、弹框等内容进行增删改;若需新增或替换按钮(Button)、图标(Icon)等控件,也可找到对应控件的指定位置源码,直接进行增加、删除、替换等操作,满足您的 UI 定制需要。
常见问题
浏览器自动播放限制
出于用户体验考虑,现代浏览器对网页自动播放 (Autoplay) 功能实施了限制性策略:所有带声音的媒体内容必须经过用户主动交互(如点击或触摸)后才能播放。这项限制主要是为了防止网站在用户未明确同意的情况下突然播放音频,避免对用户造成干扰。大多数浏览器都不限制无声视频的自动播放,但是在低电量模式下的 iOS Safari 浏览器中以及开启了自定义自动播放限制的 iOS WKWebView 中(例如 iOS 微信浏览器),无声视频的自动播放也会受到限制。
自动播放失败表现
当用户对该站点的媒体互动指数 (MEI, Media Engagement Index) 未达到阈值时,企图自动播放有声视频会失败。在 SDK 默认情况下,当检测到自动播放失败时,会弹窗引导用户与页面产生交互(例如点击确认按钮)。产生交互后,浏览器策略即被满足,有声视频即可正常播放。
解决方案:自定义处理自动播放失败
如果您希望自定义自动播放失败时的交互体验(例如替换默认的弹窗 UI),可以通过监听 SDK 抛出的
onAutoplayFailed 回调来实现。以下是在 Vue3 项目中,通过监听事件并弹出自定义对话框的实现代码示例:import TUIRoomEngine, { TUIRoomEvents } from '@tencentcloud/tuiroom-engine-js';import { useUIKit, TUIMessageBox } from '@tencentcloud/uikit-base-component-vue3';import { useRoomEngine } from 'tuikit-atomicx-vue3';const roomEngine = useRoomEngine();let isShowAutoPlayDialog = false;export default function useCustomizedAutoPlayDialog() {const { t } = useUIKit();TUIRoomEngine.once('ready', () => {roomEngine.instance?.on(TUIRoomEvents.onAutoPlayFailed, () => {if (!isShowAutoPlayDialog) {isShowAutoPlayDialog = true;TUIMessageBox.alert({title: t('RoomCommon.Attention'),content: t('RoomNotifications.AudioPlaybackFailed'),showClose: false,modal: false,confirmText: t('Confirm'),callback: () => {isShowAutoPlayDialog = false;},});}});});}export { useCustomizedAutoPlayDialog };
说明:
您需要安装对应的
@tencentcloud/tuiroom-engine-js,例如通过如下命令进行安装:npm install @tencentcloud/tuiroom-engine-js
下一步
恭喜您,现在您已经成功集成了观众观看功能。接下来,您可以继续接入直播列表、UI 自定义和监播等功能:
功能 | 描述 | 集成指引 |
直播列表 | 展示直播列表界面和功能,包含直播列表和房间信息展示功能。 | |
UI 自定义 | 更详细的 UI 组件自定义指引。 | |
直播管理系统 | 运营平台,支持直播间管控。 |



