用途
本技能用于为 Angular 版 CometChat 应用添加语音和视频通话功能,也用于诊断“通话从不响铃”一类问题。
主要能力
- 安装并接入独立的通话 SDK:
npm install @cometchat/calls-sdk-javascript@^5。它是 UI Kit 的可选 peer 依赖(^5.0.3),默认不会安装;缺少它时通话组件处于惰性状态,CometChatUIKit.isCallingEnabled()返回 false。 - 在应用根组件挂载来电监听组件
<cometchat-incoming-call>,使其在任何路由下都能响铃。 - 使用消息头部默认渲染的语音/视频通话按钮,或通过
[hideVoiceCallButton]="true"/[hideVideoCallButton]="true"隐藏;也可在其它位置独立使用<cometchat-call-buttons>。 - 可选添加通话记录
<cometchat-call-logs>,以及使用CallLogsService进行无界面查询。 - 处理进行中与呼出通话:
<cometchat-ongoing-call>、<cometchat-outgoing-call>,由套件在通话被接受后驱动。
使用方式
- 安装通话 SDK(见上)。
- 在应用根组件挂载
<cometchat-incoming-call>,不要放在聊天页面内。 - 通话按钮由消息头部默认渲染,添加前先检查运行中的应用。
- 可选添加通话记录。
关键配置:仅安装包不会开启通话。在 initFromSettings 路径上,套件从 settings 对象推导通话开关:
const callingEnabled = !!settings.uiKit?.['callsSDK'];
if (callingEnabled) builder.setCallingEnabled(true);
因此必须声明 uiKit.callsSDK 配置块:
CometChatUIKit.initFromSettings({
appId, region,
credentials: { authKey },
chatSDK: { presenceSubscription: { type: 'ALL_USERS' } },
uiKit: { callsSDK: {} }, // ← initFromSettings 路径上开启通话所必需
});
若遗漏,<cometchat-call-buttons> 会渲染为零尺寸空元素,消息头部不显示通话按钮,且不报错、不输出日志。此时先检查 CometChatUIKit.isCallingEnabled() 是否返回 false。
文档中的 builder 路径使用 UIKitSettingsBuilder 上的 .setCallingEnabled(true),两种方式各自适用于对应的初始化路径,不要混用。
根组件示例:
import { Component, inject, computed } from '@angular/core';
import { CommonModule } from '@angular/common';
import {
ChatStateService,
CometChatCallButtonsComponent,
CometChatIncomingCallComponent,
CometChatUIKitCalls,
} from '@cometchat/chat-uikit-angular';
@Component({
selector: 'app-root',
standalone: true,
imports: [CommonModule, CometChatCallButtonsComponent, CometChatIncomingCallComponent],
template: `
<cometchat-incoming-call (callAccepted)="onAccepted($event)"></cometchat-incoming-call>
<cometchat-call-buttons [user]="activeUser()" [group]="activeGroup()"></cometchat-call-buttons>
`,
})
export class AppRootComponent {
private readonly chatState = inject(ChatStateService);
readonly activeUser = computed(() => this.chatState.activeUser() ?? undefined);
readonly activeGroup = computed(() => this.chatState.activeGroup() ?? undefined);
readonly calls = CometChatUIKitCalls;
onAccepted(_call: unknown) { /* route to your ongoing-call screen */ }
}
组件输出:
| 组件 | 输出 |
|---|---|
<cometchat-incoming-call> |
callAccepted callDeclined error |
<cometchat-outgoing-call> |
callCanceled error |
<cometchat-ongoing-call> |
callEnded error |
<cometchat-call-buttons> |
error |
<cometchat-call-logs> |
itemClick callButtonClicked |
<cometchat-call-bubble> |
buttonClick |
<cometchat-ongoing-call> 接收 [sessionID],可选 [callSettingsBuilder] / [isAudioOnly]。不要自行构建通话界面,WebRTC 状态、权限与清理由套件处理。
通话记录注意事项:<cometchat-call-logs> 若在 Calls SDK 加载前挂载会硬崩溃。其 ngOnInit 同步执行 new CometChatUIKitCalls.CallLogRequestBuilder(),而 CometChatUIKitCalls 在惰性加载的 Calls SDK 解析前为 null,导致渲染 “OOPS! / Retry” 错误状态并输出 [CometChatCallLogs] Error: TypeError: Cannot read properties of null (reading 'CallLogRequestBuilder'),重试无法恢复。需在挂载前同时等待 callingReady 并确认 CometChatUIKitCalls 非空:
import { CometChatUIKit, CometChatUIKitCalls } from '@cometchat/chat-uikit-angular';
readonly callsReady = signal(false);
constructor() {
CometChatUIKit.callingReady
.then(() => this.callsReady.set(!!CometChatUIKitCalls))
.catch(() => this.callsReady.set(false));
}
<cometchat-call-logs *ngIf="callsReady()" (itemClick)="openCall($event)"></cometchat-call-logs>
<div *ngIf="!callsReady()">Loading call history…</div>
isCallingEnabled() 是同步设置检查;callingReady 加 CometChatUIKitCalls 空值检查才是真正保护挂载的条件(仅 callingReady 不够)。
适用场景
- 为已有 Angular CometChat 应用增加语音/视频通话。
- 排查通话不响铃、通话按钮不显示等问题。
- 需要通话记录列表或详情视图。
限制与环境要求
- 需要 HTTPS 或 localhost;明文 HTTP 下
getUserMedia被阻止,局域网 IP 走 http 会失败。 - 麦克风/摄像头权限是用户手势提示,必须由点击触发,不能在加载时触发。
- 通话还需在控制台为应用启用,仅靠代码不够。
- 通话 UI 内置在
@cometchat/chat-uikit-angular@5,没有单独的通话 UI 包;WebRTC 引擎是独立且不打包的 peer 依赖。 - 两个通话组件必须加入使用方组件的
imports: [],否则不渲染、不响铃。 - 进行中通话界面需要真实尺寸的容器,不能是零高度。
- 常见陷阱:监听器放在聊天页面导致仅该路由响铃;
initFromSettings缺少uiKit.callsSDK导致通话静默关闭;未安装 Calls SDK 导致组件惰性且无报错;控制台未启用通话;明文 HTTP;重复通话按钮;自行构建通话界面丢失 WebRTC 清理。
验证方式
两个浏览器、两个用户、HTTPS 或 localhost:主叫看到呼出界面,被叫设备从任意路由响铃;接受后双向连接音频/视频;结束后双方回到聊天;通话出现在通话记录中;无控制台错误。