实时音视频直播视频组件 (Web 桌面浏览器)

本文对直播视频组件（LiveView）进行了详细的介绍，您可以在已有项目中直接参考本文示例集成我们开发好的组件，也可以根据您的需求按照文档中的组件定制化部分对样式，布局进行深度的定制。
﻿
核心功能
功能分类
具体能力
智能流切换
LiveView 能够根据当前用户的身份（观众或连麦者）自动切换流类型。
观众模式： 组件将播放超低延迟视频流，确保数百万观众都能流畅观看，同时大幅节省流量成本。
连线模式： 组件会自动切换到实时音视频流，提供毫秒级的超低延迟，保证连线用户之间实时、清晰的互动体验。
可定制化 UI
为了满足多样化的业务场景，LiveView 提供组件 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：加入直播间并进行连麦
在您的项目中引入并使用 LiveView，可直接复制如下代码示例至您的项目中加入对应直播间进行连麦。
<template>
  <UIKitProvider theme="dark">
    <div class="app">
      <LiveView />
    </div>
  </UIKitProvider>
</template>
﻿
<script setup lang="ts">
import { onMounted } from 'vue';
import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
import { LiveView, useLoginState, useLiveListState, useCoGuestState } from 'tuikit-atomicx-vue3';
﻿
const { login } = useLoginState();
const { joinLive } = useLiveListState();
const { applyForSeat } = useCoGuestState();
﻿
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: '已经存在的直播间 Id',   // 观众进入直播间之后， LiveView 自动播放超低延时流
  })
  await applyForSeat({ seatIndex: 1, timeout: 60 });     // 观众端通过调用相应方法即可加入直播间并根据需要上下麦,观众成功上麦之后，LiveView 自动播放实时音视频流
});
</script>
﻿
<style>.app {width: 100vw; height: 100vh; display: flex; justify-content: center; align-items: center}</style>
组件定制化
﻿LiveView 提供两种自定义能力：通过 控制栏配置 灵活控制内置按钮的显示与禁用状态；通过 Slot（插槽） 在视频流上叠加自定义内容，如调整连麦用户的头像、昵称、设备状态等元素的样式与布局。
自定义播放器控制栏
﻿LiveView 内置了播放器控制栏（播放/暂停、音量、清晰度、画中画、全屏等按钮）。通过 LivePlayerState ，您可以 控制播放行为、定制控制栏按钮、添加自定义按钮、监听播放器事件。
﻿
隐藏/禁用内置按钮
﻿buttons 对象包含所有内置按钮（play、volume、resolution、pictureInPicture、fullscreen），直接修改即可实时生效。
说明：Play 和 Pause 合并为单个 play 按钮，组件根据播放状态自动切换图标。icon 表示按钮未被点击时（默认态）显示的图标，activeIcon 表示按钮被点击激活后显示的图标。对于 Play 按钮，进入直播间默认处于播放状态，此时显示 icon（暂停图标）；用户点击暂停后显示 activeIcon（播放图标）。
每个按钮支持以下属性（ ButtonState ）：
属性
类型
说明
visible
boolean
是否显示按钮。
disabled
boolean
是否禁用按钮。
icon
Component | (() => VNode)
自定义按钮默认态图标。
Play 按钮：播放时显示（即“暂停”图标，点击可暂停）。
Volume 按钮：未静音时显示（即“喇叭”图标）。
PictureInPicture 按钮：非画中画时显示。
Fullscreen 按钮：非全屏时显示。
activeIcon
Component | (() => VNode)
﻿
自定义按钮激活态图标。
Play 按钮：暂停时显示（即“播放”图标，点击可恢复播放）。
Volume 按钮：静音时显示（即“静音”图标）。
PictureInPicture 按钮：画中画模式下显示。
Fullscreen 按钮：全屏模式下显示。
tooltip
string
鼠标悬浮时的提示文案。
<script setup lang="ts">
import { useLivePlayerState } from 'tuikit-atomicx-vue3';
import MyPauseIcon from './icons/MyPauseIcon.vue';
import MyPlayIcon from './icons/MyPlayIcon.vue';
import MyVolumeOnIcon from './icons/MyVolumeOnIcon.vue';
import MyVolumeOffIcon from './icons/MyVolumeOffIcon.vue';
﻿
const { buttons } = useLivePlayerState();
﻿
// 隐藏/禁用按钮
buttons.pictureInPicture.visible = false;       // 隐藏画中画按钮
buttons.fullscreen.disabled = true;             // 禁用全屏按钮
﻿
// 自定义图标
buttons.play.icon = MyPauseIcon;                // 默认：播放时显示（暂停按钮图标）
buttons.play.activeIcon = MyPlayIcon;           // 激活：暂停时显示（恢复播放图标）
buttons.volume.icon = MyVolumeOnIcon;           // 默认值：未静音时显示
buttons.volume.activeIcon = MyVolumeOffIcon;    // 激活：静音时显示
﻿
// 自定义工具提示
buttons.resolution.tooltip = 'Switch Quality';
</script>
添加自定义按钮
通过 addCustomButtons 在控制栏添加业务按钮（例如分享、刷新）：
<script setup lang="ts">
import { useLivePlayerState } from 'tuikit-atomicx-vue3';
import ShareIcon from './icons/ShareIcon.vue';
﻿
const { addCustomButtons, refresh } = useLivePlayerState();
﻿
addCustomButtons([
  {
    id: 'share',
    icon: ShareIcon,
    onClick: () => navigator.clipboard.writeText(window.location.href),
    tooltip: 'Share',
    position: 'end',  // 'start' | 'end' | { slot: 'left'|'center'|'right' } | { anchor: ButtonId, position: 'before'|'after' }
  },
]);
</script>
监听播放器事件
支持的事件有：playStateChange、volumeChange、fullscreenChange、pictureInPictureChange、resolutionChange、controlBarVisibilityChange。
<script setup lang="ts">
import { useLivePlayerState } from 'tuikit-atomicx-vue3';
﻿
const { subscribeEvent } = useLivePlayerState();
﻿
// 根据全屏状态显示/隐藏直播间标题
subscribeEvent('fullscreenChange', (isFullscreen: boolean) => {
  titleVisible.value = !isFullscreen;
});
﻿
// 根据控制栏显隐状态同步显示/隐藏房间名称
subscribeEvent('controlBarVisibilityChange', (visible: boolean) => {
  roomNameVisible.value = visible;
});
</script>
播放控制
<script setup lang="ts">
import { useLivePlayerState } from 'tuikit-atomicx-vue3';
﻿
const {
  isPlaying, currentVolume, isMuted, isFullscreen,        // 响应式状态
  isPictureInPicture, controlBarVisible,                  // 响应式状态
  currentResolution, resolutionList,                      // 响应式状态
  buttons,                                                // 内置按钮配置
  pause, resume, refresh,                                 // 播放控制
  setVolume, mute, unmute,                                // 音量控制
  requestFullscreen, exitFullscreen,                      // 全屏
  requestPictureInPicture, exitPictureInPicture,          // 画中画
  switchResolution,                                       // 清晰度切换
  showControlBar, hideControlBar, setAutoHideDelay,       // 控制栏显隐
  addCustomButtons,                                       // 自定义按钮
  subscribeEvent, unsubscribeEvent,                       // 事件订阅
} = useLivePlayerState();
</script>
组件插槽
插槽参数
名称
参数
参数类型
SeatUserInfo
﻿center-overlay﻿
-
-
无参数。插槽内容会居中叠加在视频流上层，适合放置暂停按钮、水印等自定义元素。
﻿streamViewUI﻿
userInfo
﻿SeatUserInfo﻿
当前麦位上的用户信息，包含 userId、userName、avatarUrl、microphoneStatus、cameraStatus 等字段。如果麦位为空，则 userInfo.userId 为空字符串。
center-overlay 插槽
使用 center-overlay 插槽可以在视频流上层叠加自定义内容，不影响底层视频播放。适合放置水印、暂停按钮、视频刷新时 Loading 等覆盖层元素。
﻿
基本用法
<LiveView>
  <template #center-overlay>
    <div class="watermark">LIVE</div>
  </template>
</LiveView>
streamViewUI 插槽
使用 streamViewUI 插槽可以完全接管每个麦位的 UI 渲染。您将获得当前麦位的用户信息，可自由实现主播/观众标识、设备状态展示、自定义布局等。
﻿
基本用法
<LiveView>
  <template #streamViewUI="{ userInfo }">
    <div class="custom-stream-ui">
      <span class="user-name">{{ userInfo.userName }}</span>
    </div>
  </template>
</LiveView>
自定义连麦 UI 示例
<template>
  <LiveView>
    <template #streamViewUI="{ userInfo }">
      <div class="live-stream-view">
        <div class="user-overlay">
          <div class="user-badge" :class="{ 'anchor-badge': isAnchor(userInfo) }">
            {{ isAnchor(userInfo) ? '主播' : '观众' }}
          </div>
          <div class="user-name">{{ userInfo.userName }}</div>
          <div class="device-status">
            <span :class="['mic', userInfo.microphoneStatus]"></span>
            <span :class="['camera', userInfo.cameraStatus]"></span>
          </div>
        </div>
      </div>
    </template>
  </LiveView>
</template>
﻿
<script setup lang="ts">
import { LiveView } from 'tuikit-atomicx-vue3';
import type { SeatUserInfo } from 'tuikit-atomicx-vue3';
﻿
// 判断是否为主播（根据业务逻辑）
const isAnchor = (userInfo: SeatUserInfo) => {
  // 这里可以根据用户ID、角色等判断
  return userInfo.userId.includes('anchor') || userInfo.userName.includes('主播');
};
</script>
﻿
<style scoped>.live-stream-view{position:relative;width:100%;height:100%;border-radius:8px;overflow:hidden}.live-stream-view.is-anchor{border:3px solid #ff6b35;box-shadow:0 0 20px rgba(255,107,53,.3)}.live-stream-view.is-guest{border:1px solid #ddd}.video-area{width:100%;height:100%;background:#000}.user-overlay{position:absolute;bottom:0;left:0;right:0;background:linear-gradient(transparent,rgba(0,0,0,.8));padding:10px;color:#fff}.user-badge{display:inline-block;padding:2px 8px;border-radius:10px;font-size:12px;margin-bottom:5px;background:#666}.anchor-badge{background:#ff6b35;color:#fff}.user-name{font-weight:700;margin-bottom:5px}.device-status span{margin-right:5px;opacity:.8}.device-status .mic.Off,.device-status .camera.Off{opacity:.3}</style>
常见问题
如何解决浏览器自动播放受限导致的黑屏问题？
出于用户体验考虑，现代浏览器对网页自动播放功能实施了限制性策略。您可以参考如下代码自定义播放受限弹窗，引导用户与页面交互后恢复播放。
import TUIRoomEngine, { TUIAutoPlayCallbackInfo, TUIRoomEvents } from '@tencentcloud/tuiroom-engine-js';
import { useRoomEngine } from 'tuikit-atomicx-vue3';
﻿
const roomEngine = useRoomEngine();
﻿
TUIRoomEngine.once('ready', () => {
  roomEngine.instance?.on(TUIRoomEvents.onAutoPlayFailed, handleAutoPlayFailed);
});
﻿
function handleAutoPlayFailed(event: TUIAutoPlayCallbackInfo) {
  // 可以自行弹窗引导用户与页面发生交互，交互后调用 event.resume() 方法恢复播放
  TUIMessageBox.alert({
    content: 'Content is ready. Click the button to start playback',
    confirmText: 'Play',
    callback: () => {
      event.resume();
    }
  });
}

功能分类	具体能力
智能流切换	LiveView 能够根据当前用户的身份（观众或连麦者）自动切换流类型。观众模式：组件将播放超低延迟视频流，确保数百万观众都能流畅观看，同时大幅节省流量成本。连线模式：组件会自动切换到实时音视频流，提供毫秒级的超低延迟，保证连线用户之间实时、清晰的互动体验。
可定制化 UI	为了满足多样化的业务场景，LiveView 提供组件 UI 自定义插槽，让您能够完全掌控连麦用户的视频流区域，重写其 UI 展示，灵活定义连麦用户的头像、昵称、状态等信息，轻松打造符合您品牌风格的独特视觉体验。

属性	类型	说明
visible	boolean	是否显示按钮。
disabled	boolean	是否禁用按钮。
icon	Component \| (() => VNode)	自定义按钮默认态图标。 Play 按钮：播放时显示（即“暂停”图标，点击可暂停）。 Volume 按钮：未静音时显示（即“喇叭”图标）。 PictureInPicture 按钮：非画中画时显示。 Fullscreen 按钮：非全屏时显示。
activeIcon	Component \| (() => VNode)	自定义按钮激活态图标。 Play 按钮：暂停时显示（即“播放”图标，点击可恢复播放）。 Volume 按钮：静音时显示（即“静音”图标）。 PictureInPicture 按钮：画中画模式下显示。 Fullscreen 按钮：全屏模式下显示。
tooltip	string	鼠标悬浮时的提示文案。

名称	参数	参数类型	SeatUserInfo
center-overlay	-	-	无参数。插槽内容会居中叠加在视频流上层，适合放置暂停按钮、水印等自定义元素。
streamViewUI	userInfo	SeatUserInfo	当前麦位上的用户信息，包含 `userId`、`userName`、`avatarUrl`、`microphoneStatus`、`cameraStatus` 等字段。如果麦位为空，则 `userInfo.userId` 为空字符串。

直播视频组件 (Web 桌面浏览器)

本页目录：

核心功能

组件接入

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

步骤2: 安装依赖

步骤3：加入直播间并进行连麦

组件定制化

自定义播放器控制栏

隐藏/禁用内置按钮

添加自定义按钮

监听播放器事件

播放控制

组件插槽

插槽参数

center-overlay 插槽

基本用法

streamViewUI 插槽

基本用法

自定义连麦 UI 示例

常见问题

如何解决浏览器自动播放受限导致的黑屏问题？