OpenMax
免费试用

主题

通过覆盖 CSS 变量调整聊天组件的品牌色、圆角和深色模式。

主题

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

theming-custom-colors demo

演示截图。演示跑在内存里的示例 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 气泡和操作栏之间的间距

变量名仍可能调整。