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

组件构成
组件名称 | 具体内容 |
弹幕消息组件(BarrageList) | 负责实时展示和管理弹幕消息流的组件,提供消息列表渲染、时间聚合、用户交互和响应式适配等完整的消息展示解决方案。 |
消息发送组件(BarrageInput) | 提供富文本编辑和消息发送功能的输入组件,集成表情选择器、字符限制、状态管理和跨平台适配,为用户提供流畅的消息输入体验。 |
组件接入
步骤1:环境配置及开通服务
步骤2:安装依赖
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 | 自定义消息组件。 | |
containerStyle | CSSProperties | - | 自定义消息列表容器样式。 |
itemStyle | CSSProperties | - | 自定义单条消息项样式。 |
height | String | - | 组件高度,支持CSS单位。 |
style | CSSProperties | - | 指定根元素自定义样式。 |
如上表所示,弹幕消息组件的 Props 自定义部分由两块内容组成,分别为可替换子组件、自定义样式,具体内容如下表所示。
内容 | 参数 |
可替换子组件 | Message |
自定义样式 | containerStyle、itemStyle、height、style |
自定义样式
弹幕消息组件提供了
containerStyle、itemStyle、自定义子组件 等内容,用于自定义组件样式。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 插槽
说明:
1.
message-item 插槽的优先级高于 Message Props,两者同时使用时以插槽为准。2. PC 和 H5 两端的插槽行为一致,所有消息(包括礼物消息)都会传递给插槽。
3. 不使用插槽时,H5 端默认不渲染礼物消息(礼物消息在独立的礼物区域展示)。

插槽参数
插槽名 | 参数名 | 参数类型 | 说明 |
message-item | message | 当前弹幕消息对象,包含 textContent(文本内容)、sender(发送者)、messageType(消息类型)、data(自定义数据 JSON 字符串)等字段。 | |
| sender | 发送者信息,包含 userId、userName、avatarUrl 等字段。 | |
基本用法
通过
#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 可拦截本次发送,返回 true 或 void 则允许发送。支持异步回调(Promise<boolean>),适用于内容审核、敏感词过滤等场景。 |
onDidSendBarrage | onDidSendBarrage | - | 弹幕发送成功后的回调钩子。接收已成功发送的 Barrage 消息对象作为参数,适用于埋点统计、发送成功提示等场景。 |
Events
事件名 | 参数 | 说明 |
focus | - | 输入框获得焦点时触发。 |
blur | - | 输入框失去焦点时触发。 |
如上表所示,消息发送组件的 Props 自定义部分由四块内容组成,分别为尺寸控制、输入限制、自定义样式、发送钩子,具体内容如下表所示。
内容 | 参数 |
尺寸控制 | width、height、minHeight、maxHeight |
输入限制 | maxLength |
自定义样式 | containerStyle、containerClass |
发送钩子 | onWillSendBarrage、onDidSendBarrage |
尺寸控制
<BarrageInput width="400px" height="60px" minHeight="40px" maxHeight="120px" />
输入限制
通过设置
maxLength 参数,您可以控制输入内容的最大字符数。<BarrageInput :maxLength="100" />
自定义样式
消息发送组件提供了
containerStyle、containerClass 属性,用于自定义组件样式。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. 参与抽奖(发送自定义消息)
import { useBarrageState } from 'tuikit-atomicx-vue3';const { sendCustomMessage } = useBarrageState();const joinLottery = async () => {await sendCustomMessage({businessId: 'LOTTERY_JOIN', // 自定义业务 IDdata: JSON.stringify({lotteryId: 'ACT_2026_001',userName: '资深摄影师',timestamp: Date.now()}),});console.log('抽奖请求已发送');};
2. 实时监听抽奖动态
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><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>
常见问题
如何在自定义弹幕消息中区分房主和观众?
如何拦截用户发送的违规弹幕?
同步/异步拦截:该钩子支持返回
Promise<boolean>。您可以调用后台的敏感词过滤接口,若返回 false,弹幕将不会发出。示例:
async function handleWillSend(message) {const isLegal = await checkMessageWithAI(message.textContent);return isLegal; // 若为 false,组件内部会自动停止发送流程}






