API 简介
TUICallKit API 是音视频通话组件的含 UI 接口,使用 TUICallKit API,您可以通过简单接口快速实现一个类微信的音视频通话场景,更详细的接入步骤,详见:快速接入 TUICallKit。
API 概览
<TUICallKit />
: TUICallKit UI 通话组件主体。<TUICallKitMini/>
:TUICallKit UI 通话悬浮窗,当 <TUICallKit :allowedMinimized="true"/>
时,<TUICallKitMini/>
必须被放置在页面中。注意:
<TUICallKitMini/>
UI 通话悬浮窗,≥v2.3.2 废弃,不再提供该组件。由
<TUICallKit />
UI 通话组件主体,实现悬浮窗样式,减少使用复杂度。
TUICallKitServer
: TUICallKit 通话实例,成员函数:init 初始化 TUICallKit 实例
call 发起 1v1 通话
groupCall 发起群组通话
setLanguage 修改 TUICallKit 组件语言
setSelfInfo 设置当前用户的昵称和头像
setCallingBell 自定义用户来电铃声
destroyed 销毁 TUICallKit 实例
TUICallKit
属性介绍
属性概览
属性 | 描述 | 类型 | 是否必填 | 默认值 |
allowedMinimized | 是否允许通话界面最小化 | boolean | 否 | false |
allowedFullScreen | 是否允许通话界面全屏 | boolean | 否 | true |
通话界面显示模式 | VideoDisplayMode | 否 | VideoDisplayMode.COVER | |
通话分辨率 | VideoResolution | 否 | VideoResolution.RESOLUTION_480P | |
beforeCalling | 拨打电话前与收到通话邀请前会执行此函数 | function(type, error) | 否 | - |
afterCalling | 结束通话后会执行此函数 | function() | 否 | - |
onMinimized | function(oldStatus, newStatus) | 否 | - | |
kickedOut | 注意:≥v2.3.2 支持 组件抛出的事件,当前登录用户被踢出登录时会触发该事件,通话也会自动结束 | function() | 否 | - |
statusChanged | 注意:≥v2.3.2 支持 | function({oldStatus, newStatus}) | 否 | - |
@kicked-out | 注意:≥v2.3.2 废弃 组件抛出的事件,当前登录用户被踢出登录时会触发该事件,通话也会自动结束 | function() | 否 | - |
@status-changed | 注意:≥v2.3.2 废弃 | function({oldStatus, newStatus}) | 否 | - |
示例代码
<template><TUICallKit:allowedMinimized="true":allowedFullScreen="true":videoDisplayMode="VideoDisplayMode.CONTAIN":videoResolution="VideoResolution.RESOLUTION_1080P":beforeCalling="beforeCalling":afterCalling="afterCalling":onMinimized="onMinimized":kickedOut="handleKickedOut":statusChanged="handleStatusChanged"/></template><script lang="ts" setup>import { TUICallKit, TUICallKitServer, VideoDisplayMode, VideoResolution, STATUS } from "@tencentcloud/call-uikit-vue"; // vue2 要换成 '@tencentcloud/call-uikit-vue2'function beforeCalling(type: string, error: any) {console.log("[Callkit Demo] beforeCalling:", type, error);}function afterCalling() {console.log("[Callkit Demo] afterCalling");}function onMinimized(oldStatus: string, newStatus: string) {console.log("[Callkit Demo] onMinimized: " + oldStatus + " -> " + newStatus);}function kickedOut() {console.log("[Callkit Demo] kickedOut");}function statusChanged(args: { oldStatus: string; newStatus: string; }) {const { oldStatus, newStatus } = args;if (newStatus === STATUS.CALLING_C2C_VIDEO) {console.log(`[Callkit Demo] statusChanged: ${oldStatus} -> ${newStatus}`);}}</script>
TUICallKitServer API 详情
init
初始化 TUICallKit,必须在 call, groupCall 之前进行。
try {await TUICallKitServer.init({ SDKAppID, userID, userSig });// await TUICallKitServer.init({ tim, SDKAppID, userID, userSig}); // 如果工程中已有 tim 实例,需在此处传入alert("[TUICallKit] Initialization succeeds.");} catch (error: any) {alert(`[TUICallKit] Initialization failed. Reason: ${error}`);}
参数如下表所示:
参数 | 类型 | 是否必填 | 含义 |
SDKAppID | Number | 是 | 云通信应用的 SDKAppID |
userID | String | 是 | 当前用户的 ID,字符串类型,只允许包含英文字母(a-z 和 A-Z)、数字(0-9)、连词符(-)和下划线(_) |
userSig | String | 是 | |
tim | Any | 否 | tim 参数适用于业务中已存在 TIM 实例,为保证 TIM 实例唯一性 |
call
拨打 1v1 通话。
try {await TUICallKitServer.call({userID: callUserID,type: TUICallType.VIDEO_CALL});} catch (error: any) {alert(`[TUICallKit] Call failed. Reason: ${error}`);}
参数如下表所示:
参数 | 类型 | 是否必填 | 含义 |
userID | String | 是 | 目标用户的 userId |
type | 是 | 兼容旧版本:语音通话(type = 1)、视频通话(type = 2)。 | |
timeout | Number | 否 | 通话的超时时间,0 为不超时, 单位 s(秒)(选填) - 默认 30s |
Object | 否 | 自定义离线消息推送(选填)-- 需 tsignaling 版本 >= 0.8.0 |
groupCall
发起群组通话。
try {await TUICallKitServer.groupCall({userIDList: ['jack', 'tom'],groupID: "xxx",type: TUICallType.VIDEO_CALL});} catch (error: any) {alert(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);}
参数如下表所示:
参数 | 类型 | 是否必填 | 含义 |
userIDList | Array<String> | 是 | 邀请列表成员列表 |
type | 是 | 兼容旧版本:语音通话(type = 1)、视频通话(type = 2) | |
groupID | String | 是 | |
timeout | Number | 否 | 通话的超时时间,0 为不超时, 单位 s(秒)(选填) - 默认 30s |
Object | 否 | 自定义离线消息推送(选填)(tsignaling 版本 >= 0.8.0) |
setLanguage
设置 TUICallKit 组件通话语言。
默认语言为浏览器的语言。
TUICallKitServer.setLanguage("zh-cn"); // "en" | "zh-cn"
参数如下表所示:
参数 | 类型 | 是否必填 | 含义 |
lang | String | 是 | 语言类型 en 或 zh-cn |
setSelfInfo
注意:≥v2.2.0 支持
设置当前用户昵称和头像。
try {await TUICallKitServer.setSelfInfo({ nickName: "xxx", avatar: "http://xxx" });} catch (error: any) {alert(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`);}
参数如下表所示:
参数 | 类型 | 是否必填 | 含义 |
nickName | String | 是 | 用户昵称 |
avatar | String | 是 | 用户头像地址 |
setCallingBell
注意:≥v3.0.0 支持
自定义用户的来电铃音。
仅限传入本地 MP3 格式的文件地址,需要确保该文件目录是应用可以访问的。
铃声媒体文件必须放在
public
目录下引入。try {await TUICallKitServer.setCallingBell(filePath?: string)} catch (error: any) {alert(`[TUICallKit] Failed to call the setCallingBell API. Reason: ${error}`);}
destroyed
销毁 TUICallKit 实例。
该方法不会自动退出
tim
,需要手动退出 tim.logout();
。try {await TUICallKitServer.destroyed();} catch (error: any) {alert(`[TUICallKit] Failed to call the destroyed API. Reason: ${error}`);
TUICallKit 类型定义
videoDisplayMode
画面显示模式
videoDisplayMode
属性有三个值:VideoDisplayMode.CONTAIN
VideoDisplayMode.COVER
VideoDisplayMode.FILL
,默认值是 VideoDisplayMode.COVER
。属性 | 值 | 描述 |
videoDisplayMode | VideoDisplayMode.CONTAIN | 优先保证视频内容全部显示。 视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。 如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。 |
| VideoDisplayMode.COVER | 优先保证视窗被填满。 视频尺寸等比缩放,直至整个视窗被视频填满。 如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。 |
| VideoDisplayMode.FILL | 保证视窗被填满的同时保证视频内容全部显示,但是不保证视频尺寸比例不变。 视频的宽高会被拉伸至和视窗尺寸一致。 |
videoResolution
分辨率
videoResolution
有三个值:VideoResolution.RESOLUTION_480P
VideoResolution.RESOLUTION_720P
VideoResolution.RESOLUTION_1080P
,默认值是 VideoResolution.RESOLUTION_480P
。分辨率说明:
视频 Profile | 分辨率(宽 × 高) | 帧率(fps) | 码率(kbps) |
480p | 640 × 480 | 15 | 900 |
720p | 1280 × 720 | 15 | 1500 |
1080p | 1920 × 1080 | 15 | 2000 |
常见问题:
iOS 13&14不支持编码高于 720P 的视频,建议在这两个系统版本限制最高采集 720P。参考 iOS Safari 已知问题 case 12。
Firefox 不支持自定义视频帧率(默认为 30fps)。
受系统性能占用,摄像头采集能力和浏览器限制等因素的影响,视频分辨率、帧率、码率的实际值不一定能够完全匹配设定值,在这种情况下,浏览器会自动调整 Profile 尽可能匹配设定值。
STATUS
属性值 | 描述 |
STATUS.IDLE | 闲置状态 |
STATUS.BE_INVITED | 收到通话邀请 |
STATUS.DIALING_C2C | 正在 1v1 呼叫 |
STATUS.DIALING_GROUP | 正在群组呼叫 |
STATUS.CALLING_C2C_AUDIO | 正在 1v1 语音通话 |
STATUS.CALLING_C2C_VIDEO | 正在 1v1 视频通话 |
STATUS.CALLING_GROUP_AUDIO | 正在群组语音通话 |
STATUS.CALLING_GROUP_VIDEO | 正在群组视频通话 |
TUICallType
TUICallType 类型 | 描述 |
TUICallType.AUDIO_CALL | 语音通话 |
TUICallType.VIDEO_CALL | 视频通话 |
offlinePushInfo
参数 | 类型 | 是否必填 | 含义 |
offlinePushInfo.title | String | 否 | 离线推送标题(选填) |
offlinePushInfo.description | String | 否 | 离线推送内容(选填) |
offlinePushInfo.androidOPPOChannelID | String | 否 | 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID(选填) |
offlinePushInfo.extension | String | 否 | 离线推送透传内容(选填)(tsignaling 版本 >= 0.9.0) |