概览
@openmaxai/chat 里有哪些聊天组件:按界面位置分成会话列表、会话区和弹层,以及使用它们需要在外面包哪些东西。
概览

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): chat-app.tsx
"use client";
import { ConversationList } from "@openmaxai/chat/conversation-list";
import { ChatHeader } from "@openmaxai/chat/header";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend), and
// useDemoConversations() is its conversation list (a DM started from search is added to it).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoConversations, useDemoHost, useIsCompact } from "./kit";
export default function ChatApp() {
const host = useDemoHost();
const conversations = useDemoConversations();
const isCompact = useIsCompact();
const [selectedId, setSelectedId] = useState<string | null>(
isCompact ? null : conversations[0].id,
);
const selected = conversations.find((c) => c.id === selectedId) ?? null;
return (
<ChatHostProvider host={host}>
<div className="flex h-full bg-background text-foreground">
{/* On a phone show one column at a time: the list, or the open conversation. */}
<aside
className={
isCompact ? (selected ? "hidden" : "min-w-0 flex-1") : "shrink-0"
}
>
<ConversationList
conversations={conversations}
selectedId={selectedId}
onSelect={(c) => setSelectedId(c.id)}
onDeselect={() => setSelectedId(null)}
// Starting a DM from search opens it here too.
onSelectConversationId={setSelectedId}
/>
</aside>
{selected && (
<main className="flex min-w-0 flex-1 flex-col">
<ChatHeader
conversation={selected}
headerTitle={selected.name ?? ""}
headerSubtitle={null}
isAgentCollab={false}
isObserving={false}
collabAgents={[]}
typingText={null}
mode={isCompact ? "compact" : "full"}
onBack={isCompact ? () => setSelectedId(null) : undefined}
infoPanelOpen={false}
/>
<MessageThread key={selected.id} conversation={selected} />
</main>
)}
</div>
</ChatHostProvider>
);
}
本节讲 @openmaxai/chat 的组件,数据和操作全部来自你提供的宿主。换一个宿主,同一套组件就能接 OpenMax、自有后端或内存数据。
这些组件不带样式根:SDK 样式表(@openmaxai/chat-sdk/styles.css)只作用在 SDK 组件自带的 .omx-chat 组件根之内,ChatRoot 本身不是样式作用域,所以单独渲染它们没有样式,要你把它们放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。用 createChatHost 的宿主时,会话列表、消息区、会话头部和群信息面板改用 @openmaxai/chat-sdk/react 的 CwsConversationList、CwsMessageThread、ConversationHeader、CwsGroupInfoPanel,写法见快速开始。
按界面位置
左栏
- 会话列表: 置顶宫格、带未读数和草稿的会话行、搜索、置顶与隐藏。
会话区
从上到下:头部、消息区(含卡片和 Agent 运行进度)、输入框。
- 会话头部: 标题、状态、正在输入、群信息按钮、Agent 模型切换和运行入口。
- 消息区: 消息历史、实时更新、表态、撤回与编辑、已读回执、Agent 运行进度与停止。
- 输入框: 消息区底部的输入区:文字、附件、@ 提及和 # 工作项。
- 交互卡片: 带按钮和选项的消息卡片,以及和 Agent 运行绑定的审批卡。
弹层与侧栏
主页面之外
- 浮窗、停靠列与抽屉: 在任何页面上打开会话:浮窗、右侧停靠列、最小化坞和小屏底部抽屉。
引入路径
| 组件 | 引入路径 |
|---|---|
ConversationList、ResizableConversationListColumn |
@openmaxai/chat/conversation-list |
ChatHeader |
@openmaxai/chat/header |
MessageThread |
@openmaxai/chat/message-thread |
COMPOSER_PLUGINS、defineComposerPlugin |
@openmaxai/chat/composer |
CreateGroupModal、ChatInfoPanel、AddMemberContainer |
@openmaxai/chat/group-management |
FloatingChatLayer、ChatDockColumn、ChatMinimizedDock、ChatMobileDrawer(自己拼界面时用;用 SDK 时挂 @openmaxai/chat-sdk/react 的 ChatDockColumn、ChatFloatingSurfaces) |
@openmaxai/chat/surfaces |
AgentRunList、AgentRunPanel、AgentRunProgress、AgentRunSteps、AgentStopButton 规划中 |
@openmaxai/chat/agent-runs |
卡片、名片、大图查看器和 Agent 运行进度不用单独挂载,宿主提供对应能力后会出现在 MessageThread(和 ChatHeader)里。
Provider
从外到内包上这几层,完整代码见安装:
| 层 | 说明 |
|---|---|
I18nextProvider |
少数界面用 useTranslation 取词。见国际化 |
ChatProvider |
安装宿主和输入框插件。宿主 OpenMax 用 createChatHost(config),其他后端自己写 ChatHost,都用 <ChatProvider host={host}> 装;插件默认全装,宿主缺能力的不装,见输入框。见快速开始、接入自有后端 |
宿主缺少某个可选能力时,表现分三种:不显示对应控件、显示禁用的占位控件,或者用到它的组件抛错(conversations、groupManagement)。聊天组件没有错误边界,抛错会卸掉整棵 React 树,见已知限制。对照表见能力 · 缺了可选能力会怎样。
各页演示代码里的 useDemoHost() 是带示例数据的内存宿主。在应用里换成 createChatHost() 的返回值或你自己的 ChatHost,外层 Provider 按上表包好即可。
响应式
组件不收「是不是移动端」这类设备开关。聊天常嵌在侧栏、浮窗、停靠列里,桌面上的浮窗也可能很窄,所以组件看的是自己容器的宽度,不看视口,也不猜设备。
- 排版和样式跟随容器宽度(CSS 容器查询)。断点是 768 px:容器窄于 768 px 时用窄排版(间距、输入区高度、按钮位置随之调整),群信息面板改为盖住会话区的全屏浮层。
- 只有调用方知道的事用 props 说。 例如头部传了
onBack就显示返回箭头,不传就没有。 - 写不成 CSS 的行为由组件自己判断,按三根轴分开,一根不代替另一根:
| 轴 | 怎么判断 | 决定什么 |
|---|---|---|
| 宽度 | 量自己的容器 | 排版;群信息面板是侧栏还是全屏浮层 |
| 输入方式 | (pointer: coarse)、指针事件的 pointerType |
悬停出操作栏还是点按 / 长按出;滑动手势;向上翻页的提前量和「已到底部」的判定距离(同时参考容器高度);打开会话时不自动聚焦,免得弹出软键盘;触屏上图片消息的操作栏由长按图片叫出(点图片不分输入方式都是放大) |
| iOS 软键盘 | 平台判断 | 只有 iOS 需要的滚动和键盘补偿 |
用浮窗、停靠列还是底部抽屉承载会话,是整个页面的布局选择,由应用决定,见浮窗、停靠列与抽屉。
