SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cometchat-react-v7-customization

cometchat-react-v7-customization

设计与创作

查看项目

更新于 10-21 20:32

技能介绍

用途

本技能用于对 CometChat React v7 UI Kit 进行主题与品牌定制，包括颜色、字体、明暗模式，以及按组件覆盖样式。它假定已掌握配套技能 cometchat-react-v7-core（安装、Provider、init→login→render）。

主要能力

  • 设计令牌：全部为 CSS 自定义属性，前缀 --cometchat-*，作用域限定在 .cometchat 包装元素内。
  • 明暗模式：内置 light（默认）与 dark，通过 CometChatProvider 的 theme 属性以及包装元素上的 data-theme 属性选择；可用 useTheme 钩子运行时切换。
  • 跟随系统主题：theme 属性仅接受 "light" | "dark"，默认 light，没有 theme="system"，套件也不读取 prefers-color-scheme。若需跟随系统，需自行将 theme 同步到 window.matchMedia("(prefers-color-scheme: dark)")（带 change 监听，并做 SSR 保护）。
  • 可替换内容：.cometchat 上的全局令牌（主色、字体、圆角、间距）；通过 [data-theme="..."] 做按主题覆盖；通过 BEM 类（如 .cometchat-conversations、.cometchat-message-list）做按组件作用域。
  • 结构定制：主题只改变外观（令牌）；改变渲染内容需使用视图插槽与组合。各列表/消息组件暴露视图插槽属性以注入自定义 UI，例如 Conversations 的 headerView / searchView、MessageHeader 的 trailingView / auxiliaryButtonView、MessageList 的 headerView / footerView、Composer 的 auxiliaryButtonView / headerView。自定义消息气泡属于独立能力（消息插件架构）。

使用方式

导入顺序：在 UI Kit 样式之后导入你的覆盖样式（UI Kit CSS 只在根导入一次）。

import { CometChatProvider, useTheme } from "@cometchat/chat-uikit-react";
import "./cometchat-overrides.css";   // AFTER the kit styles

<CometChatProvider theme="dark"><>{/* your chat UI */}</></CometChatProvider>

.cometchat { --cometchat-font-family: "Inter", sans-serif; }             /* theme-INDEPENDENT tokens only */
.cometchat[data-theme="light"] { --cometchat-primary-color: #e91e63; }   /* per-theme COLOURS → data-theme attr */
.cometchat[data-theme="dark"]  { --cometchat-primary-color: #bb86fc; }
.cometchat-message-list { /* BEM class to scope tokens per component */ }

按主题的颜色应写在 data-theme 元素上，而非裸 .cometchat 类。CometChatProvider 渲染单个包装 div（data-theme="light|dark" class="cometchat"），套件在 [data-theme=light] / [data-theme=dark] 上定义令牌。但部分组件会渲染自己的嵌套 div（无 data-theme），例如 CometChatSearch 以及弹出层/传送表面。因此写在裸 .cometchat 上的颜色也会落到该嵌套包装上，把基础（light）值重新固定在那里，导致暗色模式下搜索仍为亮色。应将按主题颜色限定到 .cometchat[data-theme="light"] / .cometchat[data-theme="dark"]，使嵌套包装两者都不匹配并继承 Provider 的主题。仅将主题无关令牌（字体、圆角）留在裸 .cometchat 上。若要按主题重新着色套件内部元素，使用套件自身模式：[data-theme="dark"] .cometchat-message-list { … }。

区分嵌套表面：绘制不透明背景的套件子表面不会继承包装背景，必须覆盖该表面自身的背景 CSS 变量（在祖先上限定作用域即可级联）。以线程面板为例，.cometchat-message-list 绘制 background: var(--cometchat-message-list-bg)（默认 var(--cometchat-background-color-03)），而 .cometchat-thread-header 与 .cometchat-message-composer 绘制各自不透明的 var(--cometchat-background-color-01)。因此线程消息列表渲染为 -03，与主列表同色，且与其自身头部/输入框不同，仅设置线程包装背景无法修复。应在线程包装上覆盖列表自身令牌：

.cc-thread-panel {
  --cometchat-message-list-bg: var(--cometchat-background-color-01); /* matches the thread header/composer; differs from the main list's -03 */
  border-left: 1px solid var(--cometchat-border-color-default, #e8e8e8); /* optional divider from the main pane (-default = neutral-300 = #e8e8e8 light / #383838 dark) */
}

--cometchat-background-color-01 为 #ffffff（light）/ #141414（dark），-03 为 #f5f5f5（light）/ #272727（dark），因此该覆盖在两种主题下都能明显区分线程列表与主列表，同时与线程头部/输入框一致。任何按表面背景都可用同样技巧：在包装上限定该表面自身令牌，切勿覆盖套件内部 .cometchat-* 元素类。

单独给线程头部着色：.cometchat-thread-header 绘制 background: var(--cometchat-thread-header-background, var(--cometchat-background-color-01, #fff))（该令牌未在 :root 定义，仅带该回退链引用）。若想让线程头部有独立色调，直接在线程包装上设置 --cometchat-thread-header-background：

.cc-thread-panel {
  --cometchat-message-list-bg: var(--cometchat-background-color-01);  /* REQUIRED — repaints the thread LIST (opaque, covers the wrapper) */
  --cometchat-thread-header-background: var(--cometchat-background-color-02);  /* OPTIONAL — tints ONLY the thread header, independent of the list */
}

--cometchat-message-list-bg 覆盖仍为必需，头部令牌只绘制头部，不影响不透明消息列表。仅当希望头部与列表色调不同时才使用 --cometchat-thread-header-background；若希望一致，头部已继承 -01，无需覆盖。

适用场景

  • 品牌化/主题化：颜色、字体、明暗模式或按组件样式覆盖。
  • 需要跟随系统明暗设置的全新集成（推荐作为默认做法）。
  • 需要区分线程面板等嵌套表面外观的场景。

限制与常见陷阱

  • 多次导入 UI Kit CSS，或在套件样式之前导入覆盖样式（丢失优先级）。
  • 在组件中硬编码十六进制颜色而非使用令牌。
  • 假设使用 v6 主题类——v7 使用 --cometchat-* 令牌 + data-theme。
  • 将按主题覆盖写成 [data-theme="dark"] .cometchat { … }——它不匹配任何元素并静默失效。Provider 将 data-theme 与 class="cometchat" 放在同一 div 上，不存在嵌套在 [data-theme] 祖先内的 .cometchat。品牌令牌用 .cometchat[data-theme="dark"]（同一元素），重新着色内部元素用 [data-theme="dark"] .cometchat-<bem>（祖先 + 套件内部后代）。
  • 将按主题令牌（颜色、背景、字体）放在裸 :root 上：其优先级低于套件自身的 .cometchat[data-theme] 令牌，要么失效（字体静默不生效），要么在暗色模式下强制使用亮色值。每个按主题令牌都应限定到 .cometchat[data-theme="light"] / .cometchat[data-theme="dark"]（圆角等主题无关令牌可留在裸 .cometchat）。主题化是本技能的职责，需手写限定作用域的 CSS，没有 CLI 代码生成。
  • 在包装上设置背景以区分嵌套表面并期望其显示：不透明子表面会覆盖包装背景。应覆盖该表面自身令牌，而非仅包装或其内部 .cometchat-* 类。
  • 假设套件跟随系统主题：它不跟随。theme 默认 light，没有 theme="system"，普通集成会忽略用户系统的暗色模式设置。

验证

确认主题 / --cometchat-* 覆盖在运行中的应用生效（颜色、明暗），且套件 CSS 在应用根只导入一次。

事实说明

精确令牌名称与默认值需从主题文档获取，本技能不内置令牌表。