安装
安装聊天组件、SDK 及其 peer 依赖,引入样式表,配置打包器,并包上所需的 Provider。
安装
预发布版本
这些包已发布到 npm,目前是
3.0.0的预发布版本(3.0.0-beta.*)。所有导出都标着@experimental,预发布版本之间可能变动,所以要锁定确切版本号(例如3.0.0-beta.5),所有@openmaxai/chat*包用同一个。
环境要求
- React 19
不需要 Tailwind CSS:SDK 自带预编译好的样式表。
安装依赖
pnpm add @openmaxai/chat@3.0.0-beta.5 @openmaxai/chat-store@3.0.0-beta.5 @openmaxai/chat-sdk@3.0.0-beta.5 @openmaxai/chat-openmax@3.0.0-beta.5 react-i18next i18next
命令里每个 @openmaxai/chat* 包都锁同一个确切版本(这里是 3.0.0-beta.5,换版本时一起换)。只接自己的后端、不连 OpenMax 时,去掉 @openmaxai/chat-openmax。
| 包 | 用途 |
|---|---|
@openmaxai/chat |
聊天组件和 ChatHost 类型 |
@openmaxai/chat-store |
聊天的数据层,@openmaxai/chat 和 @openmaxai/chat-sdk 共用。要自己写进安装命令:页面上必须只有一份 |
@openmaxai/chat-sdk |
createChatHost({ adapter })(用你给的适配器建宿主,不认 OpenMax 的连接配置)、createLocalPorts(宿主的本地默认实现)、createChatI18n(聊天用的文案实例),以及预编译样式表 @openmaxai/chat-sdk/styles.css |
@openmaxai/chat-openmax |
接 OpenMax 后端用:@openmaxai/chat-openmax/react 的 createChatHost(config) 按 baseUrl、wsUrl、auth 直接建出连 OpenMax 的宿主,见接入 OpenMax。只接自己的后端时不装 |
react-i18next、i18next |
peer 依赖(react-i18next ^17.0.8、i18next ^26.3.2)。聊天组件经你装的这份 react-i18next 取文案;I18nextProvider、useTranslation 一律从它取 |
@tanstack/react-query |
@openmaxai/chat 的可选 peer 依赖(^5),只有 @openmaxai/chat/message-thread 的 MessageThread 用它 |
用 @openmaxai/chat/message-thread 的 MessageThread 时需安装 @tanstack/react-query@5,这项要求将在后续版本移除;@openmaxai/chat-sdk 本身不用它。
react、react-dom 19 也是 peer 依赖,React 19 项目里本来就有。
所有 @openmaxai/chat* 包必须装同一版本
@openmaxai/chat、@openmaxai/chat-store、@openmaxai/chat-sdk,以及接 OpenMax 时的@openmaxai/chat-openmax,必须是同一个版本:每个包给同一个版本号或同一个 dist-tag。@openmaxai/chat-sdk把@openmaxai/chat、@openmaxai/chat-store声明为 peer 依赖,版本就是它自己的版本(@openmaxai/chat-openmax对@openmaxai/chat、@openmaxai/chat-store、@openmaxai/chat-sdk也一样),所以版本不一致在安装时就会暴露:
- npm 报
ERESOLVE错误,什么都不装。把版本对齐;不要用--force或--legacy-peer-deps绕过去。- pnpm 照样装上,同时输出
unmet peer告警。不要忽略它,把版本对齐。(pnpm 的strictPeerDependencies设置会让pnpm install因此失败,但pnpm add仍然只告警。)- yarn 1 不会替你装 peer 依赖,版本不一致也只告警,所以要像上面的命令那样,自己把
@openmaxai/chat和@openmaxai/chat-store写进安装命令。版本不一致的几份各有一套状态和 React context,问题不声不响:比如从一份打开的浮窗永远不出现。如果它们还是进了页面,SDK 在控制台报
Package version mismatch,每个不一致的包版本只报一次(晚加载进来的那份在它到来时补报),开发模式下<ChatProvider>另抛同一文案的ChatSdkConfigError。用npm ls @openmaxai/chat @openmaxai/chat-store或pnpm why @openmaxai/chat @openmaxai/chat-store查,每个包都应只解析到一个版本。3.0.0-beta.1及更早的版本把这几个包写成普通依赖:版本不同时会悄悄另装一份,不报错也不告警,SDK 也不报这个错,要自己保持版本一致。
规划中的 Agent 运行不需要另装 @ag-ui/core:@openmaxai/chat 会依赖它(1.0.x),并把事件类型以 AgUiEvent 转出,见接入自有后端。规划中
引入样式
在全局 CSS 里引入一次 SDK 的样式表:
src/globals.css
@import "@openmaxai/chat-sdk/styles.css";
这份样式表是预编译好的:CSS 变量、基础样式和聊天组件用到的全部类名都在里面。不用配 Tailwind,不用写 @source,也不用加 PostCSS 插件。也可以在 JS 入口里引入(import "@openmaxai/chat-sdk/styles.css";)。
然后把聊天放进 ChatRoot(来自 @openmaxai/chat-sdk/react)。ChatRoot 给里面的 SDK 组件提供配色和弹出层落点;每个 SDK 组件在它里面各自带一个 .omx-chat 组件根,样式表里的每条规则都限定在这些组件根之内。组件不在 ChatRoot 里就没有样式,也不报错:
import { ChatProvider, ChatRoot } from "@openmaxai/chat-sdk/react";
<ChatProvider host={host}>
<ChatRoot colorScheme="light" style={{ height: "100%" }}>
{/* 你自己的布局:CwsConversationList、CwsMessageThread…… */}
</ChatRoot>
</ChatProvider>;
这样做之后:
- 页面其余部分不受影响。 样式表里没有作用在
html、body、:root上的规则,也没有.omx-chat之外的规则:你的根字号、滚动条、body的背景色和文字颜色、你自己的元素都保持原样。你的应用自己也用 Tailwind CSS v4 时,我们带的那份基础重置只作用在 SDK 组件自己的节点上。 - 你放进
ChatRoot的节点用你自己的样式。 你直接放在ChatRoot里的布局和内容,以及放进 SDK 组件插槽的内容(ChatSplitLayout的list/children、ConversationHeader的trailing、CwsMessageThread的emptyState、ResizableConversationListColumn的children,以及你经ChatProvider的messageRenderers装的消息展示插件画出的正文、经plugins装的输入框插件的面板和插槽(Panel、trigger.Panel、PlusSlot、LeadingSlot;工具条图标拿我们给的className,仍按聊天的样子画)),不被我们的基础重置改动:你的m-auto、边框颜色这类工具类照常生效,不管它们在不在@layer里。插槽里的继承与同名变量见已知限制。 - 你的元素选择器和通配规则只在聊天自己设了的属性上输。 在 SDK 组件的节点上,
button {}、a {}、h1 {}、* {}这类规则(写不写在@layer里都一样)在聊天样式设了的属性上输给聊天:每个元素的盒模型、外边距、内边距和边框,按钮的背景、字体和颜色,链接的颜色,标题的字号,以及聊天的类在元素上设的属性。聊天没设的属性,比如letter-spacing、word-spacing、text-transform,照样从你的规则作用进来;你在ChatRoot祖先上设的可继承属性也会传进聊天区。和我们同名的类规则、优先级高的规则同样会作用进来,见已知限制。要把这些都挡在外面,改用ChatShadowRoot嵌入(见嵌入 Shadow DOM):你的规则匹配不到聊天区的元素;shadow 边界挡不住的可继承属性(你的* {}也匹配 shadow 宿主元素,它上面的letter-spacing会继承下去)由 shadow 里的重置层挡住。 - 弹出层留在作用域里。 聊天里打开的菜单、提示、下拉、对话框和抽屉渲染进
ChatRoot容器末尾的落点节点(它自己带.omx-chat),不进body,样式和深色都跟着走。 - 动画名不撞车。 聊天的
@keyframes都叫omx-*,你自己的enter、spin改不到它的动画。 - 深色只看
colorScheme。 你在<html>上加dark类不影响聊天区,见主题。
聊天的尺寸以 --omx-rem(默认 16.8px)为基准,不跟你的根字号走,见主题 · 尺寸。
浮出面与 overlayContainer
ChatFloatingSurfaces 和 ChatDockColumn 同样放在 ChatRoot 里(React 树上):
ChatFloatingSurfacesportal 到你给的container(通常是document.body)。在ChatRoot里时,它先往这个容器里放一个带作用域类、display: contents的节点,浮窗、最小化坞和小屏抽屉都渲染在这个节点里。ChatDockColumn渲染在你放置它的地方,不用container。它必须在ChatRoot(或ChatShadowRoot)的 DOM 里、主内容旁边;放在外面就没有样式。
挂了其中任何一个,就同时给 overlayContainer,一般直接写 "body":SDK 自己在 body 末尾建落点节点,卸载时移除。不给的话,主聊天区里开的弹出层、从坞或浮窗拖出的卡片都落在 ChatRoot 容器里;容器的任何一个祖先建了层叠上下文(transform、filter、contain、isolation,或者带定位的元素设了 z-index),它们就升不出去,压在 body 一级的浮窗下面。给了 overlayContainer,它们也在 body 一级,按设计的次序叠放:拖出的卡片在浮窗之上。
import { ChatRoot } from "@openmaxai/chat-sdk/react";
import type { ReactNode } from "react";
export function ChatShell({ children }: { children: ReactNode }) {
return <ChatRoot overlayContainer="body">{children}</ChatRoot>;
}
也可以传你自己的节点,要是 body 的直接子节点(如果浮出面有自己单独的 container 节点,把这个节点放在它后面)。这个节点还是 null 的时候(你的 ref 还没拿到它),弹出层回到 body、没有聊天的样式。写 "body" 也有一段类似的空档,长一次 commit:ChatRoot 里落点节点要在挂载后的下一次 commit 才就绪,在那之前打开的弹出层同样落到 body(见已知限制「首帧弹出层在 body 里」)。
ChatRoot 在 overlayContainer 里建的落点节点带作用域类(深色时另带 omx-dark),弹出层在那里照样有聊天的样式。弹出层里的 React 事件仍沿 React 树冒泡:菜单或对话框的 DOM 节点在 body 下,ChatRoot 的 React 祖先上的 onClick 照样收得到里面的点击。
你自己的抽屉和对话框
浮窗在你页面的抽屉、对话框外面(DOM 上是 body 下的另一个节点),所以你的抽屉开着时点浮窗,抽屉会判成「点到外面了」而关掉。在它的外部交互回调里用根入口的 isChatSurfaceInteraction 排除聊天的浮出面:
host-drawer.tsx
import { isChatSurfaceInteraction } from "@openmaxai/chat-sdk";
<Dialog.Content
onInteractOutside={(event) => {
if (isChatSurfaceInteraction(event)) event.preventDefault();
}}
>
…
</Dialog.Content>
浮窗里打开的菜单、表情选择器、对话框即使 portal 到别处也算浮出面。它从根入口导出、不依赖 React,你的 Radix 与聊天的不是同一份也照样判得出;不用 Radix 时,在 document 上按冒泡阶段监听 pointerdown / focusin,把事件交给它;不要用捕获阶段,标记是聊天在 React 的事件派发里打的(React 的监听挂在页面节点上,不在 document),document 的捕获监听比它先跑。
这样只管「点到外面不关」。对话框是模态(Radix 的默认)时还会把焦点锁在框里:框开着不关了,但浮窗里的输入框拿不到焦点、打不了字。要在框开着时用浮窗,把框设成非模态(modal={false})。
在你的对话框里按 Esc
聊天自带一份 Radix,所以你页面上的 Radix 层(对话框、抽屉、弹出层)与聊天里的层互相看不见。焦点在聊天的某一层里时(菜单、表情选择器、对话框),按 Esc 关的是聊天最上面那一层,你的层留着;再按一次才关你的。聊天对这次 Esc 只调 preventDefault()、不拦传播,所以你的 Radix 层不会再关,你的其他监听照样收得到。
你的层的 onEscapeKeyDown 对这次 Esc 照样会被调用,拿到的 event.defaultPrevented 已经是 true。如果你在里面做关闭以外的事(埋点、「有未保存的修改」确认),先判它,是 true 就直接返回:
host-dialog.tsx
<Dialog.Content
onEscapeKeyDown={(event) => {
if (event.defaultPrevented) return; // 聊天关的是它自己的层
track("host_dialog_escape");
}}
>
…
</Dialog.Content>
不要在 onEscapeKeyDown 里调 preventDefault() 给聊天让出 Esc:聊天那份也会看到 defaultPrevented,结果哪一层都不关。不用 Radix、自己监听 Esc 来关东西的话,在 document 上或冒泡阶段监听,defaultPrevented 为 true 的事件跳过;window 上的捕获监听可能在聊天处理这次按键之前就跑了。
焦点不在聊天的任何层里时,Esc 照旧先到你的层,见已知限制。
嵌入 Shadow DOM
ChatRoot 靠类选择器划作用域,所以页面上有些 CSS 仍会作用到聊天区(见已知限制)。页面上有你改不了的规则时,比如全局的元素选择器或通配规则、与我们同名的类、高优先级选择器,把聊天放进 ChatShadowRoot(实验性)而不是 ChatRoot。它在你的页面里渲染一个 <omx-chat-host> 元素,把聊天渲染进这个元素的 open shadow root。仍然是同一棵 React 树:你的 Provider 和 context 在里面的组件里照样读得到。
样式经属性传进去:把字符串入口 @openmaxai/chat-sdk/styles 整个模块传给它(它导出 styles 和 properties)。只用 ChatShadowRoot 的页面不用引 @openmaxai/chat-sdk/styles.css,也只有用 Shadow DOM 的页面才会把样式表以字符串打进包里:
import { ChatProvider, ChatShadowRoot } from "@openmaxai/chat-sdk/react";
import * as chatStyles from "@openmaxai/chat-sdk/styles";
<ChatProvider host={host}>
<ChatShadowRoot styles={chatStyles} colorScheme="light" style={{ height: "100%" }}>
{/* 你自己的布局:CwsConversationList、CwsMessageThread…… */}
</ChatShadowRoot>
</ChatProvider>;
和 ChatRoot 相比:
- 你的规则进不来。 页面上的元素选择器、通配规则、同名类、高优先级规则,以及
<html>上的dark类,都匹配不到 shadow root 里的任何元素。设在<omx-chat-host>或它祖先上的可继承属性(letter-spacing、text-align、white-space等)仍会穿过 shadow 边界,由 shadow 里的重置层挡住。自定义属性(包括--omx-rem)和书写方向有意照常继承。 - 页面其余部分不受影响。 样式表以可构造样式表注入 shadow root,每个文档一份、所有实例共用(浏览器不支持可构造样式表时,退回在 shadow root 里写一个
<style>)。SDK 自己的样式除了一个<style data-omx-chat-properties>之外都不进页面head:它装着只能在文档一级生效的@property注册;只写一次,从不撤掉。之后又来了内容不同的一份(同一页面上有两个版本的 SDK)时,SDK 把它也追加进去并console.warn;两份都注册了的同名属性用哪份定义,由浏览器决定。SDK 用到的库也会往head写东西,已知的有:vaul 一加载就追加自己的<style>;滚动锁生效时加一个(见已知限制)。 <omx-chat-host>是你布局里的一个盒子,默认块级;className和style加在它上面。见主题 · Shadow DOM 下的宿主元素。- 弹出层默认留在 shadow root 里,落点节点在首次渲染之前就建好了,所以从不回落到
body。用了浮出面时,像上面那样写overlayContainer="body":SDK 在body末尾另建一个小的 shadow root(「岛」,样式相同),弹出层落在那里。和ChatRoot不同,overlayContainer={null}等同于不写:直接落进body的弹出层拿不到聊天的样式。 - 浮出面和停靠列照样放进
ChatShadowRoot,和放进ChatRoot一样:ChatFloatingSurfaces在它的container里建一个岛,ChatDockColumn必须在ChatShadowRoot的children里。 - 字体由你的页面提供。 样式表里没有
@font-face:在 shadow root 里声明的字体不可靠。要让聊天区用网络字体,在你页面自己的 CSS 里、也就是外层文档里加载它,聊天区按名字就能用上。 - 服务端渲染只输出一个空的
<omx-chat-host>;shadow root 和聊天在浏览器里挂载之后才出现。
Shadow DOM 解决了哪些问题、哪些限制还在、又带来了哪些新限制,见已知限制 · Shadow DOM。
配置打包器
Vite
对 React 去重,否则可能加载两份 React,报 Invalid hook call。
vite.config.ts
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [react()],
resolve: { dedupe: ["react", "react-dom"] },
});
Next.js
在根 layout 里引入一次样式表;聊天组件要在 Client Component("use client")里渲染。带 "use client" 的模块在服务端渲染时也会执行;在模块顶层建宿主、REST 走同源代理的写法见接入 OpenMax · 服务端渲染与 Next.js。
app/layout.tsx
import "@openmaxai/chat-sdk/styles.css";
Provider
从外到内:
| Provider | 来自 | 作用 |
|---|---|---|
I18nextProvider |
react-i18next |
提及面板、群管理、浮窗和抽屉的文案,缺了会显示 key。实例用 @openmaxai/chat-sdk 的 createChatI18n 建,见国际化 |
QueryClientProvider |
@tanstack/react-query |
用 @openmaxai/chat/message-thread 的 MessageThread 时要包:老消息区经 React Query 缓存。createChatHost 创建的宿主不带这一层,同样要包 |
ChatProvider |
@openmaxai/chat-sdk/react |
安装宿主和输入框插件,是唯一的入口。createChatHost 创建的宿主和自己实现的宿主都用它装;可选的 plugins 不传就装默认插件 |
src/app.tsx
import { createChatI18n } from "@openmaxai/chat-sdk";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { I18nextProvider } from "react-i18next";
import { host } from "./host"; // createChatHost 创建的宿主
const i18n = createChatI18n({ locale: "zh-CN" });
export function App() {
return (
<I18nextProvider i18n={i18n}>
<ChatProvider host={host}>
{/* CwsConversationList、CwsMessageThread …… */}
</ChatProvider>
</I18nextProvider>
);
}
createChatI18n 新建一份独立的 i18next 实例,内置聊天的文案,不动你应用自己的 react-i18next 配置。用 @openmaxai/chat/message-thread 的 MessageThread 时还要在 I18nextProvider 和 ChatProvider 之间包一层 QueryClientProvider。快速开始用的是 CwsMessageThread,不需要这一层。
createChatHost 创建的宿主,ChatProvider 会在登录用户信息加载完成后自动刷新界面。直接传 createChatHost() 返回的那个对象,不要展开复制({ ...host }):展开副本会让 ChatProvider 抛 ChatSdkConfigError。
输入框插件不用自己挑:每个插件写明自己需要哪些能力,宿主缺能力的插件 SDK 就不装。例如宿主没有 workItems,输入框里就没有 #,@ 照常可用。要换一套插件,传 plugins 即可,写在组件里也行,SDK 按插件 id 比较,id 不变就不会重建编辑器(同一个 id 换了插件对象不会生效)。插件有哪些、怎么自己写,见插件。
下一步
- 核心概念: 宿主、能力、适配器。
- 快速开始: 用内存数据跑起一个聊天。
- 接入 OpenMax: 用 createChatHost 连 OpenMax 后端。
