@tencentcloud/sdk-mcp 1.3.9 → 1.4.0

package/resource/doc/livekit/{voice → core-sdk/voice}/ios/voice-room-list.md

@@ -1,8 +1,5 @@
 `LiveListStore` 是 `AtomicXCore` 中负责管理直播房间列表、创建、加入以及维护房间状态的核心模块。通过`LiveListStore`，您可以为您的应用构建完整的直播生命周期管理。
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/6fd3c4f2ab6011f0b5345254005ef0f7.png)
-
-
 ## 核心功能
 - **直播列表拉取**：获取当前所有公开的直播间列表，支持分页加载。
 
@@ -14,58 +11,21 @@
 
 - **自定义业务数据**：强大的自定义元数据（`MetaData`）能力，允许您在房间内存储和同步任何业务相关的信息，例如直播状态、音乐信息、自定义角色等 。
 
-
 ## 核心概念
 
 在开始集成之前，我们先通过下表了解一下 `LiveListStore` 相关的几个核心概念：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**核心概念**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**核心职责与描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`LiveInfo`</td>
-
-<td rowspan="1" colSpan="1" >`struct`</td>
-
-<td rowspan="1" colSpan="1" >代表一个直播间的所有信息模型。包含了直播ID (`liveID`)、名称 (`liveName`)、房主信息 (`liveOwner`) 以及自定义元数据 (`metaData`) 等。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`LiveListState`</td>
-
-<td rowspan="1" colSpan="1" >`struct`</td>
-
-<td rowspan="1" colSpan="1" >代表直播列表模块的当前状态。其核心属性 liveList 是一个 `[LiveInfo] `数组，存储了拉取到的直播列表；`currentLive` 则代表用户当前所在的直播间信息。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`LiveListEvent`</td>
-
-<td rowspan="1" colSpan="1" >`enum`</td>
-
-<td rowspan="1" colSpan="1" >代表直播房间的全局事件。分为 `.onLiveEnded` (直播结束) 和 `.onKickedOutOfLive` (被踢出直播) 两种，用于处理关键的房间状态变更。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`LiveListStore`</td>
-
-<td rowspan="1" colSpan="1" >`class`</td>
-
-<td rowspan="1" colSpan="1" >这是与直播列表和房间生命周期交互的核心管理类。它是一个全局单例 (shared)，负责所有直播房间的创建、加入、信息更新等操作。</td>
-</tr>
-</table>
-
+| **核心概念** | **类型** | **核心职责与描述** |
+| --- | --- | --- |
+| `LiveInfo` | `struct` | 代表一个直播间的所有信息模型。包含了直播ID (`liveID`)、名称 (`liveName`)、房主信息 (`liveOwner`) 以及自定义元数据 (`metaData`) 等。 |
+| `LiveListState` | `struct` | 代表直播列表模块的当前状态。其核心属性 liveList 是一个 `[LiveInfo] `数组，存储了拉取到的直播列表；`currentLive` 则代表用户当前所在的直播间信息。 |
+| `LiveListEvent` | `enum` | 代表直播房间的全局事件。分为 `.onLiveEnded` (直播结束) 和 `.onKickedOutOfLive` (被踢出直播) 两种，用于处理关键的房间状态变更。 |
+| `LiveListStore` | `class` | 这是与直播列表和房间生命周期交互的核心管理类。它是一个全局单例 (shared)，负责所有直播房间的创建、加入、信息更新等操作。 |
 
 ## 实现步骤
 
 ### 步骤1：组件集成
 
-请参考 [快速接入](https://write.woa.com/document/192834898445422592) 集成 **AtomicXCore**，并完成 [搭建基础语聊房](https://write.woa.com/document/192834898445422592)的功能实现。
+请参考 快速接入 集成 **AtomicXCore**，并完成 搭建基础语聊房的功能实现。
 
 ### 步骤2：实现观众从直播列表进入直播间
 
@@ -76,24 +36,24 @@
 
    ``` swift
    class LiveListViewController: UIViewController, UICollectionViewDataSource, UICollectionViewDelegate, UICollectionViewDelegateFlowLayout {
-   
+
        private let liveListStore = LiveListStore.shared
        private var cancellables = Set<AnyCancellable>()
        private var liveList: [LiveInfo] = []
-       
+
        private var collectionView: UICollectionView!
-   
+
        override func viewDidLoad() {
            super.viewDidLoad()
            setupUI()
            bindStore()
            fetchLiveList()
        }
-       
+
        private func bindStore() {
            // 订阅 state，自动接收列表更新
            liveListStore.state
-               .subscribe(StatePublisherSelector(keyPath: \LiveListState.liveList))           
+               .subscribe(StatePublisherSelector(keyPath: \LiveListState.liveList))
                .removeDuplicates()
                .receive(on: DispatchQueue.main)
                .sink { [weak self] fetchedList in
@@ -102,7 +62,7 @@
                }
                .store(in: &cancellables)
        }
-   
+
        private func fetchLiveList() {
            liveListStore.fetchLiveList(cursor: "", count: 20) { result in
                if case .failure(let error) = result {
@@ -110,17 +70,17 @@
                }
            }
        }
-       
+
        // 当用户点击列表中的某个Cell时
        func collectionView(_ collectionView: UICollectionView, didSelectItemAt indexPath: IndexPath) {
            let selectedLiveInfo = liveList[indexPath.item]
-           
+
            // 创建观众观看页面，并将 liveID 传入
            let audienceVC = YourAudienceViewController(liveID: selectedLiveInfo.liveID)
            audienceVC.modalPresentationStyle = .fullScreen
            present(audienceVC, animated: true)
        }
-       
+
        // --- UICollectionViewDataSource, Delegate, and UI setup methods ---
        private func setupUI() {
            let layout = UICollectionViewFlowLayout()
@@ -131,11 +91,11 @@
            collectionView.register(UICollectionViewCell.self, forCellWithReuseIdentifier: "LiveCell")
            view.addSubview(collectionView)
        }
-   
+
        func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
            return liveList.count
        }
-       
+
        func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
            let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "LiveCell", for: indexPath)
            cell.backgroundColor = .lightGray // 自定义您的Cell样式
@@ -143,7 +103,7 @@
            // ... (例如: cell.titleLabel.text = liveInfo.liveName)
            return cell
        }
-       
+
        func collectionView(_ collectionView: UICollectionView, layout collectionViewLayout: UICollectionViewLayout, sizeForItemAt indexPath: IndexPath) -> CGSize {
            // 单列、双列布局可通过自定义您的Cell大小来实现
            let width = (view.bounds.width - 30) / 2
@@ -154,80 +114,16 @@
 
    **LiveInfo 参数说明**
 
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**参数名**</td>
-
-<td rowspan="1" colSpan="1" >**类型**</td>
-
-<td rowspan="1" colSpan="1" >**描述**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`liveID`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >直播间的唯一标识符</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`liveName`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >直播间的标题</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`coverURL`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >直播间的封面图片地址</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`liveOwner`</td>
-
-<td rowspan="1" colSpan="1" >[LiveUserInfo](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveuserinfo)</td>
-
-<td rowspan="1" colSpan="1" >房主的个人信息</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`totalViewerCount`</td>
-
-<td rowspan="1" colSpan="1" >`Int`</td>
-
-<td rowspan="1" colSpan="1" >直播间的总观看人数</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`categoryList`</td>
-
-<td rowspan="1" colSpan="1" >`[NSNumber]`</td>
-
-<td rowspan="1" colSpan="1" >直播间的分类标签列表</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`notice`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >直播间的公告信息</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`metaData`</td>
-
-<td rowspan="1" colSpan="1" >`[String: String]`</td>
-
-<td rowspan="1" colSpan="1" >开发者自定义的元数据，用于实现复杂的业务场景</td>
-</tr>
-</table>
-
+| **参数名** | **类型** | **描述** |
+| --- | --- | --- |
+| `liveID` | `String` | 直播间的唯一标识符 |
+| `liveName` | `String` | 直播间的标题 |
+| `coverURL` | `String` | 直播间的封面图片地址 |
+| `liveOwner` | [LiveUserInfo](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveuserinfo) | 房主的个人信息 |
+| `totalViewerCount` | `Int` | 直播间的总观看人数 |
+| `categoryList` | `[NSNumber]` | 直播间的分类标签列表 |
+| `notice` | `String` | 直播间的公告信息 |
+| `metaData` | `[String: String]` | 开发者自定义的元数据，用于实现复杂的业务场景 |
 
 ## 功能进阶
 
@@ -235,9 +131,6 @@
 
 在 App 的直播广场页，顶部设有“热门”、“音乐”、“游戏”等分类标签。用户点击不同的标签后，下方的直播列表会动态筛选，只展示对应分类的直播间，从而帮助用户快速发现感兴趣的内容。
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/7dcde616ab4b11f0a68e5254001c06ec.png)
-
-
 #### 实现方式：
 
 核心是利用 `LiveInfo` 模型中的 `categoryList` 属性。
@@ -245,7 +138,6 @@
 
 2. 您的 App 在获取到完整的直播列表后，只需在客户端根据用户选择的分类，对这个列表进行一次简单的筛选，然后刷新 UI 即可。
 
-
 #### 代码示例：
 
 以下示例展示了如何在 `LiveListViewController` 中扩展一个 `LiveListManager` 来处理数据和筛选逻辑。
@@ -305,7 +197,6 @@ class LiveListViewController: UIViewController {
         super.viewDidLoad()
         // ... setupUI ...
 
-
         // 绑定数据
         manager.filteredLiveListPublisher
             .receive(on: DispatchQueue.main)
@@ -315,19 +206,16 @@ class LiveListViewController: UIViewController {
             }
             .store(in: &cancellables)
 
-
         // 首次拉取
         manager.fetchFirstPage()
     }
 
-
     // 当用户点击顶部分类标签 (UISegmentedControl) 时
     @objc func categorySegmentDidChange(_ sender: UISegmentedControl) {
         let selectedCategoryId: NSNumber? = 1 // 假设 "音乐" 分类的ID是 1
         manager.filterLiveList(by: selectedCategoryId)
     }
 
-
     // ... (UICollectionView 相关代码)
 }
 
@@ -342,7 +230,6 @@ class LiveListViewController: UIViewController {
 
 2. 观众端只需订阅` LiveListState.currentLive`，监听 `metaData` 的变化，一旦发现关心的 key 更新，就解析其 value 并刷新业务状态。
 
-
 #### 示例代码：
 ``` swift
 import AtomicXCore
@@ -388,7 +275,7 @@ private func subscribeToDataUpdates() {
                   // ... (例如: playMusic(music))
                     return
                 }
-               
+
             }
             .store(in: &cancellables)
     }
@@ -396,24 +283,9 @@ private func subscribeToDataUpdates() {
 ```
 
 关于 [LiveListStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveliststore) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) 框架的官方 API 文档。本文档使用到的相关 Store 如下：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Store/Component**</td>
-
-<td rowspan="1" colSpan="1" >**功能描述**</td>
-
-<td rowspan="1" colSpan="1" >**API 文档**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveListStore</td>
-
-<td rowspan="1" colSpan="1" >直播间全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改直播信息（名称、公告等），监听直播状态（例如被踢出、结束）。</td>
-
-<td rowspan="1" colSpan="1" >[API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveliststore)</td>
-</tr>
-</table>
-
+| **Store/Component** | **功能描述** | **API 文档** |
+| --- | --- | --- |
+| LiveListStore | 直播间全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改直播信息（名称、公告等），监听直播状态（例如被踢出、结束）。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/liveliststore) |
 
 ## 常见问题
 
@@ -427,7 +299,7 @@ private func subscribeToDataUpdates() {
 
 我们推荐采用以下两种方式进行区分：
 
-**方式一（推荐）：使用 seatLayoutTemplateID 区分**。这是一个用于定义房间布局的模板 ID，关于目前已支持的模板 ID 和效果，请参阅文档[开始直播-运行效果](https://write.woa.com/document/191126382767431680)。您要在创建房间时指定 ID，然后在获取列表时根据 ID 范围来识别业务场景。
+**方式一（推荐）：使用 seatLayoutTemplateID 区分**。这是一个用于定义房间布局的模板 ID，关于目前已支持的模板 ID 和效果，请参阅文档开始直播-运行效果。您要在创建房间时指定 ID，然后在获取列表时根据 ID 范围来识别业务场景。
 - **步骤1：创建房间时指定 ID **调用 LiveListStore.shared.createLive 时，您需要根据业务场景为 LiveInfo 的 seatLayoutTemplateID 属性传入指定范围的 ID：
 
   - 语聊房场景：传入 1 - 199 范围内的模板 ID。
@@ -435,14 +307,12 @@ private func subscribeToDataUpdates() {
   - 视频直播场景：传入 200 - 999 范围内的模板 ID。
 
 - **步骤2：获取列表时筛选 **客户端在 `LiveListStore.state.liveList`中收到列表数据后，通过判断这个 ID 值所属的范围来区分，从而在进入直播间的时候区分两种业务场景。
-   
 
    > **重要提示：**
-   > 
+   >
 
    > 创建房间时，如果传入的 seatLayoutTemplateID 范围与您的业务场景（语聊房、视频直播）不匹配，可能会导致麦位布局出现功能异常。
-   > 
-
+   >
 
    **方式二**：**为 **`liveID`** 添加业务前缀。**这是一种可选的、纯粹的应用层约定，用于辅助您在客户端快速筛选。
 
@@ -450,7 +320,6 @@ private func subscribeToDataUpdates() {
 
   - **步骤2：获取列表时检查前缀 **客户端在拉取到列表后，通过检查 liveID 字符串的前缀来进行区分。
 
-
 ### 使用 `updateLiveMetaData` 时有哪些需要注意的限制和规则？
 
 为了保证系统的稳定和高效，`metaData` 的使用遵循以下规则：

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

@@ -1,8 +1,5 @@
 `LiveAudienceState` 是 `AtomicXCore` 中专门负责管理语聊房观众信息的模块。通过 `LiveAudienceState`，您可以为您的直播应用构建一套完整的观众列表及管理系统。
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100028028022/ef4d5ed8bbbf11f085a55254007c27c5.png)
-
-
 ## 核心功能
 - **实时观众列表**：获取并展示当前在语聊房内的所有观众信息。
 
@@ -14,12 +11,11 @@
 
 - **房间管理**：主播或管理员可以将任意普通观众请出（踢出）语聊房。
 
-
 ## 实现步骤
 
 ### 步骤1：组件集成
 
-请参考 [开始直播](https://write.woa.com/document/191127271985012736) 集成 **AtomicXCore**，完成接入。
+请参考 开始直播 集成 **AtomicXCore**，完成接入。
 
 ### 步骤2：初始化并获取观众列表
 
@@ -37,7 +33,7 @@ const { fetchAudienceList, audienceList } = useLiveAudienceState(liveID)
 onMounted(() => {
     fetchAudienceList({
       liveID: 'xxx', // 当前语聊房的 liveID
-      success: () => {        
+      success: () => {
         // 成功后，响应式数据会自动更新
         console.log('首次拉取观众列表成功')
       },
@@ -52,7 +48,7 @@ watch(audienceList, (newVal, oldVal) => {
     console.log(newVal)
 })
 
-// ... 后续代码 
+// ... 后续代码
 ```
 
 ### 步骤3：监听观众列表状态与实时动态
@@ -77,13 +73,13 @@ watch(audienceCount, (newVal, oldVal) => {
 })
 
 onMounted(() => {
-    addAudienceListener( liveID, 'onAudienceJoined', 
+    addAudienceListener( liveID, 'onAudienceJoined',
       { callback: (event) => {
         const newAudience = JSON.parse(event)
         console.log("观众 ${newAudience.userName} 加入了语聊房")
       }
     })
-    
+
     addAudienceListener( liveID, 'onAudienceLeft',
       { callback: (event) => {
         const departedAudience = JSON.parse(event)
@@ -119,7 +115,7 @@ const kickOut = () => {
       },
       fail: (error) => {
         console.log("将用户 ${userID} 踢出房间失败", error)
-      } 
+      }
     })
 }
 ```
@@ -140,7 +136,7 @@ const { setAdministrator, revokeAdministrator } = useLiveAudienceState(liveID)
 const promoteToAdmin = () => {
     setAdministrator({
       liveID: 'xxx', // 当前语聊房的 liveID
-      userID: 'xxx', // 想要设为管理员的 userID 
+      userID: 'xxx', // 想要设为管理员的 userID
       success: () => {
         console.log("成功将用户 ${userID} 设为管理员")
       },
@@ -154,7 +150,7 @@ const promoteToAdmin = () => {
 const revokeAdmin = () => {
     revokeAdministrator({
       liveID: 'xxx', // 当前语聊房的 liveID
-      userID: 'xxx', // 想要撤销管理员的 userID 
+      userID: 'xxx', // 想要撤销管理员的 userID
       success: () => {
         console.log("成功将用户 ${userID} 的管理员身份撤销")
       },
@@ -189,11 +185,11 @@ const { addAudienceListener, removeAudienceListener } = useLiveAudienceState(liv
 const { appendLocalTip } = useBarrageState(liveID)
 
 onMounted(() => {
-    addAudienceListener(liveID, 'onAudienceJoined', 
+    addAudienceListener(liveID, 'onAudienceJoined',
       { callback: (event) => {
         const newAudience = JSON.parse(event)
         // 创建一条本地提示消息
-        let welcomeTip = {}   
+        let welcomeTip = {}
         welcomeTip.liveID = liveID,
         welcomeTip.sender = { userID: 'xxx' },
         welcomeTip.sequence = Date.now(),
@@ -210,33 +206,11 @@ onMounted(() => {
 
 ## API 文档
 
-关于 [LiveAudienceState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveAudienceState) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 [AtomicXCore](https://write.woa.com/document/192223419814899712) 框架的官方 API 文档。本文档使用到的相关 State 如下：
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**State**</td>
-
-<td rowspan="1" colSpan="1" >**功能描述**</td>
-
-<td rowspan="1" colSpan="1" >**API 文档**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveAudienceState</td>
-
-<td rowspan="1" colSpan="1" >观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。</td>
-
-<td rowspan="1" colSpan="1" >[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveAudienceState)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >BarrageState</td>
-
-<td rowspan="1" colSpan="1" >弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。</td>
-
-<td rowspan="1" colSpan="1" >[API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState)</td>
-</tr>
-</table>
-
+关于 [LiveAudienceState](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveAudienceState) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅随 AtomicXCore 框架的官方 API 文档。本文档使用到的相关 State 如下：
+| **State** | **功能描述** | **API 文档** |
+| --- | --- | --- |
+| LiveAudienceState | 观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-LiveAudienceState) |
+| BarrageState | 弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。 | [API 文档](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/uni-app/zh/v1.0/api/index.html#module-BarrageState) |
 
 ## 常见问题
 
@@ -255,10 +229,6 @@ onMounted(() => {
 
   - **关键点：**在“弹幕风暴”或礼物刷屏等消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，**人数变更的消息可能会被频控策略丢弃**。
 
-
       **这对开发者意味着什么？**
 
-
       `audienceCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 **UI 展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。
-
-