@tencentcloud/sdk-mcp 1.6.4 → 1.6.6

package/resource/knowledge/callkit/preset/react/uikit-api-reference.md

@@ -0,0 +1,475 @@
+TUICallKit 是音视频通话组件的**含 UI 接口**，使用 TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景；更详细的接入步骤，详见：快速接入 TUICallKit。
+
+> **说明：**
+>
+
+> 为提供更优质的音视频通信能力， TUICallKit npm 包 [@trtc/calls-uikit-react](https://www.npmjs.com/package/@trtc/calls-uikit-react) 在 4.0.0 版本进行了重大升级。
+>
+
+## API 概览
+
+|<br>API|描述|
+|---------|---------|
+|[<TUICallKit />](https://cloud.tencent.com/document/product/647/81015#TUICallKit)|TUICallKit 通话 UI 组件。|
+|[init](https://cloud.tencent.com/document/product/647/81015#init)|初始化 TUICallKit 组件实例。|
+|[calls](https://cloud.tencent.com/document/product/647/81015#calls)|发起单人或多人通话。|
+|[join](https://cloud.tencent.com/document/product/647/81015#join)|主动加入通话。|
+|[setCallingBell](https://cloud.tencent.com/document/product/647/81015#setCallingBell)|设置自定义来电铃音。|
+|setLogLevel|设置日志级别。|
+|[setSelfInfo](https://cloud.tencent.com/document/product/647/81015#setSelfInfo)|设置用户昵称和头像。|
+|[enableMuteMode](https://cloud.tencent.com/document/product/647/81015#enableMuteMode)|开启/关闭来电铃声。|
+|[enableFloatWindow](https://cloud.tencent.com/document/product/647/81015#enableFloatWindow)|开启/关闭悬浮窗功能。|
+|[enableVirtualBackground](https://cloud.tencent.com/document/product/647/81015#enableVirtualBackground)|开启/关闭模糊背景的功能按钮。|
+|[setLanguage](https://cloud.tencent.com/document/product/647/81015#setLanguage)|设置 TUICallKit 组件通话语言。|
+|[hideFeatureButton](https://cloud.tencent.com/document/product/647/81015#hideFeatureButton)|隐藏按钮。|
+|[setLocalViewBackgroundImage](https://cloud.tencent.com/document/product/647/81015#setLocalViewBackgroundImage)|设置本地用户通话界面背景图。|
+|[setRemoteViewBackgroundImage](https://cloud.tencent.com/document/product/647/81015#setRemoteViewBackgroundImage)|设置远端用户通话界面背景图。|
+|[setLayoutMode](https://cloud.tencent.com/document/product/647/81015#setLayoutMode)|设置通话界面布局模式。|
+|[setCameraDefaultState](https://cloud.tencent.com/document/product/647/81015#setCameraDefaultState)|设置摄像头是否默认打开。|
+|[destroyed](https://cloud.tencent.com/document/product/647/81015#destroyed)|销毁 TUICallKit 组件实例。|
+|[getTUICallEngineInstance](https://cloud.tencent.com/document/product/647/81015#getTUICallEngineInstance)|获取 TUICallEngine 实例。|
+
+## <`TUICallKit />` 组件
+
+### 属性概览
+
+|属性|描述|类型|是否必填|默认值|支持 Vue|支持 React|
+|---------|---------|---------|---------|---------|---------|---------|
+|allowedMinimized|是否允许悬浮窗|boolean|否|false|<br>√<br>|√|
+|allowedFullScreen|是否允许通话界面全屏|boolean|否|true|√|√|
+|[videoDisplayMode](https://cloud.tencent.com/document/product/647/81015#videoDisplayMode)|通话界面显示模式|VideoDisplayMode|否|VideoDisplayMode.COVER|√|√|
+|[videoResolution](https://cloud.tencent.com/document/product/647/81015#videoResolution)|通话分辨率|VideoResolution|否|VideoResolution.RESOLUTION_720P|√|√|
+|beforeCalling|拨打电话前与收到通话邀请前会执行此函数|function(type, error)|否|-|√|√|
+|afterCalling|结束通话后会执行此函数|function()|否|-|√|√|
+|<br>onMinimized|组件切换最小化状态时会执行此函数，[STATUS 值说明](https://cloud.tencent.com/document/product/647/81015#STATUS)|function(oldStatus, newStatus)|否|-|√|√|
+|<br>kickedOut|组件抛出的事件，当前登录用户被踢出登录时会触发该事件，通话也会自动结束|function()|否|-|√|×|
+|<br>statusChanged|组件抛出的事件，当通话状态发生变化时，会触发该事件，通话状态种类详见，[STATUS 值说明](https://cloud.tencent.com/document/product/647/81015#STATUS)|function({oldStatus, newStatus})|否|-|√|×|
+
+### 示例代码
+
+【React】
+``` bash
+import { TUICallKit, VideoDisplayMode, VideoResolution } from "@trtc/calls-uikit-react";
+
+<TUICallKit
+    videoDisplayMode={VideoDisplayMode.CONTAIN}
+    videoResolution={VideoResolution.RESOLUTION_1080P}
+    beforeCalling={handleBeforeCalling}
+    afterCalling={handleAfterCalling}
+/>
+
+function handleBeforeCalling(type: string, error: any) {
+  console.log("[TUICallkit Demo] handleBeforeCalling:", type, error);
+}
+function handleAfterCalling() {
+  console.log("[TUICallkit Demo] handleAfterCalling");
+}
+```
+
+## TUICallKitAPI API 详情
+
+【React】
+``` javascript
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+```
+
+### init
+
+初始化 TUICallKit。
+``` javascript
+try {
+  await TUICallKitAPI.init({ SDKAppID, userID, userSig });
+  // If you already have a tim instance in your project, you need to pass it in here.
+  // await TUICallKitAPI.init({ tim, SDKAppID, userID, userSig});
+  console.log("[TUICallKit] init succeeds.");
+} catch (error: any) {
+  console.error(`[TUICallKit] init failed. Reason: ${error}`);
+}
+```
+
+参数如下表所示：
+| 参数 | 类型 | 是否必填 | 含义 |
+| --- | --- | --- | --- |
+| SDKAppID | Number | 是 | 应用的 SDKAppID，您可以在实时音视频控制台中找到您的 SDKAppID，具体详见：开通服务。 |
+| userID | String | 是 | 即用户名，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）。<br><strong>注意：</strong>不支持同一个 userID 在两台不同的设备上同时进入同一个房间通话，否则会相互干扰。 |
+| userSig | String | 是 | 使用 SecretKey 对 SDKAppID、UserID 等信息进行加密，就可以得到 userSig。<br>它是一个鉴权用的票据，用于腾讯云识别当前用户是否能够使用 TRTC 的服务，获取方式请参见 <a href="https://cloud.tencent.com/document/product/647/17275">UserSig</a>。 |
+| tim | TencentCloudChat | 否 | tim 是 <a href="https://www.npmjs.com/package/@tencentcloud/chat">TencentCloudChat</a> SDK 的实例。 |
+
+### calls
+
+发起单人或多人通话。
+``` javascript
+try {
+  await TUICallKitAPI.calls({
+    userIDList: ['jack', 'tom'],
+    type: CallMediaType.VIDEO_CALL
+  });
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
+}
+```
+
+参数如下表所示：
+| 参数 | 类型 | 是否必填 | 含义 |
+| --- | --- | --- | --- |
+| userIDList | Array<String> | 是 | 被呼叫的用户列表。 |
+| type | <a href="https://cloud.tencent.com/document/product/647/81015#TUICallType">CallMediaType</a> | 是 | 通话的媒体类型，参数值说明参见 <a href="https://cloud.tencent.com/document/product/647/81015#TUICallType">CallMediaType 通话类型</a>。<br>兼容旧版本：语音通话(type = 1)、视频通话(type = 2)。 |
+| chatGroupID | String | 是 | 与 Chat 结合使用时， Chat 群组的群 ID。 |
+| roomID | Number | 否 | 数字房间号，范围 [1, 2147483647]。 |
+| strRoomID | String | 否 | 字符串房间号。<strong>v3.3.1+ 支持</strong><br>1. roomID 与 strRoomID 是互斥的，若您选用 strRoomID，则 roomID 需要填写为 0。若两者都填，SDK 将优先选用 roomID。<br>2. 不要混用 roomID 和 strRoomID，因为它们之间是不互通的，例如数字 123 和字符串 "123" 是两个完全不同的房间。 |
+| timeout | Number | 否 | 通话超时时间，默认：30s，单位：秒。设置范围：10s ~ 600s。如果传入0，默认30s。 |
+| userData | String | 否 | 发起通话时自定义扩展字段，被呼叫用户在 ON_CALL_RECEIVED 事件中有该参数。 |
+| <a href="https://cloud.tencent.com/document/product/647/81015#offlinePushInfo">offlinePushInfo</a> | Object | 否 | 自定义离线消息推送参数。 |
+
+### join
+
+加入群组中已有的音视频通话。
+``` javascript
+try {
+  await TUICallKitAPI.join({callId: xx});
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call the join API. Reason: ${error}`);
+}
+```
+
+参数列表：
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|callId|String|是|此次通话的唯一 ID。|
+
+### setLanguage
+
+设置语言，目前支持：中文、英文、日文。
+``` javascript
+TUICallKitAPI.setLanguage("zh-cn"); // "en" | "zh-cn" | "ja_JP"
+```
+
+参数如下表所示：
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|lang|String|是|语言类型`en`、`zh-cn` 和 `ja_JP`。|
+
+### setSelfInfo
+
+设置当前用户昵称和头像。
+
+> **注意：**
+>
+
+> **通话中使用该接口修改用户信息，UI 不会立即更新，需要等到下次通话才能看到变化**。
+>
+
+``` javascript
+try {
+  await TUICallKitAPI.setSelfInfo({ nickName: "xxx", avatar: "http://xxx" });
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`;
+}
+```
+
+参数如下表所示：
+
+|**参数**|**类型**|**是否必填**|**含义**|
+|---------|---------|---------|---------|
+|nickName|String|是|自己的昵称。|
+|avatar|String|是|自己头像地址。|
+
+### setCallingBell
+- 自定义用户的来电铃音。
+
+- 仅限传入本地 MP3 格式的文件地址，需要确保该文件目录是应用可以访问的。
+
+- 使用 import 方式引入铃声文件。
+
+- 如需恢复默认铃声，`filePath` 传空即可。
+
+   ``` javascript
+   try {
+     await TUICallKitAPI.setCallingBell(filePath?: string)
+   } catch (error: any) {
+     console.error(`[TUICallKit] Failed to call the setCallingBell API. Reason: ${error}`);
+   }
+   ```
+
+   参数如下表所示：
+
+   |参数|类型|是否必填|含义|
+   |---------|---------|---------|---------|
+   |filePath|String|是|铃声文件地址。|
+
+### setLogLevel
+
+设置日志级别，低于 level 的日志将不会输出。
+``` javascript
+TUICallKitAPI.setLogLevel(level)
+```
+
+参数如下表所示：
+| 参数 | 值 | 含义 |
+| --- | --- | --- |
+| level | 0 | 普通级别，日志量较多，接入时建议使用。 |
+| 1 | release 级别，SDK 输出关键信息，生产环境时建议使用。 |  |
+| 2 | 告警级别，SDK 只输出告警和错误级别的日志。 |  |
+| 3 | 错误级别，SDK 只输出错误级别的日志。 |  |
+| 4 | 无日志级别，SDK 将不打印任何日志。 |  |
+
+### enableFloatWindow
+
+开启/关闭悬浮窗功能。默认为 false，通话界面左上角的悬浮窗按钮隐藏，设置为 true 后显示。
+``` javascript
+try {
+  await TUICallKitAPI.enableFloatWindow(enable: Boolean)
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call the enableFloatWindow API. Reason: ${error}`);
+}
+```
+
+### enableMuteMode
+
+开启/关闭来电铃声。
+
+默认为`false`，开启后，收到通话请求，不会播放来电铃声。
+``` javascript
+try {
+  await TUICallKitAPI.enableMuteMode(enable: boolean)
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
+}
+```
+
+参数如下表所示：
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|enable|Boolean|是|开启/关闭来电铃声。默认 false。|
+
+### enableVirtualBackground
+
+开启/关闭模糊背景功能。如果想设置图片背景模糊参见 [Web](https://cloud.tencent.com/document/product/647/106071)。通过调用接口，您可以在 UI 上显示模糊背景的功能按钮，点击按钮可直接启用模糊背景功能。
+``` javascript
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+const enable = true;
+TUICallKitAPI.enableVirtualBackground(enable);
+```
+
+参数列表：
+| 参数 | 类型 | 是否必填 | 含义 |
+| --- | --- | --- | --- |
+| enable | boolean | 是 | - enable = true 显示模糊背景按钮。<br>- enable = false 不显示模糊背景按钮。 |
+
+### destroyed
+
+销毁 TUICallKit 实例。
+
+该方法不会自动退出`tim`，需要手动退出`tim.logout();`。
+``` javascript
+try {
+  await TUICallKitAPI.destroyed();
+} catch (error: any) {
+  alert(`[TUICallKit] Failed to call the destroyed API. Reason: ${error}`);
+}
+```
+
+### hideFeatureButton
+
+隐藏功能按钮，目前仅支持 摄像头，麦克风和切换前后置按钮。
+
+【React】
+``` javascript
+import { TUICallKitAPI, FeatureButton } from "@trtc/calls-uikit-react";
+
+TUICallKitAPI.hideFeatureButton(FeatureButton.Camera);
+```
+
+参数列表：
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|buttonName|[FeatureButton](https://cloud.tencent.com/document/product/647/81015#FeatureButton)|是|按钮名称。|
+
+### setLocalViewBackgroundImage
+
+设置本地用户通话背景。
+``` typescript
+TUICallKitAPI.setLocalViewBackgroundImage('http://xxx.png');
+```
+
+参数列表：
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|url|String|是|图片地址（支持本地路径和网络地址）。|
+
+### setRemoteViewBackgroundImage
+
+设置远端用户通话背景。
+``` javascript
+const userId = 'xxx';
+const url = 'http://xxx.png';
+TUICallKitAPI.setRemoteViewBackgroundImage(userId, url);
+```
+
+参数列表：
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|userId|String|是|远端用户 userId，设置为 '*' 表示对所有远端用户生效。|
+|url|String|是|图片地址（支持本地路径和网络地址）。|
+
+### setLayoutMode
+
+设置通话界面布局模式。
+
+【React】
+``` javascript
+import { TUICallKitAPI, LayoutMode } from "@trtc/calls-uikit-react";
+TUICallKitAPI.setLayoutMode(LayoutMode.LocalInLargeView);
+```
+
+参数列表：
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|layoutMode|[LayoutMode](https://cloud.tencent.com/document/product/647/81015#LayoutMode)|是|用户流的布局模式。|
+
+### setCameraDefaultState
+
+设置摄像头是否默认打开。
+``` javascript
+TUICallKitAPI.setCameraDefaultState(true);
+```
+
+参数列表：
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|isOpen|boolean|是|是否开启摄像头。|
+
+### getTUICallEngineInstance
+
+获取 TUICallEngine 实例。
+``` javascript
+TUICallKitAPI.getTUICallEngineInstance();
+```
+
+## TUICallKit 类型定义
+
+### videoDisplayMode
+
+画面显示模式 `videoDisplayMode` 属性有三个值：
+- `VideoDisplayMode.CONTAIN`
+
+- `VideoDisplayMode.COVER`
+
+- `VideoDisplayMode.FILL`，默认值是`VideoDisplayMode.COVER`。
+
+| 属性 | 值 | 描述 |
+| --- | --- | --- |
+| videoDisplayMode | VideoDisplayMode.CONTAIN | - 优先保证视频内容全部显示。<br>- 视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。<br>- 如果视频尺寸与显示视窗尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满视窗，缩放后的视频四周会有一圈黑边。 |
+| VideoDisplayMode.COVER | - 优先保证视窗被填满。<br>- 视频尺寸等比缩放，直至整个视窗被视频填满。<br>- 如果视频长宽与显示窗口不同，则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。 |  |
+| VideoDisplayMode.FILL | - 保证视窗被填满的同时保证视频内容全部显示，但是不保证视频尺寸比例不变。<br>- 视频的宽高会被拉伸至和视窗尺寸一致。 |  |
+
+### videoResolution
+
+分辨率 `videoResolution` 有三个值：
+- `VideoResolution.RESOLUTION_360P`，**V4.5.1+ 支持**。
+
+- `VideoResolution.RESOLUTION_540P`，**V4.5.1+ 支持**。原来 `VideoResolution.RESOLUTION_480P`不再支持。
+
+- `VideoResolution.RESOLUTION_720P`，默认值是`VideoResolution.RESOLUTION_720P`。
+
+- `VideoResolution.RESOLUTION_1080P`
+
+   **分辨率说明：**
+
+   |视频 Profile|分辨率（宽 × 高）|帧率（fps）|码率（kbps）|
+   |---------|---------|---------|---------|
+   |360p|640*360|15|800|
+   |540p|960 × 540|15|900|
+   |720p|1280 × 720|15|1500|
+   |1080p|1920 × 1080|15|2000|
+
+   **常见问题：**
+
+- iOS 13&14不支持编码高于 720p 的视频，建议在这两个系统版本限制最高采集 720P。参见 [iOS Safari 已知问题 case 12](https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-02-info-webrtc-issues.html#h2-4)。
+
+- 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|正在群组视频通话。|
+
+### **CallMediaType**
+
+|CallMediaType 类型|描述|
+|---------|---------|
+|CallMediaType.AUDIO|语音通话。|
+|CallMediaType.VIDEO|视频通话。|
+
+### **offlinePushInfo**
+
+|参数|类型|是否必填|含义|
+|---------|---------|---------|---------|
+|offlinePushInfo.title|String|否|离线推送标题（选填）|
+|offlinePushInfo.description|String|否|离线推送内容（选填）|
+|offlinePushInfo.androidOPPOChannelID|String|否|离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID（选填）|
+|offlinePushInfo.extension|String|否|离线推送透传内容，可以用于设置 Android [Notification 模式](https://cloud.tencent.com/document/product/647/81015#Android Notification) 和 [VoIP 模式](https://cloud.tencent.com/document/product/647/81015#Android VoIP)。**默认：**Notification 模式，会是系统的通知；VoIP 模式是需要传字段。|
+|offlinePushInfo.ignoreIOSBadge|Boolean|否|离线推送忽略 badge 计数（仅对 iOS 生效）， 如果设置为 true，在 iOS 接收端，这条消息不会使 App 的应用图标未读计数增加。|
+|offlinePushInfo.iOSSound|String|否|离线推送声音设置（仅对 iOS 生效）。|
+|offlinePushInfo.androidSound|String|否|离线推送声音设置（仅对 Android 生效）。|
+|offlinePushInfo.androidVIVOClassification|Number|否|VIVO 推送消息分类。|
+|offlinePushInfo.androidXiaoMiChannelID|String|否|小米手机 8.0 系统及以上的渠道 ID。|
+|offlinePushInfo.androidFCMChannelID|String|否|FCM 通道手机 8.0 系统及以上的渠道 ID。|
+|offlinePushInfo.androidHuaWeiCategory|String|否|华为推送消息分类。|
+|offlinePushInfo.isDisablePush|Boolean|否|是否关闭推送（默认开启推送）。|
+|offlinePushInfo.iOSPushType|Number|否|iOS 离线推送类型。0-普通推送；1-VoIP推送。默认：0。|
+
+#### Android Notification 模式
+``` javascript
+const extension = {
+  timPushFeatures: {
+    fcmPushType: 0, // 0, VoIP; 1, notification
+  }
+};
+offlinePushInfo.extension = JSON.stringify(extension);
+```
+
+#### Android VoIP 模式
+``` javascript
+const extension = {
+  timPushFeatures: {
+    fcmPushType: 0, // 0, data; 1, notification
+    fcmNotificationType: 1, // 0, TIMPush implementation； 1, business implementation after transparent transmission
+  }
+};
+offlinePushInfo.extension = JSON.stringify(extension);
+```
+
+### FeatureButton
+
+|FeatureButton 类型|描述|
+|---------|---------|
+|FeatureButton.Camera|摄像头按钮。|
+|FeatureButton.Microphone|麦克风按钮。|
+|FeatureButton.SwitchCamera|切换前后置摄像头按钮。|
+|FeatureButton.InviteUser|邀请他人按钮。|
+
+### LayoutMode
+
+|LayoutMode 类型|描述|
+|---------|---------|
+|LayoutMode.LocalInLargeView|本地用户在大窗显示。|
+|LayoutMode.RemoteInLargeView|远端用户在大窗显示。|