用途
该技能用于在 Angular 应用中添加 CometChat 聊天功能,覆盖从安装、凭据配置到初始化、登录和组件渲染的完整流程。它也是其他 Angular v5 系列技能所依赖的基础设置技能。
主要能力
- 检测 Angular 项目并完成依赖安装。
- 获取并验证 CometChat 仪表盘凭据(App ID、Region、Auth Key)。
- 按 init→login→render 的顺序完成初始化与登录。
- 提供组件与 API 映射表,说明导出类名与模板选择器的对应关系。
- 给出一个生产可用的核心界面示例,包含会话列表、消息头、消息列表和消息输入框。
安装
npm install @cometchat/chat-uikit-angular@^5 @cometchat/chat-sdk-javascript@^4 @cometchat/cards-angular@^1 dompurify@^3
仅通话功能(可选):
npm install @cometchat/calls-sdk-javascript@^5
注意:Angular 22 无法安装,因为该套件的 peer 范围为 @angular/core >=17.0.0 <22.0.0。可使用 npx -y @angular/cli@21 new <app> 创建新应用。Angular 17 可用但未在文档中说明。
三条关键规则
- 每个组件都必须写入 imports 数组。套件提供独立组件,若在模板中使用
<cometchat-conversations>却未导入 CometChatConversationsComponent,Angular 不会渲染任何内容,且无错误或警告。 - 配置位于 src/environments/environment.ts,而非 .env。Angular 在构建时通过文件替换解析。
- 类名、选择器与文档标题三者不同,需在正确位置使用正确名称。
angular.json 配置
需要在 projects.<app>.architect.build 下修改三处:样式表、图标资源与生产预算。
样式表中套件样式必须放在最前:
"styles": [
"node_modules/@cometchat/chat-uikit-angular/styles/css-variables.css",
"src/styles.css"
]
资源条目:
{ "glob": "**/*", "input": "node_modules/@cometchat/chat-uikit-angular/src/lib/assets", "output": "assets" }
生产预算需调高,否则 ng build 会失败。套件与 Chat SDK 约 4.2 MB,而默认错误预算为 1 MB。
不要通过 @import 引入套件的 css-variables.css,因为包的 exports map 未暴露该路径,会导致构建失败。
凭据设置
需要三个值:App ID、Region、Auth Key。配置示例:
// src/environments/environment.ts
export const environment = {
production: false,
cometchat: { appId: 'APP_ID', region: 'REGION', authKey: 'AUTH_KEY' },
};
还需向开发者询问登录 UID。cometchat-uid-1 是文档示例,不保证应用已存在该用户,缺失时登录失败且屏幕空白。若开发者没有 UID,可使用 create-if-missing 的 ensureDevUser()。
需创建 environment.prod.ts 并在 angular.json 中配置 fileReplacements。Auth Key 仅用于开发环境,生产环境由服务端生成 auth token 并调用 loginWithAuthToken。
集成顺序
init() 必须在 login() 之前完成,login() 必须在任何套件组件渲染之前完成。在 Angular 中通过 app initializer 实现,而非组件 effect。示例代码见技能正文,其中使用 initFromSettings 而非经典 builder init,并在 finally 中引导应用,确保初始化或登录失败时聊天功能降级而非整个应用空白。
组件与 API 映射
导出类与模板选择器对应关系:
- CometChatConversationsComponent →
<cometchat-conversations>(会话列表) - CometChatMessageHeaderComponent →
<cometchat-message-header>(当前聊天头部) - CometChatMessageListComponent →
<cometchat-message-list>(消息面板) - CometChatMessageComposerComponent →
<cometchat-message-composer>(输入框) - CometChatThreadHeaderComponent →
<cometchat-thread-header>(线程面板头部) - CometChatUsersComponent →
<cometchat-users>(用户目录) - CometChatGroupsComponent →
<cometchat-groups>(群组目录) - CometChatGroupMembersComponent →
<cometchat-group-members>(成员管理) - CometChatSearchComponent →
<cometchat-search>(搜索界面) - CometChatErrorBoundaryComponent →
<cometchat-error-boundary>(错误隔离) - CometChatIncomingCallComponent →
<cometchat-incoming-call>(应用根来电监听)
非组件导出包括:CometChatUIKit、UIKitSettingsBuilder、ChatStateService、CometChatUIKitConstants、CometChatLocalize、ThemeService。AI 助手相关导出不带 Component 后缀,如 CometChatAIAssistantChat。
核心界面示例
默认的“添加聊天”场景提供会话与消息功能。示例组件包含会话列表、消息头、消息列表和输入框,并处理用户与群组两种会话类型。需注意:itemClick 事件可能返回用户或群组,应使用两个槽位分别绑定;使用 | undefined 而非 | null,因为严格模板检查会拒绝 null。
样式方面,外壳必须有尺寸,否则列表会塌缩为 0px。每个套件列表组件都需要 .cc-fill(flex: 1; min-height: 0)。<cometchat-error-boundary> 没有 :host 规则,也需设置尺寸。还需设置 html、body 的高度与背景色,使套件主题生效。
适用场景
适用于需要在 Angular 应用中集成 CometChat 聊天功能的开发者,尤其是使用独立组件和 Angular 17 至 21 的项目。
限制
- Angular 22 无法安装,peer 范围限制为 >=17.0.0 <22.0.0。
- Angular 17 可用但未在文档中说明。
- 生产环境需服务端生成 auth token,Auth Key 仅用于开发。
- 登录 UID 需开发者提供,文档示例 UID 不保证存在。
- 部分行为未在文档中说明,需查阅已安装套件源码验证。
- 用户/群组/通话标签选择器、详情或线程侧面板、线程、搜索和通话功能属于扩展目标,除非明确要求,否则应省略。