直播视频组件 (Web React)

最近更新时间:2026-01-30 14:38:11

我的收藏
本文对直播视频组件(LiveView)进行了详细的介绍,您可以在已有项目中直接参考本文示例集成我们开发好的组件,也可以根据您的需求按照文档中的组件定制化部分对样式,布局进行深度的定制。


核心功能

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

组件接入

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

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

步骤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:加入直播间

在您的项目中引入并使用 LiveView 组件,可直接复制如下代码示例至您的项目中,观看对应直播间的直播视频。
LivePlayer.tsx
LivePlayer.module.scss
import React, { useCallback, useEffect } from "react";
import { MessageBox, Dialog, UIKitProvider } from "@tencentcloud/uikit-base-component-react";
import TUIRoomEngine, { TUIRoomEvents } from "@tencentcloud/tuiroom-engine-js";
import { LiveView, LiveListEvent, useLiveListState, useRoomEngine } from "tuikit-atomicx-react";
import styles from "./LivePlayer.module.scss";

interface LivePlayerProps {
className?: string;
liveId?: string;
}

const LivePlayer: React.FC<LivePlayerProps> = ({ className }) => {
const roomEngine = useRoomEngine();
const { currentLive, joinLive, subscribeEvent, unsubscribeEvent } = useLiveListState();

useEffect(() => {
if (!currentLive?.liveId) {
joinLive({ liveId: ''}); // 输入您要加入的直播间 ID,也可以是来自外部传入的组件参数或者 URL 参数等。
}
}, [currentLive?.liveId, joinLive]);

const handleAutoPlayFailed = useCallback(() => {
MessageBox.alert({
content: '内容已准备就绪,点击【播放】按钮开始播放',
confirmText: '播放',
showClose: false,
modal: false,
});
}, []);

const handleKickedOutOfLive = useCallback(() => {
Dialog.open({
content: '你已被踢出直播间',
confirmText: '确认',
className: styles.livePlayer__liveDialog,
showCancel: false,
showClose: false,
modal: true,
center: true,
onConfirm: () => {
Dialog.close();
// 这里可以添加您自己的业务逻辑,如跳转到首页或直播列表页
},
onClose: () => {
// 这里可以添加您自己的业务逻辑,如跳转到首页或直播列表页
},
});
}, []);

const handleLiveEnded = useCallback(() => {
Dialog.open({
content: '直播已结束',
confirmText: '确认',
className: styles.livePlayer__liveDialog,
showCancel: false,
showClose: false,
modal: true,
center: true,
onConfirm: () => {
Dialog.close();
// 这里可以添加您自己的业务逻辑,如跳转到首页或直播列表页
},
onClose: () => {
// 这里可以添加您自己的业务逻辑,如跳转到首页或直播列表页
},
});
}, []);

// Setup event listeners
useEffect(() => {
if (roomEngine.instance) {
roomEngine.instance.on(TUIRoomEvents.onAutoPlayFailed, handleAutoPlayFailed);
} else {
TUIRoomEngine.once("ready", () => {
roomEngine.instance?.on(TUIRoomEvents.onAutoPlayFailed, handleAutoPlayFailed);
});
}

subscribeEvent(LiveListEvent.ON_LIVE_ENDED, handleLiveEnded);
subscribeEvent(LiveListEvent.ON_KICKED_OUT_OF_LIVE, handleKickedOutOfLive);

return () => {
roomEngine.instance?.off(TUIRoomEvents.onAutoPlayFailed, handleAutoPlayFailed);
unsubscribeEvent(LiveListEvent.ON_LIVE_ENDED, handleLiveEnded);
unsubscribeEvent(LiveListEvent.ON_KICKED_OUT_OF_LIVE, handleKickedOutOfLive);
};
}, [handleAutoPlayFailed, handleLiveEnded, handleKickedOutOfLive, roomEngine.instance, subscribeEvent, unsubscribeEvent]);

return (
<UIKitProvider theme="dark">
<div className={`${styles.livePlayer} ${className || ''}`}>
<LiveView />
</div>
</UIKitProvider>
);
};

export default LivePlayer;
@mixin scrollbar {
&::-webkit-scrollbar {
width: 6px;
background: transparent;
}

&::-webkit-scrollbar-track {
background: transparent;
}

&::-webkit-scrollbar-thumb {
background: var(--uikit-color-gray-3);
border-radius: 3px;
border: 2px solid transparent;
background-clip: padding-box;

&:hover {
background: var(--uikit-color-gray-3);
}
}
}

.livePlayer {
display: flex;
width: 100%;
height: 100%;
border-radius: 8px;
overflow: hidden;
@include scrollbar;
}

.livePlayer__liveDialog {
text-align: center;
}

下一步

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