OpenMax
免费试用

安装

安装聊天组件、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 树上):

  • ChatFloatingSurfaces portal 到你给的 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 换了插件对象不会生效)。插件有哪些、怎么自己写,见插件。

下一步