文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>无 UI 集成>搭建语聊房>快速接入>快速接入（uni-app）

快速接入（uni-app）

最近更新时间：2025-11-18 21:37:22

我的收藏

本页目录：

本文档将帮助开发者使用 AtomicXCore SDK 的 LiveListState 和 LiveSeatState 快速构建一个包含主播开播和观众进房功能的语聊房 App。

准备工作

步骤 1. 开通服务

请参见 开通服务，获取体验版或付费版 SDK。

步骤2. 导入 tuikit-atomic-x

1. 安装组件：打开 AtomicXCore SDK ，单击下载插件并导入HBuilderX，选择需要集成的项目并单击确定。

2. 配置工程权限: 请在应用的 manifest.json 文件的app-plus > distribute 节点下，确保添加了以下必要的权限：
Android 平台（android节点）：在 permissions 数组中，请确保包含以下权限：
"<uses-permission android:name=\\"android.permission.RECORD_AUDIO\\" />"
iOS 平台（ios 节点）：在 privacyDescription 对象中，请确保包含以下描述：
"NSMicrophoneUsageDescription" : "应用需要访问您的麦克风以进行直播"
在 UIBackgroundModes 数组中，添加 audio 以支持后台播放音频。
"UIBackgroundModes" : [ "audio" ]

步骤 3. 完成登录

在您的项目中调用 LoginState 中的 login 方法完成登录，这是使用 AtomicXCore 所有功能的关键前提。
重要：
推荐在您 App 自身的用户账户登录成功后，再调用 LoginState 中的 login 方法，以确保登录业务逻辑的清晰和一致。
import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";
  
const { login } = useLoginState();
  
const handleLogin = () => {
    login({
      sdkAppID: 1400000001,  // 替换为您的 SDKAppID
      userID: "test_001",    // 替换为您的 UserID
      userSig: "xxxxxxxxxx"  // 替换为您的 UserSig
    })
 }
登录接口参数说明：
参数
类型
说明
sdkAppID
number
从 控制台获取，通常是以 140 或 160 开头的 10 位整数。
userID
string
当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突，请勿使用 1、123 等简单 ID。
userSig
string
用于腾讯云鉴权的票据。请注意：
开发环境：您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者 通过 UserSig 辅助工具 生成临时的 UserSig。
生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参考 服务端生成 UserSig。
更多信息请参见 如何计算及使用 UserSig。

搭建语音聊天室

步骤1：实现房主创建语聊房

房主开播流程如下，您只需执行以下几步操作，即可快速搭建一个语聊房。

1. 初始化麦位 State

在您的房主页面中，创建一个 LiveSeatState 实例。您需要监听响应式数据的变化，以实时获取麦位数据来渲染您的 UI。
import { watch } from 'vue';
import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';

// 使用 liveID 获取 LiveSeatState 实例
const { seatlist } = useLiveSeatState(liveID);

2. 打开麦克风

通过调用 DeviceState 的 openLocalMicrophone 接口打开麦克风，示例代码如下：
import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";
  
const { openLocalMicrophone } = useDeviceState();

const openMic = () => {
    openLocalMicrophone()
}

3. 开始语聊

通过调用 LiveListState 的 createLive 接口开始语聊房直播，完整示例代码如下：
import { useLiveListState } from '@/uni_modules/tuikit-atomic-x/state/LiveListState';

// 获取 LiveListState 实例
const { createLive } = useLiveListState();

// 开始直播
const startLive = () => {
    createLive({
      liveInfo: {
        liveID: 'xxx', // 设置直播的房间 id
        liveName: 'text', // 设置直播的房间名称
        seatLayoutTemplateID: 600, // 配置布局模板，默认：600 动态宫格布局
        keepOwnerOnSeat: true, // 配置主播始终在麦位上
      },
      success: () => {        
        console.log('创建直播间成功')
        //您可以在这里进行页面的跳转
      },
      fail: (error) => {
        console.log('创建直播间失败', error)
      }
    });
  };
}
LiveInfo参数说明:
参数名
类型
属性
描述
liveID
string
必填
直播间的唯一标识符
liveName
string
选填
直播间的标题
notice
string
选填
直播间的公告信息
isMessageDisable
Bool
选填
是否禁言（true：是，false：否）
isPublicVisible
Bool
选填
是否公开可见（true：是，false：否）
isSeatEnabled
Bool
选填
是否启用麦位功能（true：是，false：否）
keepOwnerOnSeat
Bool
选填
是否保持房主在麦位上
maxSeatCount
number
必填
最大麦位数量
seatMode
string
选填
上麦模式（'FREE'：自由上麦，'APPLY'：申请上麦）
seatLayoutTemplateID
number
必填
麦位布局模板 ID
coverURL
string
选填
直播间的封面图片地址
backgroundURL
string
选填
直播间的背景图片地址
categoryList
[number]
选填
直播间的分类标签列表
activityStatus
number
选填
直播活动状态
isGiftEnabled
Bool
选填
是否启用礼物功能（true：是，false：否）

4. 构建麦位 UI 界面

通过 LiveSeatState 实例，监听 seatList 的变化，以实时获取麦位数据来渲染您的界面 UI。您可以在主播页通过以下方式监听数据：
import { watch } from 'vue';
import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';

// 使用 liveID 获取 LiveSeatState 实例
const { seatlist } = useLiveSeatState(liveID);

watch(seatlist,(newSeatList) => {
    console.log('新的麦位列表', newSeatList)
    // 用这个数据来维护您的 UI
})

5. 结束语聊

语聊结束后，房主可以调用 LiveListState 的 endLive 接口结束语聊，SDK 会处理停止推流和销毁房间的逻辑。
import { useLiveListState } from '@/uni_modules/tuikit-atomic-x/state/LiveListState';

// LiveListState 实例
const { endLive } = useLiveListState();

// 结束直播
const endLive = () => {
    endLive({
      success: () => {        
        console.log('结束直播成功')
        //您可以在这里进行页面的跳转
      },
      fail: (error) => {
        console.log('结束直播失败', error)
      }
    });
 }

步骤2：实现观众进入语聊房

观众进房流程如下，通过简单几步操作，即可实现观众进入语聊房

1. 初始化麦位 State

在您的观众页面 中，创建 LiveSeatState 实例，并监听 seatList 的变化，以渲染麦位 UI。
import { watch } from 'vue';
import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';


// 使用 liveID 获取 LiveSeatState 实例
const { seatlist } = useLiveSeatState(liveID);

watch(seatlist,(newSeatList) => {
    console.log('新的麦位列表', newSeatList)
    // 用这个数据来维护您的 UI
})

2. 进入语聊房

通过调用 LiveListState 的 joinLive 接口加入语聊房，完整示例代码如下：
import { useLiveListState } from '@/uni_modules/tuikit-atomic-x/state/LiveListState';

// 获取 LiveListState 实例
const { joinLive } = useLiveListState();

// 加入直播
const joinLive = () => {
    joinLive({
      liveID: 'xxx', // 想要加入的语聊房间 liveID
      success: () => {        
        console.log('成功进入语聊房')
        //您可以在这里进行页面的跳转
      },
      fail: (error) => {
        console.log('进入语聊房失败', error)
      }
    });
 }

3. 构建麦位 UI 界面

观众构建麦位 UI 界面的流程与主播完全一致，请参考主播 构建麦位 UI 界面

4. 退出语聊房

观众退出语聊房时，需要调用 LiveListState 的 leaveLive 接口来退出。
import { useLiveListState } from '@/uni_modules/tuikit-atomic-x/state/LiveListState';

// 获取 LiveListState 实例
const { leaveLive } = useLiveListState();

// 退出直播
const leaveLive = () => {
    leaveLive({
      liveID: 'xxx', // 您当前加入的直播间
      success: () => {        
        console.log('退出直播成功')
        //您可以在这里进行页面的跳转
      },
      fail: (error) => {
        console.log('退出直播失败', error)
      }
    });
 }

运行效果

完成上述步骤后，即可完成一个最基础的语聊直播场景。您可以参考 丰富语聊场景 来完善语聊场景。


功能进阶

实现麦上用户说话音浪

在语聊房场景中，一个常见的需求是当麦上用户说话时，在其头像上显示一个波浪动画，以提示全房间用户“谁在说话”，LiveSeatState 提供了 speakingUsers 数据流，专门用于实现此功能。

实现效果


在您构建的麦位 UI 界面中监听 speakingUsers 变化，并更新“正在说话”状态，代码示例如下
import { watch } from 'vue';
import { useLiveSeatState } from '@/uni_modules/tuikit-atomic-x/state/LiveSeatState';

// 使用 liveID 获取 LiveSeatState 实例
const { speakingUsers } = useLiveSeatState(liveID);

watch(speakingUsers,(newSpeaker) => {
    console.log('正在说话的人', newSpeaker)
    // 用这个数据和之前监听的 seatList 进行匹配来更新 UI
})

丰富语音聊天室场景

当您完成了基础的语音聊天室功能后，您可以参考以下功能指南来为语音聊天室添加丰富的互动玩法。
语音聊天室功能
功能介绍
功能 State
实现指南
实现观众音频连麦
观众申请上麦，与主播进行实时音频互动。
实现观众连麦
添加弹幕聊天功能
观众可以在语音聊天室发送和接收实时文字消息。
实现弹幕功能
构建礼物赠送系统
观众可以向主播赠送虚拟礼物，增加互动和趣味性。
GiftState
实现礼物功能
添加设置音效功能
变声（童声 / 男声）、混响（KTV 等）、耳返调节，实时切换特效。
实现音效功能

API 文档

State
功能描述
API 文档
LiveListState
语音聊天室全生命周期管理：创建 / 加入 / 离开 / 销毁房间，查询房间列表，修改语音聊天室信息（名称、公告等），监听语音聊天室状态（如被踢出、结束）。
DeviceState
音视频设备控制：麦克风（开关 / 音量），设备状态实时监听。
CoGuestState
观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风），状态同步。
CoHostState
主播跨房连线：支持多布局模板（动态网格等），发起 / 接受 / 拒绝连线，连麦主播互动管理。
GiftState
礼物互动：获取礼物列表，发送 / 接收礼物，监听礼物事件（含发送者、礼物详情）。
BarrageState
弹幕功能：发送文本 / 自定义弹幕，维护弹幕列表，实时监听弹幕状态。
LikeState
点赞互动：发送点赞，监听点赞事件，同步总点赞数。
LiveAudienceState
观众管理：获取实时观众列表（ID / 名称 / 头像），统计观众数量，监听观众进出事件。
AudioEffectState
音频特效：变声（童声 / 男声）、混响（KTV 等）、耳返调节，实时切换特效。

常见问题

1. 代码变更后，没有效果或者编译报错？

引入 uni_modules 后，需要重新制作自定义基座，详情参考制作自定义基座流程

2. 原生能力集成问题

问题：插件调用失败或无响应。
解决方案：
必须打包自定义基座：在开发调试原生插件时，不能使用标准基座，必须通过 HBuilderX -> 运行 -> 运行到手机或模拟器 -> 制作自定义基座，然后选择这个自定义基座来运行。
检查权限：如本文档“准备工作”中所述，manifest.json 必须声明相机、麦克风等权限。
查看原生日志：这是终极调试手段。通过 Android Studio (Logcat) 或 Xcode (Console) 查看设备的原生日志，通常能发现最直接的错误信息。

中国站
目录