Only the Chinese version of this page is provided currently. The English version will be provided soon.

弹幕组件 (Web 桌面浏览器)

Last updated: 2026-03-25 11:38:23

本文对弹幕组件进行了详细的介绍,其中包含弹幕消息组件(BarrageList消息发送组件(BarrageInput)。您可以在已有项目中直接参考本文示例集成我们开发好的整体组件,也可以根据您的需求按照文档中的组件自定义部分对样式和布局进行深度的定制。


组件构成

组件名称
具体内容
弹幕消息组件(BarrageList)
负责实时展示和管理弹幕消息流的组件,提供消息列表渲染、时间聚合、用户交互和响应式适配等完整的消息展示解决方案。
消息发送组件(BarrageInput)
提供富文本编辑和消息发送功能的输入组件,集成表情选择器、字符限制、状态管理和跨平台适配,为用户提供流畅的消息输入体验。

组件接入

步骤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:集成弹幕组件

在您的项目中引入并使用弹幕组件,可直接复制如下示例至您的项目中展示完整的直播间弹幕消息组件以及消息发送组件
<template>
<UIKitProvider theme="dark">
<div class="app">
<div class="chat-container">
<div class="chat-content">
<BarrageList class="barrage-list" />
</div>
<div class="chat-input">
<BarrageInput class="barrage-input" />
</div>
</div>
</div>
</UIKitProvider>
</template>

<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
import { BarrageList, BarrageInput, 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', // 输入对应 liveId 进入直播间
});
});
</script>

<style scoped>.app{width:100vw;height:100vh;display:flex;justify-content:center;align-items:center;padding:20px;box-sizing:border-box}.chat-container{width:100%;max-width:500px;height:600px;border-radius:16px;display:flex;flex-direction:column;overflow:hidden}.chat-content{flex:1;overflow:hidden}.barrage-list{width:100%;height:100%}.chat-input{background-color:var(--bg-color-dialog);padding:16px}.barrage-input{width:100%}</style>

自定义组件

弹幕消息组件分别为用户自定义需求提供了丰富且多维度的 Props 接口和 Slot 插槽,允许用户自定义功能或自定义 UI 等,具体参数内容如下表所示。
说明:
若您需要直接了解弹幕消息组件(BarrageList)的自定义详细内容可跳转到如下链接:弹幕消息组件自定义
若您需要直接了解消息发送组件(BarrageInput)的自定义详细内容可跳转到如下链接:消息发送组件自定义

弹幕消息组件(BarrageList)自定义

弹幕消息组件提供了 Props(属性配置)和 Slot(插槽)两种自定义方式,满足不同层次的定制需求:
Props:通过属性配置自定义样式和替换子组件,适合简单的样式调整。
Slot:通过 message-item 插槽完全接管消息渲染,适合深度定制消息展示逻辑。

Props

参数名
参数类型
默认值
说明
Message
Component
Message
自定义消息组件。
containerStyle
CSSProperties
-
自定义消息列表容器样式。
itemStyle
CSSProperties
-
自定义单条消息项样式。
height
String
-
组件高度,支持CSS单位。
style
CSSProperties
-
指定根元素自定义样式。
如上表所示,弹幕消息组件的 Props 自定义部分由两块内容组成,分别为可替换子组件、自定义样式,具体内容如下表所示。
内容
参数
可替换子组件
Message
自定义样式
containerStyleitemStyleheightstyle

自定义样式

弹幕消息组件提供了 containerStyleitemStyle自定义子组件 等内容,用于自定义组件样式。
1. 要自定义消息列表容器样式,您可以给 containerStyle 属性传递一个样式对象。
示例:自定义容器内边距
<BarrageList :containerStyle="{ padding: '0px' }" />
2. 要自定义单条消息样式,您可以给 itemStyle 属性传递一个样式对象。
示例:自定义消息项间距和边框及消息气泡颜色
<BarrageList :itemStyle="{ borderRadius: '10px', background: '#1C66e5', padding: '10px', boxSizing: 'border-box'}" />
3. 弹幕消息组件支持自定义消息展示组件,您可以完全控制消息的渲染方式。
示例:自定义消息组件
// MyCustomMessage.vue
<template>
<div class="custom-message">
<div class="message-header">
<span class="user-name">{{ getSenderName(message) }}</span>
<span class="message-time">{{ formatTime(message.timestampInSecond) }}</span>
</div>
<div class="message-content">
{{ getMessageText(message) }}
</div>
</div>
</template>
<script setup lang="ts">
import type { Barrage } from 'tuikit-atomicx-vue3';
interface Props {
message: Barrage;
isLastInChunk?: boolean;
}
const props = defineProps<Props>();
const formatTime = (timestampInSecond: number) => {
return new Date(timestampInSecond * 1000).toLocaleTimeString('zh-CN', {
hour: '2-digit',
minute: '2-digit'
});
};
const getSenderName = (message: Barrage) => {
const sender = message.sender;
return sender.nameCard || sender.userName || sender.userId || '匿名用户';
};
const getMessageText = (message: Barrage) => {
if (message.textContent) {
return message.textContent;
}
if (message.data) {
try {
const data = JSON.parse(message.data);
if (data.type === 'gift') {
return `🎁 送出了 ${data.giftInfo?.name || '礼物'} x${data.count || 1}`;
}
} catch {
// data 解析失败,忽略
}
}
return '';
};
</script>
<style scoped>.custom-message{background:linear-gradient(135deg,#667eea 0%,#764ba2 100%);color:white;padding:12px;border-radius:12px;margin:4px 0;box-shadow:0 2px 8px rgba(0,0,0,0.1);transition:transform 0.2s ease}.custom-message:hover{transform:translateY(-2px)}.message-header{display:flex;justify-content:space-between;align-items:center;margin-bottom:8px;font-size:12px;opacity:0.9}.user-name{font-weight:500;max-width:120px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.message-time{font-size:11px;opacity:0.7}.message-content{font-size:14px;line-height:1.4;word-break:break-word}</style>
// 在 弹幕消息组件 中使用
<template>
<BarrageList :Message="MyCustomMessage" />
</template>
<script setup lang="ts">
import MyCustomMessage from "./MyCustomMessage.vue";
</script>
修改前
修改后
自定义容器内边距
自定义消息项间距和边框
自定义消息组件





Slot 插槽

弹幕消息组件提供了 message-item 插槽,允许您完全自定义每条弹幕消息的渲染方式。使用此插槽后,所有消息(包括礼物消息)都会通过插槽传递。
说明:
1. message-item 插槽的优先级高于 Message Props,两者同时使用时以插槽为准。
2. PC 和 H5 两端的插槽行为一致,所有消息(包括礼物消息)都会传递给插槽。
3. 不使用插槽时,H5 端默认不渲染礼物消息(礼物消息在独立的礼物区域展示)。

插槽参数
插槽名
参数名
参数类型
说明
message-item
message
Barrage
当前弹幕消息对象,包含 textContent(文本内容)、sender(发送者)、messageType(消息类型)、data(自定义数据 JSON 字符串)等字段。
sender
发送者信息,包含 userIduserNameavatarUrl 等字段。
基本用法
通过 #message-item 插槽自定义每条弹幕消息的展示:
<BarrageList>
<template #message-item="{ message, sender }">
<div class="custom-barrage-item">
<span class="sender-name">{{ sender.userName }}:</span>
<span class="message-text">{{ message.textContent }}</span>
</div>
</template>
</BarrageList>
按消息类型区分渲染
使用自定义的 isGiftMessage 函数,在插槽中对礼物消息和普通消息进行差异化渲染:
<template>
<BarrageList>
<template #message-item="{ message, sender }">
<!-- 礼物消息 -->
<div v-if="isGiftMessage(message)" class="gift-barrage-item">
<span class="sender-name">{{ sender.userName }}</span>
<span class="gift-text">🎁 送出了礼物!</span>
</div>
<!-- 普通文本消息 -->
<div v-else class="text-barrage-item">
<span class="sender-name">{{ sender.userName }}:</span>
<span class="message-text">{{ message.textContent }}</span>
</div>
</template>
</BarrageList>
</template>

<script setup lang="ts">
function isGiftMessage(message: { data?: string }): boolean {
if (!message.data) return false;
try {
const data = JSON.parse(message.data);
return data.type === 'gift';
} catch {
return false;
}
}
</script>

消息发送组件(BarrageInput)自定义

props

参数名
类型
默认值
说明
containerClass
String
''
自定义容器的 CSS 类名。
containerStyle
Record<string, any>

{}
自定义容器的内联样式。
width
String
-
组件宽度,支持CSS单位。
height
String
-
组件高度,支持CSS单位。
minHeight
String
'40px'
组件最小高度,支持CSS单位。
maxHeight
String
'140px'
组件最大高度,支持CSS单位。
placeholder
String
-
输入框占位符文本。
disabled
Boolean
false
是否禁用输入框。
autoFocus
Boolean
true
是否自动聚焦到输入框。
maxLength
Number
80
输入内容的最大字符数限制。
onWillSendBarrage
onWillSendBarrage
-
弹幕发送前的回调钩子。接收即将发送的 Barrage 消息对象作为参数,返回 false 可拦截本次发送,返回 truevoid 则允许发送。支持异步回调(Promise<boolean>),适用于内容审核、敏感词过滤等场景。
onDidSendBarrage
onDidSendBarrage
-
弹幕发送成功后的回调钩子。接收已成功发送的 Barrage 消息对象作为参数,适用于埋点统计、发送成功提示等场景。

Events

事件名
参数
说明
focus
-
输入框获得焦点时触发。
blur
-
输入框失去焦点时触发。
如上表所示,消息发送组件的 Props 自定义部分由四块内容组成,分别为尺寸控制、输入限制、自定义样式、发送钩子,具体内容如下表所示。
内容
参数
尺寸控制
widthheightminHeightmaxHeight
输入限制
maxLength
自定义样式
containerStylecontainerClass
发送钩子

onWillSendBarrageonDidSendBarrage

尺寸控制

通过设置 widthheightminHeightmaxHeight 参数,您可以灵活地控制 BarrageInput 的尺寸。
<BarrageInput width="400px" height="60px" minHeight="40px" maxHeight="120px" />

输入限制

通过设置 maxLength 参数,您可以控制输入内容的最大字符数。
<BarrageInput :maxLength="100" />

自定义样式

消息发送组件提供了 containerStylecontainerClass 属性,用于自定义组件样式。
1. 若需要自定义输入框容器样式,您可以给 containerStyle 属性传递一个样式对象。
示例:自定义容器背景和边框圆角
<BarrageInput :containerStyle="{ backgroundColor: '#a8abb2', borderRadius: '0 0', boxShadow: '0 2px 8px rgba(0,0,0,0.1)'}" />
2. 若需要自定义输入框容器类名,您可以给 containerClass 属性传递一个类名字符串。
示例:自定义容器类名
<template>
<BarrageInput containerClass="my-custom-input-container" />
</template>

<style>.my-custom-input-container {background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);border: none;border-radius: 20px;padding: 8px 20px;}.my-custom-input-container:focus-within {box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.3);}</style>
修改前
修改后
自定义容器背景和边框圆角
自定义容器类名




消息发送钩子

消息发送组件提供了两个钩子,允许您在弹幕发送前后介入处理流程:
onWillSendBarrage:发送前触发,返回 false 可拦截发送(支持异步),适用于内容审核、敏感词过滤。
onDidSendBarrage:发送成功后触发,适用于埋点统计、发送成功提示。

<template>
<BarrageInput
:onWillSendBarrage="handleWillSend"
:onDidSendBarrage="handleDidSend"
/>
</template>

<script setup lang="ts">
import { BarrageInput } from 'tuikit-atomicx-vue3';
import type { Barrage } from 'tuikit-atomicx-vue3';

// 发送前内容过滤 — 返回 false 可拦截发送
function handleWillSend(message: Barrage): boolean {
const sensitiveWords = ['spam', 'abuse'];
const hasSensitive = sensitiveWords.some(word => (message.textContent || '').includes(word));
if (hasSensitive) {
alert('消息包含敏感内容,已拦截发送');
return false;
}
return true;
}

// 发送成功后的埋点统计
function handleDidSend(message: Barrage) {
console.log('已发送:', message.textContent);
}
</script>

进阶场景:如何快速实现“弹幕抽奖”

弹幕抽奖是直播互动的核心玩法。通过 tuikit-atomicx-vue3 提供的自定义消息能力,您可以轻松实现从“参与抽奖”到“中奖公示”的全流程。

1. 参与抽奖(发送自定义消息)

当用户点击页面上的“参与抽奖”按钮时,调用 sendCustomMessage 发送一个特定协议的消息。这样,直播间的所有人(包括管理后台)都能收到该请求。
import { useBarrageState } from 'tuikit-atomicx-vue3';

const { sendCustomMessage } = useBarrageState();

const joinLottery = async () => {
await sendCustomMessage({
businessId: 'LOTTERY_JOIN', // 自定义业务 ID
data: JSON.stringify({
lotteryId: 'ACT_2026_001',
userName: '资深摄影师',
timestamp: Date.now()
}),
});
console.log('抽奖请求已发送');
};

2. 实时监听抽奖动态

利用 subscribeEvent 监听所有到达的消息。如果是抽奖相关的业务 ID,则触发对应的视觉效果(如弹出抽奖动画或记录名单)。
import { useBarrageState, BarrageType, BarrageEvent } from 'tuikit-atomicx-vue3';

const { subscribeEvent } = useBarrageState();

subscribeEvent(BarrageEvent.onBarrageReceived, (barrage) => {
// 识别自定义业务消息
if (barrage.messageType === BarrageType.custom && barrage.businessId === 'LOTTERY_JOIN') {
const lotteryData = JSON.parse(barrage.data);
console.log(`用户 ${lotteryData.userName} 参与了抽奖!`);
// 💡 此处可调用您自己的动效引擎,弹出“XX参与了抽奖”的轻提示
}
});

3. 在弹幕列表中过滤/定制抽奖消息

如果您不希望“抽奖协议”这种纯数据消息干扰正常的聊天列表,可以通过 BarrageList 的插槽进行过滤。
<BarrageList>
<template #message-item="{ message, sender }">
<div v-if="message.messageType === 0" class="normal-msg">
<span class="name">{{ sender.userName }}:</span>
<span>{{ message.textContent }}</span>
</div>
<div v-else-if="message.businessId === 'LOTTERY_JOIN'" class="lottery-card">
🎊 欢迎 {{ sender.userName }} 参加本场抽奖!
</div>
</template>
</BarrageList>

常见问题

如何在自定义弹幕消息中区分房主和观众?

您可以根据 Barrage 消息中的 sender.userId 和直播间 ownerId 比对来判断是否为房主,并显示您想要的特定效果.

如何拦截用户发送的违规弹幕?

您可以利用 BarrageInputonWillSendBarrage 发送前钩子:
同步/异步拦截:该钩子支持返回 Promise<boolean>。您可以调用后台的敏感词过滤接口,若返回 false,弹幕将不会发出。
示例:
async function handleWillSend(message) {
const isLegal = await checkMessageWithAI(message.textContent);
return isLegal; // 若为 false,组件内部会自动停止发送流程
}