SuperAPI AI 工具集

cometchat-angular-v5-calls

编程与开发

查看项目

更新于 10-21 20:28

技能介绍

用途

本技能用于为 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>,由套件在通话被接受后驱动。

使用方式

  1. 安装通话 SDK(见上)。
  2. 在应用根组件挂载 <cometchat-incoming-call>,不要放在聊天页面内。
  3. 通话按钮由消息头部默认渲染,添加前先检查运行中的应用。
  4. 可选添加通话记录。

关键配置:仅安装包不会开启通话。在 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:主叫看到呼出界面,被叫设备从任意路由响铃;接受后双向连接音频/视频;结束后双方回到聊天;通话出现在通话记录中;无控制台错误。