@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/resource/{doc → knowledge}/livekit/core-sdk/voice/uni-app/voice-co-guest-interaction.md

@@ -1,4 +1,4 @@
-**AtomicXCore** 提供了 [CoGuestState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState) 和 [LiveSeatState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveSeatState) 模块，用于管理观众连麦的完整业务流程。您无需关心复杂的状态同步和信令交互，只需调用几个简单的方法，即可为您的直播添加强大的观众与主播音视频互动功能。本文档将指导您如何使用 `CoGuestState `和 `LiveSeatState`在您的应用中快速实现语音连麦功能。
+**AtomicXCore** 提供了 [CoGuestState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState) 和 [LiveSeatState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveSeatState) 模块，用于管理观众连麦的完整业务流程。您无需关心复杂的状态同步和信令交互，只需调用几个简单的方法，即可为您的直播添加强大的观众与主播音视频互动功能。本文档将指导您如何使用 `CoGuestState` 和 `LiveSeatState`在您的应用中快速实现语音连麦功能。
 
 ## 核心场景
 
@@ -13,7 +13,7 @@
 
 ### 步骤1：组件集成
 
-请参考 快速接入 集成 **AtomicXCore**。
+请参考 开播与收听 集成 **AtomicXCore**。
 
 ### 步骤2：实现观众申请上麦
 
@@ -46,7 +46,7 @@
    ```
 2. **监听主播的处理结果**
 
-   通过  `addCoGuestGuestListener` 订阅`'onGuestApplicationResponded'` 事件，您可以接收到主播的处理结果。
+   通过 `addCoGuestGuestListener` 订阅`'onGuestApplicationResponded'` 事件，您可以接收到主播的处理结果。
 
    ``` typescript
    import { onMounted } from 'vue';
@@ -61,24 +61,22 @@
        addCoGuestGuestListener(liveID, 'onGuestApplicationResponded', handleGuestApplicationResponded)
    })
 
-   const handleGuestApplicationResponded = {
-       callback: (event) => {
-         const res = JSON.parse(event)
-         if(res.isAccept){
-           console.log('上麦申请被同意')
-           // 1.打开麦克风
-           openLocalMicrophone()
-           // 2. 在此更新 UI，例如变更申请按钮状态，显示为连麦中
-         } else {
-           console.log('上麦申请被拒绝')
-           // 弹窗提示用户申请被拒绝
-         }
+   const handleGuestApplicationResponded = (event) => {
+      const res = JSON.parse(event)
+      if(res.isAccept){
+         console.log('上麦申请被同意')
+         // 1.打开麦克风
+         openLocalMicrophone()
+         // 2. 在此更新 UI，例如变更申请按钮状态，显示为连麦中
+       } else {
+         console.log('上麦申请被拒绝')
+         // 弹窗提示用户申请被拒绝
        }
    }
    ```
 3. **主动下麦**
 
-   当连麦观众想结束互动时，调用 `disConnect` 方法即可返回普通观众状态。
+   当连麦观众想结束互动时，调用 disconnect 方法即可返回普通观众状态。
 
    ``` typescript
    import { useCoGuestState } from "@/uni_modules/tuikit-atomic-x/state/CoGuestState";
@@ -136,15 +134,13 @@
 
    // 在页面初始化时订阅事件
    onMounted(() => {
-       addCoGuestHostListener(liveID, 'onGuestApplicationReceived', handleGuestApplicationReceived)
+     addCoGuestHostListener(liveID, 'onGuestApplicationReceived', handleGuestApplicationReceived)
    })
 
-   const handleGuestApplicationReceived =  {
-       callback: (event) => {
-         const res = JSON.parse(event)
-         console.log('收到观众的连麦申请')
-         // 在此更新 UI，例如在"申请列表"按钮上显示红点
-       }
+   const handleGuestApplicationReceived = (event) => {
+     const res = JSON.parse(event)
+     console.log('收到观众的连麦申请')
+     // 在此更新 UI，例如在"申请列表"按钮上显示红点
    }
    ```
 2. **展示申请列表**
@@ -155,8 +151,8 @@
    <template>
        // 在这里绘制您的 “申请者列表” UI
        <view v-for="audience in applicants" :key="audience?.userID">
-         <text>{ audience.userName }</text>
-         <text>{ audience.userID }</text>
+         <text>{{ audience.userName }}</text>
+         <text>{{ audience.userID }}
        </view>
    </template>
    <script setup>
@@ -180,10 +176,10 @@
          liveID,
          userID,
          success: () => {
-           console.log('已同意${userID}的上麦申请')
+           console.log('已同意上麦申请')
          },
          fail: (error) => {
-           console.log('同意${userID}的上麦申请失败', error)
+           console.log('同意上麦申请失败', error)
          }
 
        })
@@ -195,10 +191,10 @@
          liveID,
          userID,
          success: () => {
-           console.log('已拒绝${userID}的上麦申请')
+           console.log('已拒绝上麦申请')
          },
          fail: (error) => {
-           console.log('拒绝${userID}的上麦申请失败', error)
+           console.log('拒绝上麦申请失败', error)
          }
        })
    }
@@ -224,10 +220,10 @@
          seatIndex: -1, // 邀请的麦位，传 -1, 随机分配麦位
          timeout: 30, // 超时时间
          success: () => {
-           console.log('已向观众 ${userID} 发送上麦邀请，请等待回应...')
+           console.log('已向观众发送上麦邀请，请等待回应...')
          },
          fail: (error) => {
-           console.log('向观众 ${userID} 发送上麦邀请失败', error)
+           console.log('向观众发送上麦邀请失败', error)
          }
        })
    }
@@ -247,15 +243,13 @@
        addCoGuestHostListener(liveID, 'onHostInvitationResponded', handleHostInvitationResponded)
    })
 
-   const handleHostInvitationResponded =  {
-       callback: (event) => {
-         const res = JSON.parse(event)
-         if(res.isAccept){
-           console.log('观众 ${res.guestUser.userName} 接受了您的邀请')
-         } else {
-           console.log('观众 ${res.guestUser.userName} 拒绝了您的邀请')
-         }
-       }
+   const handleHostInvitationResponded = (event) => {
+     const res = JSON.parse(event)
+     if(res.isAccept){
+        console.log('观众接受了您的邀请')
+     } else {
+        console.log('观众拒绝了您的邀请')
+     }
    }
    ```
 
@@ -272,13 +266,11 @@
 
    // 在页面初始化时订阅事件
    onMounted(() => {
-       addCoGuestGuestListener(liveID, 'onHostInvitationReceived', handleHostInvitationReceived)
+     addCoGuestGuestListener(liveID, 'onHostInvitationReceived', handleHostInvitationReceived)
    })
 
-   const handleHostInvitationReceived =  {
-       callback: (event) => {
-         // 在此弹出一个对话框，让用户选择“接受”或“拒绝”
-       }
+   const handleHostInvitationReceived = (event) => {
+     // 在此弹出一个对话框，让用户选择“接受”或“拒绝”
    }
    ```
 2. **响应邀请**
@@ -287,10 +279,8 @@
 
    ``` typescript
    import { useCoGuestState } from "@/uni_modules/tuikit-atomic-x/state/CoGuestState";
-   import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";
    const liveID = "xxx" // 您当前加入的语聊房的 liveID
    const { acceptInvitation, rejectInvitation } = useCoGuestState(liveID);
-   const { openLocalMicrophone, openLocalCamera } = useDeviceState(liveID);
 
    const inviterID = "发起邀请的主播ID" // 从 onHostInvitationReceived 事件中获取
 
@@ -300,8 +290,7 @@
          liveID,
          inviterID,
          success: () => {
-           openLocalMicrophone()
-           openLocalCamera({isFront: true})
+           // 可以选择在此处打开麦克风或者摄像头
          },
          fail: (error) => {
            console.log('接受邀请失败', error)
@@ -349,10 +338,11 @@ const unmuteMic = () => {
 ```
 
 #### unmuteMicrophone 接口参数：
-| **参数** | **类型** | **描述** |
-| --- | --- | --- |
-| `success` | `Function` | 解除静音的回调 |
-| `fail` | `Function` | 解除静音失败的回调。 |
+
+|**参数**|**类型**|**描述**|
+|---------|---------|---------|
+|`success`|`Function`|解除静音的回调|
+|`fail`|`Function`|解除静音失败的回调。|
 
 ### 主播远程控制麦上用户开麦或关麦
 
@@ -381,10 +371,10 @@ const closeRemoteMic = () => {
       liveID: 'xxx', // 当前语聊房 liveID
       userID: targetUserID,
       success: () => {
-        console.log('已将 ${targetUserID} 静音并锁定')
+        console.log('静音并锁定成功')
       },
       fail: (error) => {
-        console.log('静音并锁定 ${targetUserID} 失败', error)
+        console.log('静音并锁定失败', error)
       }
     })
 }
@@ -395,10 +385,10 @@ const openRemoteMic = () => {
       liveID: 'xxx', // 当前语聊房 liveID
       userID: targetUserID,
       success: () => {
-        console.log('已邀请 ${targetUserID} 打开麦克风 （已解锁）')
+        console.log('邀请打开麦克风成功')
       },
       fail: (error) => {
-        console.log('静音并锁定 ${targetUserID} 失败', error)
+        console.log('邀请打开麦克风失败', error)
       }
     })
 }
@@ -415,36 +405,34 @@ const { addLiveSeatEventListener } = useLiveSeatState(liveID);
 
 // userA 监听主播的操作,在页面初始化时订阅事件
 onMounted(() => {
-    addLiveSeatEventListener(liveID, 'onLocalMicrophoneClosedByAdmin', {
-      callback: () => {
-        console.log('被主播静音了')
-        // 可以在此进行弹框提示
-      }
+    addLiveSeatEventListener(liveID, 'onLocalMicrophoneClosedByAdmin', () => {
+      console.log('被主播静音了')
+      // 可以在此进行弹框提示
     })
-    addLiveSeatEventListener(liveID, 'onLocalMicrophoneOpenedByAdmin', {
-      callback: () => {
-        console.log('主播已解除静音锁定')
-        // 可以在此进行弹框提示
-      }
+    addLiveSeatEventListener(liveID, 'onLocalMicrophoneOpenedByAdmin', () => {
+      console.log('主播已解除静音锁定')
+      // 可以在此进行弹框提示
     })
 })
 ```
 
 #### closeRemoteMicrophone 接口参数：
-| **参数** | **类型** | **描述** |
-| --- | --- | --- |
-| `liveID` | `string` | 当前语聊房的`liveID`。 |
-| `userID` | `string` | 被操作的用户`userID`。 |
-| `success` | `Function` | 静音成功的回调。 |
-| `fail` | `Function` | 静音失败的回调。 |
+
+|**参数**|**类型**|**描述**|
+|---------|---------|---------|
+|`liveID`|`string`|当前语聊房的`liveID`。|
+|`userID`|`string`|被操作的用户 `userID`。|
+|`success`|`Function`|静音成功的回调。|
+|`fail`|`Function`|静音失败的回调。|
 
 #### openRemoteMicrophone 接口参数：
-| **参数** | **类型** | **描述** |
-| --- | --- | --- |
-| `liveID` | `string` | 当前语聊房的`liveID`。 |
-| `userID` | `string` | 被操作的用户`userID`。 |
-| `success` | `Function` | 解除静音成功的回调。 |
-| `fail` | `Function` | 解除静音失败的回调。 |
+
+|**参数**|**类型**|**描述**|
+|---------|---------|---------|
+|`liveID`|`string`|当前语聊房的 `liveID`。|
+|`userID`|`string`|被操作的用户 `userID`。|
+|`success`|`Function`|解除静音成功的回调。|
+|`fail`|`Function`|解除静音失败的回调。|
 
 ### 主播将麦上用户踢下麦位
 
@@ -469,7 +457,7 @@ const kickOutOfSeat = () => {
       liveID: 'xxx', // 当前语聊房的 liveID
       userID: targetUserID,
       success: () => {
-        console.log('已将 ${targetUserID} 踢下麦位')
+        console.log('踢下麦位成功')
       },
       fail: (error) => {
         console.log('踢人失败', error)
@@ -479,29 +467,28 @@ const kickOutOfSeat = () => {
 
 onMounted(() => {
     // "userB" 收到被踢下麦事件
-    addLiveSeatEventListener(liveID, 'onKickedOffSeat', {
-      callback: () => {
+    addLiveSeatEventListener(liveID, 'onKickedOffSeat', () => {
         console.log('被主播踢下麦')
         // 可以在此进行弹框提示
-      }
     })
 })
 ```
 
 #### kickUserOutOfSeat 接口参数：
-| **参数** | **类型** | **描述** |
-| --- | --- | --- |
-| `liveID` | `string` | 当前语聊房的`liveID`。 |
-| `userID` | `String` | 被踢下麦的用户`userID`。 |
-| `success` | `Function` | 踢下麦成功的回调。 |
-| `fail` | `Function` | 踢下麦失败的回调。 |
+
+|**参数**|**类型**|**描述**|
+|---------|---------|---------|
+|`liveID`|`string`|当前语聊房的 `liveID`。|
+|`userID`|`String`|被踢下麦的用户 `userID`。|
+|`success`|`Function`|踢下麦成功的回调。|
+|`fail`|`Function`|踢下麦失败的回调。|
 
 ### 主播锁定和解锁麦位
 
 主播可以锁定或解锁某个麦位。
 
 #### 实现方式：
-1. **锁定麦位**：主播可调用 `lockSeat` 方法锁定指定索引的麦位，麦位被锁定后，观众无法通过 `applyForSeat` 或`takeSeat` 占用该麦位。
+1. **锁定麦位**：主播可调用 `lockSeat` 方法锁定指定索引的麦位，麦位被锁定后，观众无法通过 `applyForSeat` 或 `takeSeat` 占用该麦位。
 
 2. **解锁麦位**：调用 `unlockSeat` 可以解锁麦位，解锁后该麦位可以再次被占用。
 
@@ -542,20 +529,22 @@ const unlock = () => {
 ```
 
 #### lockSeat 接口参数：
-| **参数** | **类型** | **描述** |
-| --- | --- | --- |
-| `liveID` | `string` | 当前语聊房的`liveID`。 |
-| `seatIndex` | `number` | 需要锁定的麦位索引。 |
-| `success` | `Function` | 锁麦成功的回调。 |
-| `fail` | `Function` | 锁麦失败的回调。 |
+
+|**参数**|**类型**|**描述**|
+|---------|---------|---------|
+|`liveID`|`string`|当前语聊房的 `liveID`。|
+|`seatIndex`|`number`|需要锁定的麦位索引。|
+|`success`|`Function`|锁麦成功的回调。|
+|`fail`|`Function`|锁麦失败的回调。|
 
 #### unlockSeat 接口参数：
-| **参数** | **类型** | **描述** |
-| --- | --- | --- |
-| `liveID` | `string` | 当前语聊房的`liveID`。 |
-| `seatIndex` | `number` | 需要解锁的麦位索引。 |
-| `success` | `Function` | 解锁麦位成功的回调。 |
-| `fail` | `Function` | 解锁麦位失败的回调。 |
+
+|**参数**|**类型**|**描述**|
+|---------|---------|---------|
+|`liveID`|`string`|当前语聊房的 `liveID`。|
+|`seatIndex`|`number`|需要解锁的麦位索引。|
+|`success`|`Function`|解锁麦位成功的回调。|
+|`fail`|`Function`|解锁麦位失败的回调。|
 
 ### 移动麦位
 
@@ -564,7 +553,7 @@ const unlock = () => {
 #### 实现方式：
 1. **主播移动麦位**：主播可以调用此接口将任意用户移动到指定麦位。此时 `userID` 传入目标用户的 ID，`targetIndex`是目标麦位索引，`policy` 参数来指定如果目标麦位有人时的移动策略，详细参见 [接口参数](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/interface.html#MoveUserToSeatOptions) 说明。
 
-2. **普通上麦用户移动自己麦位**：普通上麦用户也可以调用此接口来移动自己。此时 `userID` 必须传入用户自己的 ID，`targetIndex` 传入想去的新麦位索引，此时`policy` 参数无效，如果目标麦位有人时会报错并停止移动。
+2. **普通上麦用户移动自己麦位**：普通上麦用户也可以调用此接口来移动自己。此时 `userID` 必须传入用户自己的 ID，`targetIndex` 传入想去的新麦位索引，此时 `policy` 参数无效，如果目标麦位有人时会报错并停止移动。
 
 #### 示例代码：
 ``` typescript
@@ -572,7 +561,7 @@ import { useLiveSeatState } from "@/uni_modules/tuikit-atomic-x/state/LiveSeatSt
 
 //通过 liveID 获取 LiveSeatState 的实例
 const { moveUserToSeat } = useLiveSeatState(liveID);
-
+const newSeatIndex = 2; // 目标麦位索引。
 const moveSeat = () => {
     moveUserToSeat({
       liveID: 'xxx', // 当前语聊房 liveID
@@ -580,7 +569,7 @@ const moveSeat = () => {
       targetIndex: newSeatIndex, // 目标麦位
       policy: 'FORCE_REPLACE',
       success: () => {
-        console.log('已成功移动到 ${newSeatIndex} 号麦位')
+        console.log('移动麦位成功')
       },
       fail: (error) => {
         console.log('换座失败', error)
@@ -590,21 +579,22 @@ const moveSeat = () => {
 ```
 
 #### moveUserToSeat 接口参数：
-| **参数** | **类型** | **描述** |
+| <strong>参数</strong> | <strong>类型</strong> | <strong>描述</strong> |
 | --- | --- | --- |
-| `userID` | `string` | 需要移麦的用户`userID`。 |
-| `targetIndex` | `number` | 目标麦位索引。 |
-| `policy` | `string` | 目标麦位有人时的移动策略枚举：<br>- `'ABORT_WHEN_OCCUPIED'`：目标麦位有人时放弃移动（默认策略）​​<br>- `'FORCE_REPLACE'`：强制替换目标麦位上的用户​​，被替换的用户将会被踢下麦<br>- `'SWAP_POSITION'`：与目标麦位用户交换位置​​。 |
-| `success` | `Function` | 移动麦位成功的回调。 |
-| `fail` | `Function` | 移动麦位失败的回调。 |
+| <code>userID</code> | <code>string</code> | 需要移麦的用户 <code>userID</code>。 |
+| <code>targetIndex</code> | <code>number</code> | 目标麦位索引。 |
+| <code>policy</code> | <code>string</code> | 目标麦位有人时的移动策略枚举：<br>- <code>'ABORT_WHEN_OCCUPIED'</code>：目标麦位有人时放弃移动（默认策略）​​<br>- <code>'FORCE_REPLACE'</code>：强制替换目标麦位上的用户​​，被替换的用户将会被踢下麦<br>- <code>'SWAP_POSITION'</code>：与目标麦位用户交换位置​​。 |
+| <code>success</code> | <code>Function</code> | 移动麦位成功的回调。 |
+| <code>fail</code> | <code>Function</code> | 移动麦位失败的回调。 |
 
 ## API 文档
 
 关于 [CoGuestState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState) 和 [LiveSeatState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveSeatState) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅 AtomicXCore 框架的官方 API 文档。本指南使用到的相关 Store 如下：
-| **State** | **功能描述** | **API 文档** |
-| --- | --- | --- |
-| CoGuestState | 观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风 / 摄像头），状态同步。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState) |
-| LiveSeatState | 麦位管理：静音/解除静音，锁定/解锁麦位，踢人下麦、远程控制麦上用户麦克风，麦列表状态监听 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveSeatState) |
+
+|**State**|**功能描述**|**API 文档**|
+|---------|---------|---------|
+|CoGuestState|观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风 / 摄像头），状态同步。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-CoGuestState)|
+|LiveSeatState|麦位管理：静音/解除静音，锁定/解锁麦位，踢人下麦、远程控制麦上用户麦克风，麦列表状态监听|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveSeatState)|
 
 ## 常见问题
 
@@ -624,7 +614,7 @@ const moveSeat = () => {
 
 - 通过 `seatInfo.userInfo.microphoneStatus` 判断麦上用户的麦克风状态。
 
-### LiveSeatState 和 DeviceState  都有麦克风接口，它们有何区别？
+### LiveSeatState 和 DeviceState 都有麦克风接口，它们有何区别？
 
 这是一个非常重要的问题。`DeviceState` 管理的是物理设备，而 `LiveSeatState` 管理的是麦位业务（即音频流）。
 

package/resource/{doc → knowledge}/livekit/core-sdk/voice/uni-app/voice-gift.md

@@ -40,19 +40,14 @@
 import { useGiftState } from "@/uni_modules/tuikit-atomic-x/state/GiftState";
 import { onMounted, watch } from 'vue';
 
-// liveID 是语聊房的唯一标识
-const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
-
 // 通过 liveID 获取 GiftState 的实例
 const { addGiftListener, usableGifts } = useGiftState(liveID);
 
 onMounted(() => {
-    addGiftListener(liveID, 'onReceiveGift', {
-       callback: (event) => {
+    addGiftListener(liveID, 'onReceiveGift', (event) => {
          const gift = JSON.parse(event)
          console.log('收到礼物', gift)
          // 在此进行礼物的处理逻辑，例如 svga 格式的礼物进行播放，其他格式的进行弹窗提示
-       }
      })
 })
 
@@ -65,26 +60,26 @@ watch(usableGifts, (newVal, oldVal) => {
 #### 礼物列表结构体参数
 - `GiftCategory`**参数说明**
 
-| **参数** | **类型** | **描述** |
-| --- | --- | --- |
-| `categoryID` | `string` | 礼物分类的唯一 ID。 |
-| `name` | `string` | 礼物分类的显示名称。 |
-| `desc` | `string` | 礼物分类的描述信息。 |
-| `extensionInfo` | `[string: string]` | 扩展信息字段。 |
-| `giftList` | `[string]` | 该分类下包含的 Gift 礼物对象数组。 |
+   |**参数**|**类型**|**描述**|
+   |---------|---------|---------|
+   |`categoryID`|`string`|礼物分类的唯一 ID。|
+   |`name`|`string`|礼物分类的显示名称。|
+   |`desc`|`string`|礼物分类的描述信息。|
+   |`extensionInfo`|`[string: string]`|扩展信息字段。|
+   |`giftList`|`[string]`|该分类下包含的 Gift 礼物对象数组。|
 
 - `Gift`** 参数说明**
 
-| **参数** | **类型** | **描述** |
-| --- | --- | --- |
-| `giftID` | `string` | 礼物的唯一 ID。 |
-| `name` | `string` | 礼物的显示名称。 |
-| `desc` | `string` | 礼物的描述信息。 |
-| `iconURL` | `string` | 礼物图标 URL。 |
-| `resourceURL` | `string` | 礼物动画资源 URL。 |
-| `level` | `number` | 礼物等级。 |
-| `coins` | `number` | 礼物价格。 |
-| `extensionInfo` | `[string: string]` | 扩展信息字段。 |
+   |**参数**|**类型**|**描述**|
+   |---------|---------|---------|
+   |`giftID`|`string`|  礼物的唯一 ID。|
+   |`name`|`string`|  礼物的显示名称。|
+   |`desc`|`string`|  礼物的描述信息。|
+   |`iconURL`|`string`|  礼物图标 URL。|
+   |`resourceURL`|`string`|  礼物动画资源 URL。|
+   |`level`|`number`|  礼物等级。|
+   |`coins`|`number`|  礼物价格。|
+   |`extensionInfo`|`[string: string]`|  扩展信息字段。|
 
 ### 步骤3：获取礼物列表
 
@@ -102,11 +97,8 @@ watch(usableGifts, (newVal, oldVal) => {
 import { useGiftState } from "@/uni_modules/tuikit-atomic-x/state/GiftState";
 import { onMounted } from 'vue';
 
-// liveID 是语聊房的唯一标识
-const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
-
 // 通过 liveID 获取 GiftState 的实例
-const { addGiftListener, usableGifts } = useGiftState(liveID);
+const { addGiftListener, refreshUsableGifts } = useGiftState(liveID);
 
 onMounted(() => {
     refreshUsableGifts({
@@ -135,40 +127,36 @@ onMounted(() => {
 
 #### 代码示例:
 ``` typescript
-
 import { useGiftState } from "@/uni_modules/tuikit-atomic-x/state/GiftState";
-
-// liveID 是语聊房的唯一标识
-const liveID = 'your_live_id'; // 替换为实际的语聊房 liveID
 
 // 通过 liveID 获取 GiftState 的实例
 const { sendGift } = useGiftState(liveID);
 
-// 用户发送一个礼物
-const sendGift = () => {
+// 用户发送一个礼物（函数重命名，并接收 giftID 作为参数）
+const handleSendGift = (giftID: string) => {
     sendGift({
       liveID: 'xxx', // 当前直播间 liveID
       giftID: giftID,
       count: 1,
       success: () => {
-        console.log('礼物 ${giftID} 发送成功')
+        console.log(`礼物 ${giftID} 发送成功`);
       },
       fail: (error) => {
-        console.log('礼物发送失败', error)
-        // 可以在此提示用户，例如“余额不足”或“网络错误”
+        console.log('礼物发送失败', error);
       },
-    })
+    });
 }
 ```
 
 #### `sendGift`接口参数
-| **参数名** | **类型** | **描述** |
-| --- | --- | --- |
-| `liveID` | `string` | 当前直播间的`liveID`。 |
-| `giftID` | `string` | 要发送的礼物的唯一 ID。 |
-| `count` | `number` | 发送的数量。 |
-| `success` | `Function` | 发送成功的回调。 |
-| `fail` | `Function` | 发送失败的回调。 |
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|`liveID`|`string`|当前直播间的`liveID`。|
+|`giftID`|`string`|要发送的礼物的唯一 ID。|
+|`count`|`number`|发送的数量。|
+|`success`|`Function`|发送成功的回调。|
+|`fail`|`Function`|发送失败的回调。|
 
 ## 功能进阶
 
@@ -222,9 +210,10 @@ const sendGift = () => {
 #### 调用流程图
 
 #### 涉及 REST API 接口一览
-| 接口 | 说明 | 请求示例 |
-| --- | --- | --- |
-| 回调配置 - 发送礼物之前回调 | 客户后台可以通过该回调决定是否通过送礼前校验等场景 | 调用示例 |
+
+|接口|说明|请求示例|
+|---------|---------|---------|
+|回调配置 - 发送礼物之前回调|客户后台可以通过该回调决定是否通过送礼前校验等场景|调用示例|
 
 ### 实现全屏礼物动画播放
 
@@ -233,13 +222,14 @@ const sendGift = () => {
 #### 实现方式
 
 `AtomicXCore` 本身包含礼物动画播放器，您可以根据业务需求选择并集成第三方库。以下是两种方案的对比：
-| **对比项** | **内置方案 (SVGAPlayer)** | **高级方案 (TCEffectPlayerKit)** |
-| --- | --- | --- |
-| 计费 | 免费 | 付费 (需购买 License)，请参见 [付费指引](https://cloud.tencent.com/document/product/616/116461) |
-| 集成方式 | AtomicXCore 内置 | 需额外集成 TCEffectPlayerKit 并进行鉴权 |
-| 动画格式支持 | 仅支持 SVGA | SVGA、PAG、WebP、Lottie、MP4 等多种格式 |
-| 性能 | 建议 SVGA 文件 ≤ 10MB | 支持更大的动画文件，复杂特效/多动画并发/低端机表现更优 |
-| 推荐场景 | 礼物动画格式统一为 SVGA，且文件大小可控 | 需要支持多种动画格式，或对动画性能/设备兼容性有更高要求 |
+
+|**对比项**|**内置方案 (SVGAPlayer)**|**高级方案 (TCEffectPlayerKit)**|
+|---------|---------|---------|
+|计费|免费 |付费 (需购买 License)，请参见 [付费指引](https://cloud.tencent.com/document/product/616/116461)|
+|集成方式|AtomicXCore 内置|需额外集成 TCEffectPlayerKit 并进行鉴权|
+|动画格式支持|仅支持 SVGA|SVGA、PAG、WebP、Lottie、MP4 等多种格式|
+|性能|建议 SVGA 文件 ≤ 10MB|支持更大的动画文件，复杂特效/多动画并发/低端机表现更优|
+|推荐场景|礼物动画格式统一为 SVGA，且文件大小可控|需要支持多种动画格式，或对动画性能/设备兼容性有更高要求|
 
 本章节主要演示基础方案的集成。如果您选择高级方案，请参考 [TCEffectPlayer 集成指引](https://cloud.tencent.com/document/product/616/116474)。
 
@@ -278,7 +268,6 @@ onMounted(() => {
      })
 })
 </script>
-
 ```
 
 ### 在弹幕区展示礼物赠送消息
@@ -329,10 +318,11 @@ onMounted(() => {
 ## API 文档
 
 关于 [GiftState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 AtomicXCore 框架的官方 API 文档。本指南使用到的相关 Store 如下：
-| **State** | **功能描述** | **API 文档** |
-| --- | --- | --- |
-| GiftState | 礼物互动：获取礼物列表，发送 / 接收礼物，监听礼物事件（含发送者、礼物详情）。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState) |
-| BarrageState | 弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState) |
+
+|**State**|**功能描述**|**API 文档**|
+|---------|---------|---------|
+|GiftState|礼物互动：获取礼物列表，发送 / 接收礼物，监听礼物事件（含发送者、礼物详情）。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-GiftState)|
+|BarrageState|弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。|[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState)|
 
 ## 常见问题