帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>直播与语聊房（含 UI）>Core SDK>功能模块>礼物>礼物（Web）

礼物（Web）

最近更新时间：2026-08-20 14:28:42
我的收藏

本页目录：

LiveGiftState 是 AtomicXCore（tuikit-atomicx-vue3）中专门负责管理直播间礼物功能的模块。通过它，开发者可以为 Web 直播应用构建一套完整的礼物系统，实现丰富的营收和互动场景。
礼物面板
全屏礼物







核心功能

拉取礼物列表：从服务端拉取礼物面板所需的数据，包括礼物分类和礼物详情。
发送礼物 / 点赞：观众可以向主播发送选定的礼物（附带数量），也可以发送点赞。
礼物事件广播：实时接收房间内发生的礼物赠送、点赞、礼物统计变化等事件，用于展示礼物动画和弹幕通知。
内置全屏特效播放：模块内置 SVGA 特效播放器，收到带动画资源的礼物时可自动播放，无需业务方手动接入第三方播放库。

核心概念

概念
说明
useLiveGiftState
礼物模块的 Composable 入口，返回礼物状态与操作方法。无需传入 liveID，模块内部会自动绑定当前所在的直播间。
giftInfoList
响应式的礼物分类列表（Ref<GiftCategory[]>），驱动礼物面板 UI。
totalLikeCount
响应式的累计点赞总数（Ref<number>）。
GiftCategory
礼物分类，包含分类信息及该分类下的礼物列表 giftList。
GiftInfo
单个礼物详情，包含 ID、名称、图标、价格、动画资源等。
LiveGiftEvents
礼物事件枚举，通过 subscribeEvent / unsubscribeEvent 订阅与取消订阅。

实现步骤

步骤1：集成组件

说明：
使用礼物系统要求开通 TUILiveKit 多人连麦版、大规模直播版，不同套餐中可配置的礼物数量有所不同，详细参见 功能与计费说明 中的礼物系统说明。

步骤2：初始化并监听礼物事件

获取 useLiveGiftState 返回的状态与方法，并订阅礼物事件以接收礼物、点赞、礼物统计变化的实时通知。

实现方式:

1. 获取实例：调用 useLiveGiftState() 获取礼物状态与操作方法。
2. 订阅事件：使用 subscribeEvent 订阅 LiveGiftEvents.ON_RECEIVE_GIFT_MESSAGE 等事件。
3. 监听状态：监听响应式数据 giftInfoList 来驱动礼物面板 UI 更新。
注意：
事件需要在事件触发之前监听。建议在进入直播间前完成事件订阅，避免漏掉通知；组件卸载时记得调用 unsubscribeEvent 取消订阅。

代码示例:

import { onMounted, onUnmounted, watch } from 'vue';
import { useLiveGiftState, LiveGiftEvents } from 'tuikit-atomicx-vue3';

const {
  giftInfoList,
  totalLikeCount,
  subscribeEvent,
  unsubscribeEvent,
} = useLiveGiftState();

const onReceiveGift = (eventInfo) => {
  console.log('收到礼物:', eventInfo.giftInfo.name, '数量:', eventInfo.giftCount);
  console.log('发送者:', eventInfo.sender.userName);
};

const onLikes = (eventInfo) => {
  console.log('收到点赞, 总数:', eventInfo.totalLikesReceived);
};

onMounted(() => {
  subscribeEvent(LiveGiftEvents.ON_RECEIVE_GIFT_MESSAGE, onReceiveGift);
  subscribeEvent(LiveGiftEvents.ON_RECEIVE_LIKES_MESSAGE, onLikes);
});

onUnmounted(() => {
  unsubscribeEvent(LiveGiftEvents.ON_RECEIVE_GIFT_MESSAGE, onReceiveGift);
  unsubscribeEvent(LiveGiftEvents.ON_RECEIVE_LIKES_MESSAGE, onLikes);
});

watch(giftInfoList, (list) => {
  console.log('礼物分类列表已更新:', list);
});

礼物列表结构体参数

GiftCategory 参数说明
参数
类型
描述
categoryID
string
礼物分类的唯一 ID。
name
string
礼物分类的显示名称。
desc
string
礼物分类的描述信息。
extensionInfo
Record<string, string>
扩展信息字段（Record<string, string>）。用于存放业务自定义的扩展键值对，具体可用的 key 由服务端礼物配置决定；若无自定义需求可忽略。
giftList
GiftInfo[]
该分类下包含的礼物对象数组。
GiftInfo 参数说明
参数
类型
描述
giftID
string
礼物的唯一 ID。字段名为 giftID（大写 ID）；调用 sendGift 时入参 key 为小写 d 的 giftId，其值取本字段。
name
string
礼物的显示名称。
desc
string
礼物的描述信息。
iconUrl
string
礼物图标 URL，用于在面板中展示。
resourceUrl
string
礼物动画资源 URL（如 .svga），用于全屏特效播放。
level
number
礼物等级。
coins
number
礼物价格（金币数）。
extensionInfo
Record<string, string>
扩展信息字段（Record<string, string>）。用于存放业务自定义的扩展键值对，具体可用的 key 由服务端礼物配置决定；若无自定义需求可忽略。

步骤3：拉取礼物列表

调用 refreshGiftList 方法，从服务端拉取礼物列表。

实现方式:

1. 调用接口：在合适的时机（例如打开礼物面板时）调用 refreshGiftList。
2. 接收数据：拉取成功后，giftInfoList 会自动更新，UI 通过对它的监听自动刷新。拉取成功后模块还会自动预加载礼物的特效动画资源，以加快后续播放速度。

代码示例:

import { onMounted } from 'vue';
import { useLiveGiftState } from 'tuikit-atomicx-vue3';

const { giftInfoList, refreshGiftList } = useLiveGiftState();

onMounted(async () => {
  try {
    await refreshGiftList();
    // giftInfoList 已自动更新，可直接用于渲染
    const allGifts = giftInfoList.value.flatMap(category => category.giftList ?? []);
    console.log('可用礼物:', allGifts);
  } catch (error) {
    console.error('礼物列表拉取失败', error);
  }
});

步骤4：发送礼物

当用户在礼物面板选择一个礼物并点击发送时，调用 sendGift 接口将礼物发送出去。

实现方式:

1. 获取参数：从 UI 获取用户选择礼物的 giftID 和发送数量 count。
2. 调用接口：调用 sendGift({ giftId, count })（注意入参 key 为 giftId，值取礼物的 giftID）。
3. UI 更新驱动：发送成功后的 UI 更新（动画、弹幕）应由 ON_RECEIVE_GIFT_MESSAGE 事件驱动，而非在 sendGift 之后手动执行，避免重复。

代码示例:

import { useLiveGiftState } from 'tuikit-atomicx-vue3';

const { sendGift } = useLiveGiftState();

const handleSendGift = async (gift) => {
  try {
    await sendGift({ giftId: gift.giftID, count: 1 });
    console.log(`礼物 ${gift.giftID} 发送成功`);
  } catch (error) {
    // 处理发送失败，例如余额不足提示
    console.error('礼物发送失败', error);
  }
};

sendGift 接口参数

参数名
类型
描述
giftId
string
要发送的礼物的唯一 ID（取自 GiftInfo.giftID）。
count
number
发送的数量。

步骤5（可选）：发送点赞

除了礼物，观众还可以向主播发送点赞。

代码示例:

import { useLiveGiftState } from 'tuikit-atomicx-vue3';

const { sendLikes, totalLikeCount } = useLiveGiftState();

const handleLike = async () => {
  try {
    await sendLikes({ count: 1 });
  } catch (error) {
    console.error('点赞失败', error);
  }
};

// totalLikeCount 会随 ON_RECEIVE_LIKES_MESSAGE 事件自动更新

功能进阶

LiveGiftState 的功能高度依赖于您的业务后台服务。本章将指导您如何通过服务端配置和客户端实现，构建功能丰富、体验卓越的礼物互动系统。

礼物素材配置

需在后台自定义直播间可用的礼物种类、分类、名称、图标、价格以及动画效果，以满足运营需求和品牌特色。

实现方式

1. 服务端配置：使用 LiveKit 服务端 REST API 管理礼物信息、分类、多语言等。请参考 礼物配置指引文档。
2. 客户端拉取：在客户端调用 refreshGiftList 获取配置数据。
3. UI 展示：使用 giftInfoList 中的 GiftCategory[] 数据填充礼物面板。

涉及 REST API 接口一览

接口分类
接口
礼物管理
添加 / 删除 / 查询礼物信息
礼物分类管理
礼物关系管理
礼物多语言管理
维护礼物 / 分类的多语言信息

礼物多语言展示

如果需要根据不同用户展示不同语言（中文、英文等）的礼物名称和描述，可在拉取礼物列表之前调用 setLanguage 设置目标语言，服务端会返回对应语言的礼物信息。

代码示例:

import { useLiveGiftState } from 'tuikit-atomicx-vue3';

const { setLanguage, refreshGiftList } = useLiveGiftState();

await setLanguage('en');       // 或 'zh-CN'
await refreshGiftList();       // 拉取到的礼物名称/描述为对应语言

计费与送礼扣费流程

当观众赠送礼物时，需要确保其账户余额充足，并完成实际的扣费操作，然后才能触发礼物特效的播放和广播。

实现方式

1. 后台配置回调：在 LiveKit 后台配置您的自建计费系统的回调 URL。
2. 客户端发送：客户端调用 sendGift。
3. 后台交互：LiveKit 后台调用您的回调 URL，您的计费系统执行扣费并返回结果。
4. 结果同步：扣费成功，AtomicXCore 广播 ON_RECEIVE_GIFT_MESSAGE 事件；扣费失败，sendGift 返回的 Promise 会 reject（进入 catch）。

实现全屏礼物动画播放

当直播间有用户（包括自己）发送了"火箭""嘉年华"等豪华礼物时，全屏播放一个酷炫的礼物动画（如 SVGA 动画），营造热烈的氛围。
Web 端 LiveGiftState 内置了 SVGA 特效播放器（AnimationPlayerManager），并采用自动播放机制：当收到 ON_RECEIVE_GIFT_MESSAGE 事件、且礼物的 resourceUrl 为有效动画资源（如 .svga）时，模块会自动将其加入播放队列并在指定容器中播放，业务方无需手动调用播放接口。

实现方式

1. 提供容器：在页面中放置一个用于承载全屏动画的容器元素，并设置其 id。
2. 绑定容器：调用 setGiftPlayerView({ view }) 将容器 id 告知播放器；若不调用，则使用默认容器 id：livekit-svg-special-effects。
3. 无需手动播放：收到带 resourceUrl 的礼物后会自动播放；多个礼物会自动排队依次播放。
说明：
目前内置播放器已支持 SVGA；MP4 特效播放能力规划中。通过资源 URL 后缀（.svga / .mp4）识别动画类型。为保证流畅度，建议单个 SVGA 文件不超过 10MB。

代码示例:

<template>
  <div class="live-player">
    <!-- 全屏特效容器：占满播放区域即可 -->
    <div id="livekit-svg-special-effects" class="gift-effect-layer"></div>
  </div>
</template>

<script setup lang="ts">
import { onMounted } from 'vue';
import { setGiftPlayerView } from 'tuikit-atomicx-vue3';

onMounted(() => {
  // 可选：使用自定义容器 id，不调用则默认 'livekit-svg-special-effects'
  setGiftPlayerView({ view: 'livekit-svg-special-effects' });
});
</script>

<style scoped>
.gift-effect-layer {
  position: absolute;
  inset: 0;
  pointer-events: none;
  z-index: 10;
}
</style>

在弹幕区展示礼物赠送消息

当有用户发送礼物时，除了播放动画，通常还需要在公屏弹幕区显示一条系统消息，例如："【观众昵称】送出了【礼物名称】x【数量】"，让所有观众都能看到。

实现方式

1. 监听事件：订阅 ON_RECEIVE_GIFT_MESSAGE 事件。
2. 拼接消息：从事件参数中取出 sender.userName 与 giftInfo.name，拼接展示文案。
3. 插入弹幕：将拼接后的消息插入到您的公屏/弹幕列表中。

代码示例:

import { onMounted, onUnmounted } from 'vue';
import { useLiveGiftState, LiveGiftEvents } from 'tuikit-atomicx-vue3';

const { subscribeEvent, unsubscribeEvent } = useLiveGiftState();

const onReceiveGift = (eventInfo) => {
  const { sender, giftInfo, giftCount } = eventInfo;
  const text = `${sender.userName || sender.userId} 送出了 ${giftInfo.name} x${giftCount}`;
  // 将 text 插入到您的公屏 / 弹幕列表
  console.log(text);
};

onMounted(() => subscribeEvent(LiveGiftEvents.ON_RECEIVE_GIFT_MESSAGE, onReceiveGift));
onUnmounted(() => unsubscribeEvent(LiveGiftEvents.ON_RECEIVE_GIFT_MESSAGE, onReceiveGift));

API 文档

useLiveGiftState() 返回的状态与方法如下：

响应式状态

属性
类型
描述
giftInfoList
Ref<GiftCategory[]>
当前直播间的礼物分类列表，refreshGiftList 成功后自动更新。
totalLikeCount
Ref<number>
当前直播间累计收到的点赞总数，随 ON_RECEIVE_LIKES_MESSAGE 事件自动更新。

方法

方法
参数
返回值
描述
refreshGiftList
-
Promise<void>
刷新当前房间可用的礼物列表，成功后自动更新 giftInfoList 并预加载特效资源。
sendGift
{ giftId: string; count: number }
Promise<void>
向当前直播间发送指定礼物。
sendLikes
{ count: number }
Promise<void>
向当前直播间发送点赞。
setLanguage
language: string
Promise<void>
设置礼物信息的显示语言（如 'zh-CN'、'en'），下次刷新礼物列表时生效。
subscribeEvent
(event, callback)
void
订阅礼物 / 点赞事件。
unsubscribeEvent
(event, callback)
void
取消订阅事件（需传入与订阅时相同的 event 和 callback）。
注意：
getGiftList 接口已废弃（仅供内部使用），请统一使用 refreshGiftList。

全屏特效播放（独立导出）

方法
参数
描述
setGiftPlayerView
{ view: string }
设置全屏特效动画的容器元素 id，默认 'livekit-svg-special-effects'。
getAnimationPlayerManager
-
获取内置动画播放器管理单例，可用于 stop() 等高级控制。

事件（LiveGiftEvents）

事件
回调参数字段
触发时机
ON_RECEIVE_GIFT_MESSAGE
liveId / giftCount / sender: TUIUserInfo / giftInfo: GiftInfo
收到礼物消息时（房间内所有成员广播，含发送者自己）。
ON_GIFT_COUNT_CHANGED
liveId / totalGiftsSent / totalGiftCoins / totalUniqueGiftSenders
礼物统计数量变化时。
ON_RECEIVE_LIKES_MESSAGE
liveId / totalLikesReceived / sender: TUIUserInfo
收到点赞消息时。

常见问题

giftInfoList 为空时的排查方法？

您必须主动调用 refreshGiftList() 从您的业务后台拉取礼物列表。这些礼物数据需要预先在您的业务后台通过服务端 REST API 进行配置。同时请确认调用时已经进入了直播间。

发送礼物时入参用 giftId 还是 giftID？

礼物对象（GiftInfo）上的字段是 giftID（大写 ID），而 sendGift 的入参 key 是 giftId（小写 d）。正确写法：sendGift({ giftId: gift.giftID, count })。

调用 sendGift 发送礼物后，礼物动画播放了两次的原因？

ON_RECEIVE_GIFT_MESSAGE 是对房间内所有成员的广播（包括发送者自己）。如果您在 sendGift 成功后手动播放了一次动画，同时模块又在收到广播事件时自动播放了一次，就会造成重复。
实践建议：Web 端的全屏特效由模块自动播放，您无需在 sendGift 之后手动触发动画；sendGift 的 catch 仅用于处理发送失败（如提示"发送失败""余额不足"）。

全屏礼物动画没有显示？

请依次检查：
1. 页面中是否存在容器元素，且其 id 与 setGiftPlayerView({ view }) 传入的一致（或使用默认 id：livekit-svg-special-effects）。
2. 礼物的 resourceUrl 是否为有效的 .svga 资源。
3. 容器是否具有可见尺寸（避免被 display:none 或 0 宽高隐藏）。

如何实现礼物的多语言展示？

使用 setLanguage(language)，在 refreshGiftList 之前调用，传入目标语言代码（如 'en'、'zh-CN'）。服务端会据此返回对应语言的礼物名称和描述。

礼物扣费逻辑在哪里实现？

礼物扣费逻辑完全由您的自建计费系统负责。AtomicXCore 通过后台回调机制与您的计费系统对接：客户端调用 sendGift 触发回调，您的后台完成扣费后返回结果，从而决定礼物事件是否广播。

礼物动画播放卡顿的排查方法？

请检查 SVGA 文件大小，内置播放器建议单个文件不超过 10MB。若文件过大或动画复杂，可考虑接入 TUILiveKit 的进阶特效播放能力（属于企业版 / 定制能力，如需使用请联系腾讯云商务）以获得更优性能。

中国站