tencent cloud

直播 SDK

动态与公告
TUILiveKit 产品动态
云直播推拉流 SDK 产品动态
新手指引
产品简介
产品概述
产品优势
性能数据
基本概念
购买指南
TRTC Live 价格总览
Live 视频直播计费说明
开通服务(TUILiveKit)
Demo 体验
Demo 体验指引
跑通 Demo(TUILiveKit)
接入指南
视频直播
准备工作
主播开播
观众观看
直播列表
语聊房
准备工作
主播开播
观众观看
直播列表
推流助手
推流助手(Electron 桌面应用)
推流助手(Web 桌面浏览器)
直播监播
监播页面(Web 桌面浏览器 React 版)
监播页面(Web 桌面浏览器 Vue 版)
UI 自定义
直播视频组件
视频源编辑组件
观众列表组件
聊天弹幕组件
媒体源配置面板
连麦管理面板
直播送礼组件
无 UI 集成
搭建视频直播
搭建语聊房
功能指南
关注主播(TUILiveKit)
至臻画质(TUILiveKit)
输入媒体流进房(TUILiveKit)
礼物系统(TUILiveKit)
客户端 API
Android
iOS
Web
服务端 API(TUILiveKit)
账号系统
REST API
第三方回调
错误码(TUILiveKit)
常见问题
平台编译
用户鉴权
云直播推拉流 SDK
产品简介
购买指南
Demo 体验
免费测试
SDK 下载
License 管理
高级功能
客户端 API
常见问题
无 UI 集成方案
API 文档
OSS information
OSS Attribution Notice

弹幕(Web)

PDF
聚焦模式
字号
最后更新时间: 2026-03-10 16:43:43
本篇文档旨在指导 Web 开发者如何使用 AtomicXCore 框架中的 BarrageState 模块,为您的直播应用快速集成功能丰富、性能卓越的弹幕系统。


核心功能

BarrageState 为您的直播应用提供了一套完整的弹幕解决方案,核心功能包括:
接收并展示直播间弹幕消息。
发送文本弹幕与观众互动。
发送自定义业务弹幕,以支持礼物、点赞等复杂场景。
在本地消息列表中插入系统提示(例如,“欢迎 XX 进入直播间”)。

示例项目

您可参考我们在 GitHub 上提供的 BarrageListBarrageInput 组件来查看完整实现。

实现步骤

步骤1:组件集成

请参见 快速接入 集成 AtomicXCore,完成接入。
注意:
下列步骤需要参考 快速接入 中先创建房间或加入房间,随后执行下列步骤中的方法。

步骤2:初始化并监听弹幕

获取一个与当前直播间 liveId 绑定的 BarrageState 实例,并且监听 messageList 来接收最新的全量弹幕消息列表。
import { useBarrageState } from 'tuikit-atomicx-vue3';
import { watch } from 'vue'

const { messageList } = useBarrageState()

// 监听 messageList 的实时变更,用于驱动 UI 更新
watch(messageList, (newVal, oldVal) => {
console.log(newVal)
});

步骤3:发送文本弹幕

调用 sendTextMessage 方法向直播间内的所有用户广播一条纯文本消息。
import { useBarrageState } from 'tuikit-atomicx-vue3'

const { sendTextMessage } = useBarrageState();

const sendMessage = async () => {
try {
await sendTextMessage({
text: '大家好,欢迎来到直播间!',
extensionInfo: {
color: '#ff0000',
fontSize: '16px'
}
});
} catch (error) {
console.error('消息发送失败:', error);
}
}

接口参数

参数
类型
描述
text
string
要发送的文本内容。
extensionInfo
Record<string, string>
附加的扩展信息,可用于业务自定义。

步骤4:发送自定义弹幕

发送一条包含自定义业务逻辑的消息,例如礼物、点赞或游戏化互动指令。这条消息的内容格式由业务层自行定义,接收端需要根据 businessIddata 自行解析和处理。
import { useBarrageState } from 'tuikit-atomicx-vue3'
import { watch } from 'vue';

const { sendCustomMessage } = useBarrageState();

/// 发送一条自定义弹幕,例如用于发送礼物
const sendGiftMessage = async (giftId: string, giftCount: number) => {
// 1. 定义一个能识别业务的ID
const businessId = 'live_gift';
// 2. 将业务数据编码为 JSON 字符串
const giftData = { gift_id: giftId, gift_count: giftCount };
// 3. 调用核心API发送自定义消息
try {
await sendCustomMessage({
businessId,
data: JSON.stringify(giftData)
});
} catch (error) {
console.error('礼物消息发送失败:', error);
}
};

接口参数

参数
类型
描述
businessId
string
业务唯一标识符,例如 "live_gift",用于接收端区分不同的自定义消息。
data
string
业务数据,通常为 JSON 格式的字符串。

步骤5:在本地插入提示消息

在当前用户的消息列表中插入一条本地消息,这条消息不会被发送到直播间的其他用户。这非常适合用来显示系统欢迎、警告或操作提示等信息。
import { useBarrageState } from 'tuikit-atomicx-vue3'

const { appendLocalTip } = useBarrageState()

const systemTip = {
liveId: 'live123',
sender: {
userId: 'system',
userName: '系统',
avatarUrl: '',
},
sequence: Date.now(), // 消息序列号,用于排序
timestampInSecond: Math.floor(Date.now() / 1000), // 10位 Unix 时间戳
messageType: 0, // 消息类型枚举值(例如:0 代表普通文本消息,请参考 API 枚举定义)
textContent: '欢迎进入直播间!',// 消息显示的文本内容
extensionInfo: { type: 'system' },// 扩展字段,用于 UI 特殊渲染
}

appendLocalTip(systemTip)

步骤6:管理用户发言(禁言与解禁)

主播或管理员可以对直播间内的用户发言权限进行管理。

禁止/解禁单个用户发言

通过 LiveAudienceState 中的 disableSendMessage 接口来实现对指定用户的禁言或解禁。此状态会被持久化,即使用户重新进入直播间,禁言状态依然有效。
import { useLiveAudienceState } from 'tuikit-atomicx-vue3';

const { disableSendMessage } = useLiveAudienceState()

// isDisable 为 true 时禁用用户发送消息;
// isDisable 为 false 时启用用户发送消息;
await disableSendMessage({ userId: 'user123', isDisable: true });


开启/关闭全体禁言

要对直播间内所有用户(通常不包括主播自己)进行禁言,您需要通过 LiveListStateupdateLiveInfo 更新直播间信息来实现。
import { useLiveListState } from 'tuikit-atomicx-vue3';

// 1. 获取 LiveListState 的实例
const { updateLiveInfo } = useLiveListState();

const setGlobalMute = async (shouldMute: boolean) => {
try {
// 2. 调用更新接口
// LiveListState 会根据传入的参数自动合并更新直播间信息
await updateLiveInfo({
// 对应 LiveInfo 中的 isMessageDisable 字段
// true: 禁止所有观众发言
// false: 允许观众发言
isMessageDisable: shouldMute
});
console.log(`全体禁言状态已更新为: ${shouldMute}`);
} catch (error) {
console.error('更新全体禁言失败:', error);
}
};

// 示例用法:开启全体禁言
await setGlobalMute(true);

API 文档

关于 BarrageState 及其相关类的所有公开接口、属性和方法的详细信息,请参考 AtomicXCore 框架的官方 API 文档。

常见问题

除了基础的文本弹幕,我们还希望实现“彩色弹幕”、“礼物弹幕”等更丰富的样式,该如何实现?

可通过自定义消息 sendCustomMessage 实现。BarrageState 支持灵活的自定义消息格式,开发者可根据业务需求自定义消息结构和样式。
实现思路
1. 定义数据结构: 与您的客户端和服务器团队共同定义好自定义消息的 JSON 结构。例如,一条彩色弹幕可以这样定义:
{ "type": "colored_text", "text": "这是一条彩色弹幕!", "color": "#FF5733" }
2. 发送端: 在发送时,将这个 JSON 结构转换为字符串,并通过 sendCustomMessagedata 参数发送出去。businessId 可以设置为一个能代表您业务的唯一标识,例如 "barrage_style_v1"。
3. 接收端: 在接收到弹幕消息后,检查其 messageType 是否为 'CUSTOM' 以及 businessId 是否匹配。如果匹配,则解析 data 字符串(通常是解析 JSON),根据解析出的数据(例如 color、text)来渲染您的自定义UI样式。

为什么我调用了 sendTextMessage,但是在消息列表中看不到我发送的消息?

请按以下步骤排查:
1. 检查 catch 中捕获的错误sendTextMessage 方法有错误捕获。请检查回调返回的结果是成功还是失败。如果失败,错误信息会明确指出问题所在(例如“您已被禁言”、“网络错误”等)。
2. 确认订阅时机:确保您对 barrageState 的订阅发生在该 liveId 对应的直播开始之后。如果在加入直播房间之前就开始监听,可能会错过部分消息。
3. 检查 liveId:确认您在创建 BarrageState 实例、加入直播房间、以及发送消息时使用的 liveId 完全一致,包括大小写。
4. 网络问题:检查设备当前的网络连接是否正常。消息发送依赖于网络。

新观众进入直播间时,如何让他们看到加入前的历史弹幕消息?

AtomicXCore 支持拉取历史弹幕消息,但这需要您在服务端控制台进行一项简单的配置。配置完成后,SDK 会自动处理后续的一切,您无需编写额外的代码。

步骤1:在 Live 控制台进行配置

1. 登录 控制台 > Live > 配置,在顶部选择目标应用
2. 在 Live 配置页选择新成员拉取历史消息,修改新成员可查看最新消息数,最大支持 50 条。




步骤2:客户端无感获取

完成上述配置后,您的客户端代码无需做任何改动
当新用户加入直播间时,AtomicXCore 底层会自动拉取配置的历史消息数量。这些历史消息会和实时消息一样,通过 BarrageState的订阅通道推送到 UI 层。应用会像接收实时弹幕一样,自然地接收并展示这些历史弹幕。

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈