OpenMax
免费试用

概览

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

概览

chat-app demo

演示截图。演示跑在内存里的示例 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 需要的滚动和键盘补偿

用浮窗、停靠列还是底部抽屉承载会话,是整个页面的布局选择,由应用决定,见浮窗、停靠列与抽屉。