主题
通过覆盖 CSS 变量调整聊天组件的品牌色、圆角和深色模式。
主题
聊天组件没有 theme 属性。颜色来自 SDK 样式表(@openmaxai/chat-sdk/styles.css)里的 CSS 变量,在自己的 CSS 里改:常见的改法设主题输入变量(--omx-*),它们管不到的,才在 .omx-chat 上覆盖内部变量。

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): theming-custom-colors.tsx
"use client";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { type CSSProperties, useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
// The chat reads the CSS variables of @openmaxai/chat-sdk/styles.css. Override them on any wrapper element.
const THEMES = {
default: {},
violet: {
"--primary": "oklch(0.55 0.22 293)",
"--primary-foreground": "oklch(0.98 0 0)",
"--ring": "oklch(0.55 0.22 293)",
"--radius": "1rem",
},
green: {
"--primary": "oklch(0.55 0.15 155)",
"--primary-foreground": "oklch(0.98 0 0)",
"--ring": "oklch(0.55 0.15 155)",
"--radius": "0.25rem",
},
} as const;
type ThemeName = keyof typeof THEMES;
export default function ThemingDemo() {
const host = useDemoHost();
const { conversations } = useDemoData();
const [theme, setTheme] = useState<ThemeName>("violet");
return (
<ChatHostProvider host={host}>
<div
className="flex h-full flex-col bg-background text-foreground"
style={THEMES[theme] as CSSProperties}
>
<div className="flex gap-2 border-b p-2 text-xs">
{(Object.keys(THEMES) as ThemeName[]).map((name) => (
<button
key={name}
type="button"
onClick={() => setTheme(name)}
className={`rounded-md border px-2 py-1 ${
theme === name ? "bg-primary text-primary-foreground" : ""
}`}
>
{name}
</button>
))}
</div>
<MessageThread conversation={conversations[1]} />
</div>
</ChatHostProvider>
);
}
样式表引入与 ChatRoot 见安装。样式表把变量声明在每个 .omx-chat 节点上:SDK 组件在 ChatRoot 里各自带的组件根、ChatRoot 的弹出层落点,以及浮出面渲染进去的那个节点。
主题输入变量
实验性。样式表读一小组公开变量,自己从不声明它们。把它们设在聊天区和渲染在它外面的一切(overlayContainer 的节点、浮出面的 container)的共同祖先上,通常是 :root。自定义属性会继承,所以 ChatRoot 和 ChatShadowRoot 下聊天的每一处都拿得到这个值,Shadow DOM 里也一样;不用写 .omx-chat 选择器,也不看加载先后:
src/globals.css
:root {
--omx-primary: #7c3aed;
--omx-radius: 8px;
--omx-font-sans: "Inter", system-ui, sans-serif;
}
这份名单也从 @openmaxai/chat-sdk 导出为 CHAT_THEME_VARIABLES。不设时各自取下表的默认值,聊天和原来一模一样。
| 变量 | 浅色默认 | 深色默认 | 改的是什么 |
|---|---|---|---|
--omx-primary |
#21b1ff |
#21b1ff |
品牌色:自己的气泡、按钮、选中态。焦点环跟着它 |
--omx-primary-foreground |
oklch(0.985 0 0) |
oklch(0.985 0 0) |
品牌色上的文字 |
--omx-background |
oklch(1 0 0) |
oklch(0.145 0 0) |
底色。卡片(面板、气泡)和弹层(菜单)的底色跟着它 |
--omx-foreground |
oklch(0.145 0 0) |
oklch(0.985 0 0) |
正文,以及卡片和弹层上的文字 |
--omx-secondary |
oklch(0.97 0 0) |
oklch(0.269 0 0) |
次级按钮。菜单项悬停底色跟着它 |
--omx-secondary-foreground |
oklch(0.205 0 0) |
oklch(0.985 0 0) |
次级按钮和悬停菜单项上的文字 |
--omx-muted |
oklch(0.97 0 0) |
oklch(0.269 0 0) |
弱化的底色 |
--omx-muted-foreground |
oklch(0.556 0 0) |
oklch(0.708 0 0) |
弱化的文字(时间、提示) |
--omx-border |
#eceef2 |
oklch(1 0 0 / 10%) |
边框。输入框边框跟着它 |
--omx-radius |
calc(0.625 * var(--omx-rem, 16.8px)) |
同浅色 | 基础圆角;rounded-sm … rounded-4xl 按它缩放 |
--omx-font-sans |
系统无衬线字体栈 | 同浅色 | 正文字体 |
尺寸里讲的尺寸基准 --omx-rem 是同样的用法,不在这份名单里。
「跟着它」的意思:这些地方没有自己的变量,取你设的值。默认时其中几处略有不同(深色下卡片和弹层比底色亮一档,输入框边框和焦点环是各自的灰);一旦设了变量,它们都用你的值。
浅色与深色。 设了的变量两种配色都用。深色要用别的值,就在你自己的浅色、深色作用域里各设一份,并和传给聊天的 colorScheme 保持一致:
:root {
--omx-background: #fafafa;
}
:root[data-theme="dark"] {
--omx-background: #18181b;
}
只在浅色作用域里设了某个变量时,深色下聊天对它用 SDK 的深色默认值。
--omx-radius 的长度写成 px 或 calc(N * var(--omx-rem, 16.8px)):这里写的 rem 跟着你的根字号走,不跟聊天的 --omx-rem。--omx-primary 改不到每一处品牌蓝:换品牌色里列的那几处还没有输入变量。
样式表自己声明的无前缀变量(--primary、--card 以及变量参考里的其余变量)是内部的:名字、值、哪些读输入变量,任何版本都可能改。
换品牌色
只换品牌色本身,用上面的 --omx-primary 就够了。有几处细节的品牌色写在各自的变量里,没有输入变量管得到;要改它们,就在 import 之后、在 .omx-chat 上覆盖内部变量(这些名字不保证,见上;用 ChatShadowRoot 时页面 CSS 选不中 .omx-chat):
src/globals.css
@import "@openmaxai/chat-sdk/styles.css";
.omx-chat,
.omx-chat.omx-dark {
--primary: #7c3aed;
--primary-ink: #6d28d9; /* 品牌色小字,对比度保持在 4.5:1 以上 */
--coco-cyan-10: rgb(124 58 237 / 0.1); /* 名字旁 Agent 小标签的底色 */
--radius: calc(0.75 * var(--omx-rem, 16.8px));
}
.omx-chat.omx-dark {
--primary-ink: #a78bfa;
}
--primary-hover、--badge-channel-fg、--badge-agent-fg 由 --primary 推导,自动跟随。
下面这些变量的默认值也带品牌色,但它们是独立的值,不跟随 --primary,要一起改:
--primary-ink、--coco-cyan-10:上例已改。不改的话,名字旁 Agent 小标签和头部选中按钮还是默认蓝色。--badge-channel-bg、--badge-agent-bg:「频道」徽标和 Agent 徽标的底色,默认是品牌蓝和青色的浅底。只改了--primary时,徽标的字换了颜色、底色没换。--panel-gradient、--panel-bar-bg:会话列表面板顶部的渐变和会话头部的底色,默认是品牌蓝的浅色。--coco-blue-l1-30:会话列表搜索框的底色,默认是品牌蓝的浅色。
这些内部变量设在 .omx-chat 上,不要设在 :root 或你自己的外层容器上(与上面的输入变量相反):样式表在每个 .omx-chat 节点上都声明了它们,祖先上的值到那里就被换掉了。写在 .omx-chat 上的规则,各组件、菜单、对话框和浮窗都拿得到。.omx-chat.omx-dark 也要一起列上,否则深色时样式表在这个选择器下声明的深色值会赢。
以上针对 ChatRoot。在 ChatShadowRoot 里,你页面上的规则到不了 .omx-chat,见 Shadow DOM 下的宿主元素。
深色模式
给 ChatRoot 传 colorScheme:
<ChatRoot colorScheme={prefersDark ? "dark" : "light"}>{/* … */}</ChatRoot>
ChatRoot 给里面各组件的组件根、它的弹出层落点和浮出面渲染进去的那个节点都加上 omx-dark,样式表的深色变量写在 .omx-chat.omx-dark 下。<html> 或其他祖先上的 dark 类不影响聊天区。聊天不会自己跟随 prefers-color-scheme,何时切换由页面决定。
用 ChatShadowRoot 时同样传 colorScheme:它给 shadow root 里的作用域根、它的落点节点和每个岛都加上 omx-dark。页面上的 html.dark 这类选择器根本进不了 shadow root,所以 colorScheme 是唯一的开关。
尺寸
样式表里的长度写成 calc(N * var(--omx-rem, 16.8px)),不用 rem,所以你的根字号改不到聊天。16.8px 是浏览器默认字号的 105%,即聊天在 OpenMax 里的大小。想整体缩放,就在 ChatRoot(或它的祖先)和渲染在它外面的部分(overlayContainer 节点、浮出面的 container)的共同祖先上设 --omx-rem,通常是 <html>:
html {
--omx-rem: 15px;
}
样式表从不声明 --omx-rem,聊天的每个部分都继承到同一个值。你自己用 rem 写的长度(比如上面的 --radius)跟的是你的根字号;要跟着聊天缩放,写成 calc(N * var(--omx-rem, 16.8px))。聊天里容器查询的断点是固定的像素值,不跟着它缩放。
ChatShadowRoot 也一样:自定义属性会继承进 shadow root,所以在 <omx-chat-host> 或它的祖先上设 --omx-rem,主聊天区就跟着缩放。浮出面、overlayContainer 和 overlayContainer="body" 渲染进页面别处的岛里(通常在 body 末尾),要让它们一起缩放,就把 --omx-rem 设在它们和 <omx-chat-host> 的共同祖先上,比如 html。
Shadow DOM 下的宿主元素
用 ChatShadowRoot(实验性)时,聊天区渲染进一个 <omx-chat-host> 元素的 shadow root。这个元素在你的页面里,是你布局里的一个盒子,默认块级(display: block)。SDK 不在它上面写行内 display,你的类或 style 写成 flex、grid 等都生效:
omx-chat-host.chat-pane {
display: flex;
height: 100%;
}
SDK 为浮出面、overlayContainer 和 overlayContainer="body" 在别处另建的 <omx-chat-host>(文档里叫「岛」)是 display: contents,只是弹出层或浮窗渲染进去的落点,不在你的布局里占盒子,不用给它们写布局规则。
你页面上的 CSS 进不了 shadow root,在 .omx-chat 上覆盖聊天变量的规则也一样:样式表在 shadow root 里每个 .omx-chat 节点上都声明了这些变量,从你的页面继承来的值到那里就被换掉了。--omx-rem 是例外,因为样式表从不声明它。
覆盖组件样式
样式表里的工具类写成 .omx-chat .flex,优先级 (0,2,0)。你经 className 传给 SDK 组件的类(.my-x,(0,1,0))会输给它们。优先改上面的变量;确实要覆盖某个属性时,选择器也照样限定在作用域下,并写在 import 之后:
.omx-chat .my-x {
border-radius: 0;
}
变量参考
样式表在 .omx-chat 上声明的变量。它们是内部的,列在这里是为了看清每个值管什么;有对应的输入变量时请用输入变量。
颜色
默认值见 @openmaxai/chat-sdk/styles.css。
| 变量 | 用途 |
|---|---|
--background |
页面背景 |
--foreground |
正文 |
--card / --card-foreground |
面板、气泡 |
--popover / --popover-foreground |
菜单、浮层 |
--primary |
品牌色(默认 #21b1ff):自己的气泡、按钮、选中态 |
--primary-foreground |
--primary 上的文字 |
--primary-hover |
悬停态 |
--primary-ink |
品牌色小字(名字旁 Agent 小标签、头部选中按钮) |
--secondary / --secondary-foreground |
次要按钮 |
--muted / --muted-foreground |
弱化的背景和文字(时间、提示) |
--accent / --accent-foreground |
菜单项悬停 |
--destructive |
错误、发送失败 |
--border |
边框 |
--input |
输入框边框 |
--ring |
焦点环 |
--radius |
基础圆角(默认 0.625 × --omx-rem),rounded-sm 到 rounded-4xl 都按它缩放 |
聊天不使用 --chart-* 和 --sidebar-*。--shadow-ambient 是浮在会话上面那几块的阴影:信息侧栏与群信息面板盖在消息区上时、消息操作栏、表情回应的「谁回应了」列表。
聊天专用
| 变量 | 出现在哪 |
|---|---|
--badge-collab-bg / --badge-collab-fg |
「协作」会话徽标 |
--badge-group-bg / --badge-group-fg |
「群聊」徽标 |
--badge-channel-bg / --badge-channel-fg |
「频道」徽标(-fg 跟随 --primary) |
--badge-agent-bg / --badge-agent-fg |
Agent 徽标,在会话行和消息发送者旁(-fg 跟随 --primary) |
--panel-gradient |
会话列表面板的背景 |
--panel-bar-bg |
会话头部的背景 |
--coco-blue-l1-30 |
会话列表搜索框的背景 |
--coco-cyan-10 |
名字旁 Agent 小标签的底色,在通讯录搜索结果里 |
--coco-green |
已读回执,以及头部「正在输入…」那一行 |
布局
由聊天组件自己定义,与上面的颜色变量分开:
| 变量 | 默认值 | 作用 |
|---|---|---|
--chat-list-w |
clamp(220px, 26vw, 340px) |
桌面端会话列表宽度。设在祖先元素上即可调整这一栏。用了 ResizableConversationListColumn 时,width 不为 null 就由它在自己的外壳上设置,覆盖祖先上的值 |
--msg-action-bar-h |
1.6 × --omx-rem |
消息操作栏占位高度 |
--msg-action-bar-gap |
0.25 × --omx-rem |
气泡和操作栏之间的间距 |
变量名仍可能调整。
