tencent cloud

实时音视频

动态与公告
产品动态
产品近期公告
关于 TRTC Live 正式上线的公告
关于TRTC Conference 正式版上线的公告
Conference 商业化版本即将推出
关于多人音视频 Conference 开启内测公告
关于音视频通话 Call 正式版上线的公告
关于腾讯云音视频终端 SDK 播放升级及新增授权校验的公告
关于 TRTC 应用订阅套餐服务上线的相关说明
产品简介
产品概述
基本概念
产品功能
产品优势
应用场景
性能数据
购买指南
计费概述
免费时长说明
月订阅
现收现付
TRTC 逾期与暂停政策
常见问题解答
退款说明
新手指引
Demo 体验
视频通话 SDK
组件介绍
开通服务
跑通 Demo
快速接入
离线唤醒
会话聊天
云端录制
AI 降噪
界面定制
Chat 集成通话能力
更多特性
无 UI 集成
服务端 API
客户端 API
解决方案
错误码表
发布日志
常见问题
视频会议 SDK
组件介绍(TUIRoomKit)
开通服务(TUIRoomKit)
跑通 Demo(TUIRoomKit)
快速接入(TUIRoomKit)
屏幕共享(TUIRoomKit)
预定会议(TUIRoomKit)
会中呼叫(TUIRoomKit)
界面定制(TUIRoomKit)
虚拟背景(TUIRoomKit)
会议控制(TUIRoomKit)
云端录制(TUIRoomKit)
AI 降噪(TUIRoomKit)
会中聊天(TUIRoomKit)
机器人推流(TUIRoomKit)
更多特性(TUIRoomKit)
客户端 API(TUIRoomKit)
服务端 API(TUIRoomKit)
常见问题(TUIRoomKit)
错误码 (TUIRoomKit)
SDK更新日志(TUIRoomKit)
直播与语聊 SDK
Live 视频直播计费说明
组件介绍
开通服务(TUILiveKit)
跑通 Demo
无 UI 集成
UI 自定义
直播监播
视频直播
语聊房
高级功能
客户端 API
服务端 API
错误码
发布日志
常见问题
RTC Engine
开通服务
SDK 下载
API-Example
接入指引
API-参考手册
高级功能
AI 集成
概述
MCP 配置
Skills 配置
集成指南
常见问题
RTC RESTFUL API
History
Introduction
API Category
Room Management APIs
Stream mixing and relay APIs
On-cloud recording APIs
Data Monitoring APIs
Pull stream Relay Related interface
Web Record APIs
AI Service APIs
Cloud Slicing APIs
Cloud Moderation APIs
Making API Requests
Call Quality Monitoring APIs
Usage Statistics APIs
Data Types
Appendix
Error Codes
控制台指南
应用管理
套餐包管理
用量统计
监控仪表盘
开发辅助
解决方案
实时合唱
常见问题
迁移指南
计费相关
功能相关
UserSig 相关
应对防火墙限制相关
缩减安装包体积相关
Andriod 与 iOS 相关
Web 端相关
Flutter 相关
Electron 相关
TRTCCalling Web 相关
音视频质量相关
其他问题
旧版文档
RTC RoomEngine SDK(旧)
集成 TUIRoom (Web)
集成 TUIRoom (Android)
集成 TUIRoom (iOS)
集成 TUIRoom (Flutter)
集成 TUIRoom (Electron)
TUIRoom API 查询
实现云端录制与回放(旧)
监控仪表盘计费(旧)
协议与策略
安全合规认证
安全白皮书
信息安全说明
服务等级协议
苹果隐私策略:PrivacyInfo.xcprivacy
TRTC 政策
隐私协议
数据处理和安全协议
词汇表

弹幕(Web)

PDF
聚焦模式
字号
最后更新时间: 2025-12-31 17:09:16
本篇文档旨在指导 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 层。应用会像接收实时弹幕一样,自然地接收并展示这些历史弹幕。

帮助和支持

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

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

文档反馈