cometchat-angular-v5-customization

用途

本技能用于定制 CometChat Angular UI Kit v5（已验证 5.1.0–5.2.0）的外观与文案，包括颜色、字体、明暗模式、语言、日期格式，以及替换某个区域的标记。它面向的是“改变界面看起来或读起来的样子”，而不是改变组件行为。

选择最小改动手段

技能建议按成本从低到高选择：

改颜色/间距：使用 CSS 变量，只需一个样式表。
明暗切换：使用 ThemeService，一行代码。
改语言：使用 CometChatLocalize 配置。
改日期格式：使用各组件对应的 *DateTimeFormat 输入，一个输入即可。
改某区域标记：使用 *View 插槽加 ng-template。
改行为：不属于定制范畴，应参考 features 或 components 技能。

优先使用能生效的最小手段。为改一个颜色而替换整个区域，会丢失选中状态、在线状态和已读回执。

CSS 变量

所有视觉元素都是 --cometchat-* 自定义属性。可在级联生效的位置覆盖，通常是 styles.css：

:root {
  --cometchat-primary-color: #6851D6;
  --cometchat-border-color-default: #DCDCDC;
  --cometchat-text-color-primary: #141414;
}

若只想作用于应用的一部分，可将变量设置在包裹元素而非 :root 上。完整令牌列表见 {DOCS_BASE}/ui-kit/angular/customization/theming.md。

注意：不要用后代选择器定位生成的类名，它们会在版本间变化；不要使用 !important，如果令牌未生效，通常是 kit 样式表未注册（angular.json → styles）或规则不在级联路径中。

明暗主题 — ThemeService

import { Component, inject } from '@angular/core';
import { ThemeService } from '@cometchat/chat-uikit-angular';

@Component({ selector: 'app-root', standalone: true, template: '<router-outlet />' })
export class AppComponent {
  constructor() { inject(ThemeService).initFromPreference(); }
}

该调用会遵循操作系统 prefers-color-scheme，通过 DOCUMENT 令牌将 data-theme 应用到 <html>（SSR 安全），并维护自己的 matchMedia 监听器，使 UI 实时跟随系统。

⚠️ 它不会持久化，尽管其文档字符串如此声称。经 5.1.0 实测：initFromPreference() 声称先读 localStorage，setTheme()/toggleTheme() 声称会持久化，但该类从未接触 localStorage——手动切换在刷新后会丢失。若用户需要刷新后仍保留的切换，应在服务外围添加持久化，而不是替换它；第二个 matchMedia 监听器会与 currentTheme() 产生偏差。

切换：themeService.toggleTheme()——不要自行计算下一个值。设置特定模式：themeService.setTheme('dark')。读取：themeService.currentTheme()——这是一个 signal，可直接在模板中使用。

与文档的差异：{DOCS_BASE}/ui-kit/angular/customization/theming.md 记录了 setTheme()、toggleTheme() 和手动设置 data-theme，但未提及 initFromPreference() 或跟随系统 prefers-color-scheme。initFromPreference() 是真实存在且经 5.1.0 验证的，优先使用它而非手写 matchMedia 监听器。不要因为指南未提及就“纠正”掉它；这是文档缺口，而非方法有误的证据。

不要手写 matchMedia('(prefers-color-scheme: dark)') 监听器。那是 React 的做法；React 的 kit 无法读取系统。Angular 的可以，重复实现会产生与 currentTheme() 偏差的状态。

本地化

CometChatLocalize 内置 19 种语言。在启动时设置一次语言；TranslatePipe 和 getLocalizedString() 会从中读取。若要覆盖个别字符串或添加语言，请查阅 {DOCS_BASE}/ui-kit/angular/customization/localization.md——覆盖结构因版本而异，值得阅读而非猜测。

日期与时间格式

使用各组件输入，而非全局 CSS：lastMessageDateTimeFormat（会话列表）、messageSentAtDateTimeFormat（搜索）、callInitiatedDateTimeFormat（通话记录）、lastActiveAtDateTimeFormat（消息头部）。管道 CalendarDatePipe、MessageDatePipe 和 ConversationDatePipe 已导出，若需在自己的标记中使用相同格式可直接使用。

全局配置

COMETCHAT_GLOBAL_CONFIG 是用于应用级 kit 默认值的注入令牌。优先使用它，而不是在每个组件实例上重复相同的输入。详情见 {DOCS_BASE}/ui-kit/angular/customization/global-config.md。

结构性更改

替换标记而非样式化属于视图插槽：itemView、titleView、subtitleView、leadingView、trailingView、headerView、emptyView、errorView、loadingView。参见 cometchat-angular-v5-components。覆盖能完成任务的最小插槽。

常见陷阱

手写系统主题检测——ThemeService.initFromPreference() 已实现。
为改颜色而替换 itemView——会丢失选中、在线状态和已读回执。
样式化生成的类名——下次 kit 发布就会失效。
!important 之争——样式表未注册，或规则不在级联中。
两个主题来源——ThemeService 加上自己的 data-theme 写入器，二者会偏差。

验证要点

品牌色在两种主题下均生效；暗色模式仅在自行持久化选择后才能刷新保留（kit 不会，见上文警告），否则刷新会回退到系统设置；首次加载遵循系统主题；本地化字符串正常渲染；被覆盖的区域仍保留点击、在线状态和已读回执功能。

技能介绍

用途