文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>视频通话（含 UI）>快速接入>uni-app（客户端）

uni-app（客户端）

最近更新时间：2026-04-24 17:24:32

我的收藏

本页目录：

本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤，最终获得一个功能完备的音视频通话界面。

说明：
自 2025 年 5 月 1 日起，由于 uni-app 官方限制，CallKit 原生语言插件已终止迭代，为保障业务持续稳定运行，现提供 CallKit UTS 插件方案。
​​CallKit UTS 插件核心优势：​​
支持自定义 UI、深度界面定制。
支持 uni-app 及 uni-app x 项目。
提供插件版本锁定功能，避免因更新导致兼容性问题。

准备工作

环境要求

说明：
HBuilderX 4.64 和 4.65 版本对 UTS 插件打包存在已知兼容性问题，建议使用 4.66 或更高版本。
HBuilderX：HBuilderX 是 uni-app 官方的集成开发环境（IDE），我们需要用它来导入、配置和运行我们的 Demo。
2个移动设备： Android 5.0 以上的设备 / iOS 13.0 及以上设备。

开通服务

您需要开通腾讯云服务，以获取应用所需的唯一身份标识和密钥。 请参考 开通服务 文档，获取 SDKAppId 和 SecretKey，这些参数将在后续的步骤中作为必填参数使用。

代码集成

步骤 1：下载 TUICallKit 源码

1. 克隆项目源码

git clone https://github.com/Tencent-RTC/TUIKit_uni-app.git

2. 导入 atomic-x 组件

将源码中 TUIKit_uni-app/App/uni_modules 目录下的 tuikit-atomic-x 文件夹，完整拷贝到您项目根目录下的 uni_modules 文件夹中。
将源码中 TUIKit_uni-app/App/components 下的文件，完整地拷贝到您项目的 components 文件夹中。
将源码中 TUIKit_uni-app/App/static 目录下的文件，完整拷贝到您项目根目录下的同名文件夹下。
将源码中 TUIKit_uni-app/App/debug 文件夹拷贝到您项目的根目录下，这个目录提供可以方便您在客户端快速生成的 UserSig 的快捷函数。

3. 合并 App.vue 配置。

TUIKit_uni-app/App/App.vue 文件中包含通话能力的初始化逻辑，因此您需要将 TUIKit_uni-app/App/App.vue 文件和您项目下的 App.vue 文件进行合并。
注意：
不要直接覆盖 App.vue 文件！ 打开源码中的 TUIKit_uni-app/App/App.vue， 将其 <script> 部分的 ts 内容追加到您自己项目的 App.vue 的 <script> 标签内。

步骤 2：工程配置

1. 配置 manifest.json。
打开您项目的 manifest.json 文件，在 app-plus > distribute 节点下，确保添加了以下必要的权限：
Android 平台（Android 节点）：在 permissions 数组中，请确保包含以下权限：
"<uses-permission android:name=\\"android.permission.CAMERA\\"/>",
"<uses-permission android:name=\\"android.permission.RECORD_AUDIO\\" />",
"<uses-permission android:name=\\"android.permission.INTERNET\\"/>",
"<uses-permission android:name=\\"android.permission.ACCESS_NETWORK_STATE\\"/>",
"<uses-permission android:name=\\"android.permission.WRITE_EXTERNAL_STORAGE\\"/>"
iOS 平台（iOS 节点）：在 privacyDescription 对象中，请确保包含以下描述：
"NSCameraUsageDescription" : "应用需要访问您的相机以进行通话",
"NSMicrophoneUsageDescription" : "应用需要访问您的麦克风以进行通话"
在 UIBackgroundModes 数组中，添加 audio 以支持后台播放音频。
"UIBackgroundModes" : [ "audio" ]
2. 制作自定义基座。
说明：
由于 TUICallKit 包含原生代码（UTS 插件），您必须制作自定义调试基座才能在真机上运行。
2.1 在 HBuilderX 顶部菜单选择运行 > 运行到手机或模拟器 > 制作自定义调试基座。
2.2 制作成功后，再次选择运行 > 运行到手机或模拟器，在弹窗中勾选使用自定义调试基座后运行到您的手机。
具体操作指引参见 跑通 Demo 的步骤3。

步骤 3：完成登录

集成完成后，您需要完成登录。在您项目中需要使用到通话能力的地方进行登录，这是使用 TUICallKit 的关键步骤，因为只有在登录成功后才能正常使用 TUICallKit 的各项功能，故请您耐心检查相关参数是否配置正确：
import { onMounted } from 'vue';
import { useLoginState } from "@/uni_modules/tuikit-atomic-x/state/LoginState";

const { login } = useLoginState();

onMounted(() => {
  login({
	sdkAppID: 1400000001,     // 请替换为开通服务控制台的 SDKAppID
	userID: "denny",        // 请替换为您的 UserID
	userSig: "xxxxxxxxxxx",  // 您可以在控制台中计算一个 UserSig 并填在这个位置
  });
});

登录接口参数说明
参数
类型
说明
SDKAppID
Number
从 TRTC 控制台 > 应用管理 获取。
userID
String
当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。
userSig
String
用于腾讯云鉴权的票据。请注意：
开发环境：您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 UserSig 或者通过 UserSig 辅助工具 生成临时的 UserSig。
生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参见 服务端生成 UserSig。
更多信息请参见 如何计算及使用 UserSig。

步骤 4：注册通话页面

现在，您需要在 pages.json 文件中告诉您的应用，这个新页面是存在的。
打开您项目根目录下的 pages.json 文件，在 "pages" 数组中，添加以下对象来注册通话页。

{
    "pages": [
        // ... 您项目已有的其他页面配置
        {
            "path": "uni_modules/tuikit-atomic-x/pages/call",
            "style": {
                "navigationBarTitleText": "",
                "disableSwipeBack": true, // 禁止右滑返回，防止直播中误操作退出
                "app-plus": {
                    "titleNView": false // 隐藏原生导航栏，使用页面内的自定义导航
                }
            }
        }
    ]
    // ... 其他配置
}


步骤5：跳转通话页面

在您需要发起通话的地方（具体由您的业务决定，在其点击事件里执行），您需要先调用 calls 函数。在该函数成功执行的 success 回调中，再通过 uni.navigateTo 跳转到通话页面，以确保通话状态已正确建立。
import { useCallState } from '@/uni_modules/tuikit-atomic-x/state/CallState';
import { useDeviceState } from "@/uni_modules/tuikit-atomic-x/state/DeviceState";
const { calls } = useCallState()
const { openLocalCamera, openLocalMicrophone } = useDeviceState();

// 示例：在一个按钮的点击事件中
function startCall() {
    // 跳转到通话页
    calls({
      participantIds: ['xxx'],
      mediaType: 1, // 1 是视频通话, 0 是语音通话
      success: () => {
        openLocalCamera({isFront: true})
        openLocalMicrophone()
        uni.navigateTo({
          url: '/uni_modules/tuikit-atomic-x/pages/call?layoutTemplate=Float'
        })
      },
      fail: (error) => {
        console.log('calls fail:', error)
      }
    });
}

说明：
在 tuikit-atomic-x/server/callService 文件中进行了默认处理被叫端收到呼叫的逻辑，若您需要自定义，可以修改该文件中的 "onCallReceived" 事件对应的处理逻辑。

常见问题

调用接口没有反应？

请检查您是否制作了自定义基座并且使用自定义基座运行项目。

如何禁止系统侧滑返回上一个页面的行为？

iOS 端可以通过设置页面上的 disableSwipeBack 属性进行禁止。详情参考 uni-app 官方文档。
Android 端可以通过 onBackPress 拦截系统侧滑和物理返回，示例代码如下
注意：
使用该方式进行系统侧滑和物理返回的拦截的前提是该页面使用的是 自定义导航栏。
<script setup>
  import { onBackPress } from '@dcloudio/uni-app'

  // 拦截系统侧滑和物理返回键，防止通话中误退出
  onBackPress((option) => {
    if (option.from === 'backbutton') {
      return true; // 返回 true 阻止默认回退行为
    }
  });
</script>

交流与反馈

如果您在使用过程中，有什么建议或者意见，可以 联系我们，感谢您的反馈。
中国站