弹幕(Web)

最近更新时间:2025-11-27 15:16:31

我的收藏
本篇文档旨在指导 Web 开发者如何使用 AtomicXCore 框架中的 BarrageState 模块,为您的直播应用快速集成功能丰富、性能卓越的弹幕系统。


核心功能

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

实现步骤

步骤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
[string:string]?
附加的扩展信息,可用于业务自定义。

步骤4:发送自定义弹幕

发送一条包含自定义业务逻辑的消息,例如礼物、点赞或游戏化互动指令。这条消息对其他客户端来说是透明的,需要业务层自行解析。
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),
messageType: 0,
textContent: '欢迎进入直播间!',
extensionInfo: { type: 'system' },
}

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();

// 2. 调用更新接口,并指定修改的标志位
await updateLiveInfo({
coverUrl: 'https://xxx',
categoryList: [5, 6],
isPublicVisible: false,
activityStatus: 1
});

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:在 IM 控制台进行配置
1. 登录您的 即时通讯 IM 控制台
2. 在左侧导航栏按照路径:消息服务 Chat > 功能配置 > 群组配置 > 群功能配置 > 直播群新成员查看入群前消息量配置进行导航。

3. 修改“新成员可查看最近消息数”,最大支持 50 条。
步骤2:客户端无感获取
完成上述配置后,您的客户端代码无需做任何改动
当新用户加入直播间时,AtomicXCore 的底层会自动拉取您配置的历史消息数量。这些历史消息会和实时消息一样,通过您已实现的 BarrageState 订阅通道推送给您的UI层。您的应用会像接收实时弹幕一样,自然地接收并展示这些历史弹幕。