OpenMax
免费试用

会话头部

会话上方的标题栏,包含标题、状态、正在输入、群信息按钮、Agent 模型切换和规划中的 Agent 运行入口。

会话头部

header-group demo

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。

演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): header-group.tsx
"use client";

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).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost, useIsCompact } from "./kit";

export default function GroupHeaderDemo() {
	const host = useDemoHost();
	const { conversations, lang } = useDemoData();
	const isCompact = useIsCompact();
	const [infoOpen, setInfoOpen] = useState(false);
	const group = conversations[0];

	return (
		<ChatHostProvider host={host}>
			<div className="flex h-full flex-col bg-background text-foreground">
				<ChatHeader
					conversation={group}
					headerTitle={group.name ?? ""}
					headerSubtitle={lang === "zh" ? "4 位成员" : "4 members"}
					isAgentCollab={false}
					isObserving={false}
					collabAgents={[]}
					typingText={null}
					mode={isCompact ? "compact" : "full"}
					infoPanelOpen={infoOpen}
					// Without this callback the header draws no info-panel button.
					onToggleInfoPanel={() => setInfoOpen((open) => !open)}
				/>
				<div className="flex min-h-0 flex-1">
					{/* In a row, the thread must fill the remaining width itself, or it shrinks to its content and no longer lines up with the header. */}
					<div className="flex min-w-0 flex-1 flex-col">
						<MessageThread conversation={group} />
					</div>
					{infoOpen && (
						<aside className="w-56 shrink-0 border-l p-4 text-muted-foreground text-sm">
							{lang === "zh"
								? "infoPanelOpen 为 true 时,在这里放你的群信息面板。"
								: "infoPanelOpen is true: put your group info panel here."}
						</aside>
					)}
				</div>
			</div>
		</ChatHostProvider>
	);
}

演示使用内存宿主(useDemoHost)。实际项目里宿主来自 createChatHost,ChatHeader 只需放在它的 Provider 里。

何时使用

  • 放在 MessageThread 上方。MessageThread 不自带头部。
  • 标题、副标题、徽标等由应用算好传入,头部不判断会话类型。
  • trailing 插槽可放自己的控件,比如浮窗的最小化 / 关闭。

代码示例

第一节用 SDK 的 ConversationHeader;其后各节用的是 @openmaxai/chat/header 的 ChatHeader,它不带样式根:SDK 样式表只作用在 SDK 组件自带的 .omx-chat 组件根之内,ChatRoot 本身不是样式作用域,所以照抄出来没有样式。要用它,把它放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式;用 createChatHost 的宿主时用 ConversationHeader。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。

SDK 的会话顶部栏

header-sdk demo

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。

演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): header-sdk.tsx
"use client";

import {
	ChatProvider,
	ConversationHeader,
	CwsMessageThread,
	createChatHost,
} from "@openmaxai/chat-sdk/react";
import { createMemoryAdapter } from "@openmaxai/chat-sdk/testing";
import { useEffect, useMemo } from "react";
// Docs helpers: page language and the toast line at the bottom of the demo.
import { useDemoData, useDemoNotify } from "./kit";

export default function SdkHeaderDemo() {
	const { lang, members } = useDemoData();
	const notify = useDemoNotify();
	// In your app the host comes from createChatHost() with your adapter. The memory adapter
	// implements `conversations.setMuted`, so the header shows the mute toggle.
	const host = useMemo(
		() =>
			createChatHost({
				adapter: createMemoryAdapter({
					me: members[0],
					people: members.slice(1),
					conversations: [
						{
							id: "design",
							name: lang === "zh" ? "设计评审" : "Design review",
							messages: [
								{
									senderId: members[1]?.memberId ?? "me",
									text: lang === "zh" ? "稿子发群里了" : "Mockups are in",
								},
							],
						},
					],
				}),
				locale: lang === "zh" ? "zh-CN" : "en",
				ports: { attention: { notify, setUnreadSignal: () => {} } },
			}),
		[lang, members, notify],
	);
	useEffect(() => () => host.dispose(), [host]);
	const conversation = {
		id: "design",
		type: "GROUP" as const,
		name: lang === "zh" ? "设计评审" : "Design review",
		created_at: "2026-10-01T00:00:00Z",
		last_message_at: "2026-10-01T00:00:00Z",
		unread_count: 0,
		member_count: members.length,
		is_observer: false,
	};

	return (
		<ChatProvider host={host}>
			<div className="flex h-full flex-col bg-background text-foreground">
				{/* Title, member count and mute come from the conversation; on a narrow
				    screen `onBack` adds a back arrow. */}
				<ConversationHeader
					conversation={conversation}
					onBack={() => notify("info", "onBack()")}
				/>
				<CwsMessageThread conversation={conversation} />
			</div>
		</ChatProvider>
	);
}

用 createChatHost 时放 ConversationHeader:标题、头像、徽标、成员数从会话数据算,和会话列表那一行同名;读的是列表里同一 id 的最新那一行,静音、成员数、改名后跟着变;这条会话不在已取到的列表里时(已隐藏、从链接打开),静音开关读这次设成功的结果(换到别的会话就不再用它);静音成功后再从链接打开这条会话,读到的是静音后的状态。

conversation-pane.tsx

import { ConversationHeader, CwsMessageThread } from "@openmaxai/chat-sdk/react";

<ConversationHeader
  conversation={selected}
  onBack={() => setSelected(null)}
  trailing={<MyButton />}
/>;
<CwsMessageThread conversation={selected} />;
  • 静音:宿主有 conversations.setMuted(OpenMax 适配器已接)时出现开关,旁观的会话没有;失败时经 attention.notify 提示。
  • 返回:窄屏(视口窄于 768 px)且传了 onBack 才有返回键。一次一栏的布局用 ChatSplitLayout;浏览器后退要你的应用自己接历史。
  • 群信息:传 onToggleInfoPanel 才有按钮,只在群聊里。Chat SDK 的 ConversationHeader 另要宿主有 groupManagement、会话不是旁观,否则传了也不画。trailing 画在最右侧。
  • 正在输入与对端在线状态:副标题那一行画正在输入;与 Agent 单聊时画对端的在线状态(来自成员资料与 presence 信号,状态不知道时不画、不猜「离线」,对方计费停机时照旧画「暂停 · 欠费」)。还没有的见已知限制。属性见 API 参考。

群聊

conversation-header.tsx

import { ChatHeader } from "@openmaxai/chat/header";

<ChatHeader
  conversation={conversation}
  headerTitle={titleFor(conversation)}
  headerSubtitle={`${memberCount} 位成员`}
  isAgentCollab={conversation.type === "BRIDGE"}
  isObserving={conversation.is_observed === true}
  collabAgents={[]}
  typingText={null}
  infoPanelOpen={infoOpen}
  onToggleInfoPanel={() => setInfoOpen((v) => !v)}
/>;

信息按钮用来打开 ChatInfoPanel,只在 GROUP 会话且传了 onToggleInfoPanel 时出现。

带模型切换的 Agent 单聊

header-agent-dm demo

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。

演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): header-agent-dm.tsx
"use client";

import { ChatHeader } from "@openmaxai/chat/header";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// 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 { AGENT, useDemoData, useDemoHost, useIsCompact } from "./kit";

export default function AgentDmHeaderDemo() {
	// The demo host provides `agentConfig` (model selector) and `profileCard` (clickable avatar).
	const host = useDemoHost();
	const { conversations } = useDemoData();
	const isCompact = useIsCompact();
	const dm = conversations.find((c) => c.id === "helper");
	if (!dm) return null;

	return (
		<ChatHostProvider host={host}>
			<div className="flex h-full flex-col bg-background text-foreground">
				<ChatHeader
					conversation={dm}
					headerTitle={dm.name ?? ""}
					headerSubtitle={null}
					isAgentCollab={false}
					isObserving={false}
					collabAgents={[]}
					dmPeerStatus="online"
					typingText={null}
					mode={isCompact ? "compact" : "full"}
					infoPanelOpen={false}
					// Your own agent: the header shows the model selector for it.
					isAgentOwnerDm
					agentModelMemberId={AGENT}
				/>
				<MessageThread conversation={dm} />
			</div>
		</ChatHostProvider>
	);
}

你和自己名下 Agent 的单聊里,头部可以切换模型、设置模型名是否对他人可见。

<ChatHeader
  /* …必填 props */
  isAgentOwnerDm
  agentModelMemberId={agentMemberId}
/>

不传 agentModelMemberId 就不画。数据来自宿主的 agentConfig 能力:

agent-config.ts

import type { ChatAgentConfigPort } from "@openmaxai/chat/host";

export const agentConfig: ChatAgentConfigPort = {
  async loadModelState(agentMemberId) {
    const res = await api.getAgentModel(agentMemberId);
    if (!res.ok) return undefined; // 头部会显示禁用的占位控件
    return {
      effectiveModel: res.body.active,
      desiredModel: res.body.requested,
      applyState: res.body.pending ? "applying" : "ready",
      visible: res.body.public,
      configurable: res.body.canEdit,
      availableModels: res.body.choices.map((c) => ({ key: c.id, displayName: c.label })),
    };
  },
  setModel: (agentMemberId, model) => api.setAgentModel(agentMemberId, model),
  setModelVisibility: (agentMemberId, visible) => api.setAgentModelVisibility(agentMemberId, visible),
};
  • 读不到模型时 loadModelState 返回 undefined,不要抛错。
  • setModel 返回只代表已受理。头部会重新读取状态,applyState 变回 ready 前一直显示「应用中」。
  • 别人的 Agent 改传 dmPeerModelLabel,显示只读模型名。

用 @openmaxai/chat-sdk 时,适配器的 agentConfig 是同一个类型,SDK 自有名为 ChatSdkAdapterAgentConfig,适配器不必从 @openmaxai/chat/host 引。

单栏布局和浮窗

<ChatHeader
  /* …必填 props */
  mode="compact"
  onBack={() => setSelectedId(null)}
  trailing={<WindowControls />}
/>

传了 onBack 才显示返回箭头,显示不显示由你决定,比如只在一次只显示一栏的布局里传。头部的排版跟随所在容器的宽度,不需要告诉它是不是移动端,见响应式。

头部在盖住应用弹层的浮层里时,传 overlayContainer,让它的浮层渲染在这一层里。

Agent 运行入口

规划中

宿主提供 agentRuns 能力后,头部为每个有未结束运行的 Agent 显示一个入口,如「助手 · 2 个进行中 · 1 个排队中」。点开是这个 Agent 在本会话里的运行列表(AgentRunList)。

今天:执行摘要(过渡)

过渡

上面的运行入口落地之前,用 Chat SDK 时头部已有一句执行摘要,属只读进度(实验性 · 过渡)。宿主的 agentActivity 里这条会话有进行中(排队中、思考中、调用工具中)且没失联的 run 时,ConversationHeader 把它显示在副标题的位置,有人在输入也先显示它;run 全部结束(终态、失联、淘汰、作用域结束)后回落到下面的「正在输入」。ChatHeader 自己不算,文字同样经 typingText 传进来。

进行中的 run 显示(chat 命名空间的 key)
一个,排队中 「助手 等待处理」(agentRun.header.queued);当前用户参与的单聊里不带名字:「等待处理」(agentRun.state.queued)
一个,处理中 「助手 处理中」(agentRun.header.working);当前用户参与的单聊里不带名字:「处理中」(agentRun.state.working)
同一个 Agent 的两条及以上 「助手 处理中(2 条)」(agentRun.header.workingCount),都在排队时「助手 等待处理(2 条)」(agentRun.header.queuedCount);当前用户参与的单聊里不带名字:「处理中(2 条)」(agentRun.state.workingCount)/「等待处理(2 条)」(agentRun.state.queuedCount)
两个及以上的 Agent 「2 个 Agent 处理中」(agentRun.header.many),数的是不同的 Agent,不是 run

名字取这条会话的成员,查不到时是「未知成员」。头部只给固定状态,不写 Agent 正在做的具体动作,动作在消息区的执行过程块里。规划中的 Agent 运行能力落地时由上面的运行入口替换它。

正在输入

会话里有当前用户以外的人在输入时,头部副标题的位置显示「正在输入」,压过对端状态与副标题。ChatHeader 自己不算:文字由 typingText 传进来;用 Chat SDK 时 ConversationHeader 替你算好(数据来自适配器 realtime 交的 typing 信号)。

谁在输入 显示(chat 命名空间的 key)
当前用户参与的单聊里的对方 「正在输入…」(typing.peer)
其余:一个人 「张三 正在输入…」(typing.one,名字查不到时是「未知成员」)
其余:两个人及以上 「3 人正在输入…」(typing.many)
  • 只算别人。 自己在别的标签页或设备上输入不显示;当前用户还不知道(GET /me 没回)时谁都不显示。
  • 会自己过期。 最后一声「开始」之后 6 秒没有新的就去掉;收到「停止」立即去掉。对方发了消息不会提前收起。
  • Agent 照样显示。
  • 旁观者看不看得到以后端为准:OpenMax 目前只把 typing 发给会话成员。
  • 自己打字别人看不到:Chat SDK 还不发 typing,见已知限制。

数据来自 typing 信号,见实时与同步 · 实时信号。会话列表的行上不显示「正在输入」。

API

Prop 类型 默认值 说明
conversation ChatConversation 必填 当前会话
headerTitle string 必填 标题
headerSubtitle string | null 必填 副标题;Agent 单聊里改为显示 Agent 状态
isAgentCollab boolean 必填 Agent 协作会话,显示协作的 Agent
isObserving boolean 必填 当前用户在旁观(只读)
collabAgents CollabAgent[] 必填 协作会话里显示的 Agent
typingText string | null 必填 「正在输入」的文字,见正在输入;null 不显示
infoPanelOpen boolean 必填 信息按钮的按下状态
dmPeerStatus OnlineStatus — 单聊对方的在线状态
peerStatusAvailable boolean true 有没有对方的在线状态。false 时 Agent 单聊的状态行只在对方计费停机时显示,不显示「离线」
mode "full" | "compact" "full" 密度,只影响间距。移动端和浮窗用 compact
showIdentity boolean true 画不画会话的头像与名字。停靠列给 false(标签上已有),其余元素照常
inlineMeta boolean false 副行(正在输入 / 对端状态 / 副标题)与徽标 / 模型排进同一行、不换行,副行在前;名字(画身份时)独占上面一行。停靠列与抽屉给 true;放不下时徽标与模型名截断,不换行
onBack () => void — 返回箭头回调;传了就显示返回箭头
onToggleInfoPanel () => void — 群信息按钮;不传则无按钮,传了 onToggleInfoSidebar 时也没有
onToggleInfoSidebar () => void — 会话信息侧栏按钮,所有会话类型都有,代替群信息按钮;不传则无按钮。@experimental
infoSidebarOpen boolean false 侧栏开没开:按钮的按下态与 aria-expanded
infoSidebarId string — 侧栏元素的 id;开着时作为按钮的 aria-controls
isMuted boolean false 已静音:开关画划线铃铛
onToggleMute () => void — 静音开关回调;不传则无开关
muteDisplay "toggle" | "marker" "toggle" 静音怎么画:"toggle" 常驻铃铛;"marker" 不画铃铛,只在已静音时名字旁出现「已静音」,点它调 onToggleMute(取消静音)。只对群聊生效,其他会话照旧是铃铛。会话信息侧栏打开时用。@experimental
memberCounts { people: number; agents: number } | null null 群里的人数与 Agent 数。群聊且同时给了 onOpenMembers 时,标题下方的人数画成「N 人 · N 个 Agent」两个按钮;否则副标题照给的画。@experimental
onOpenMembers (tab: "people" | "agents") => void — 点了上面两个数中的一个:在成员列表的对应页打开。@experimental
onOpenPeerInfo () => void — 给了 ⇒ 单聊里对端的头像和名字是调它的按钮(打开会话信息侧栏并停在「信息」tab),不再弹对端名片。旁观的单聊也接(与名片不同,侧栏是它的只读视图);与系统成员的私聊、Agent 协作会话和群聊不接。@experimental
onPopOut () => void — 「弹出成浮窗」按钮,排在静音 / 群信息之后;不传则没有。这里能不能开浮窗由你判断
isAgentOwnerDm boolean false 当前用户是单聊里 Agent 的主人:显示主人徽标,启用模型切换
agentModelMemberId string — 要配置模型的 Agent 成员 id,仅 isAgentOwnerDm 时读取
dmPeerModelLabel string | null — 与他人 Agent 单聊时的只读模型名
badge ChatHeaderBadge | null null 标题旁的徽标 { label, bg, color }
trailing ReactNode — 最右侧插槽
rootProps ComponentPropsWithoutRef<"div"> — 根元素额外属性;className 会合并
overlayContainer HTMLElement | null — 浮层和对话框的挂载点

CollabAgent 是 { name: string; online_status?: OnlineStatus | null },OnlineStatus 是 "online" | "starting" | "stopping" | "offline" | "error" | "unknown"(和数据模型里成员的 online_status 相同)。两个类型都从 @openmaxai/chat/header 导出 规划中。

依赖的能力

能力 缺了会怎样
agentConfig 主人单聊里模型切换处显示禁用的占位控件
profileCard 单聊头像和名字不可点,见名片
agentRuns 规划中 没有 Agent 运行入口
适配器的 realtime(typing / presence 信号,ConversationHeader) 没有就不显示「正在输入」,Agent 单聊的在线状态只来自成员资料、不随上下线实时变
适配器的 profiles(ConversationHeader) Agent 单聊的在线状态要等第一声 presence 信号才出现;两样都没有时状态行只在对方计费停机时出现

无障碍

  • 返回按钮、主人徽标按钮和模型切换按钮都有标签。模型切换生效前带 aria-busy,失败用 role="alert" 提示。
  • 群信息按钮只有图标,用 aria-label 给出无障碍名称。规划中
  • 「正在输入」与对端状态不进实时播报区域:变化不播报,读屏用户读到头部时能读到这行文字。

常见问题

信息按钮没出来。 需要 GROUP 会话,并传 onToggleInfoPanel。

模型切换没出来或是灰的。 isAgentOwnerDm 和 agentModelMemberId 都要传。灰色说明宿主没有 agentConfig、loadModelState 返回了 undefined,或状态里 configurable: false、availableModels 为空。