浮窗、停靠列与抽屉
在主页面之外打开会话:可拖动的浮窗、右侧停靠列、最小化坞和小屏底部抽屉。用 SDK 的 ChatDockColumn 与 ChatFloatingSurfaces 挂上即可;要自己拼界面时用 @openmaxai/chat/surfaces 的四个承载面和记录打开了哪些会话的 store。
浮窗、停靠列与抽屉
用户可以在任何页面上打开会话,换页也不关。用 SDK 时挂两个组件,都从 @openmaxai/chat-sdk/react 引入:
| 组件 | 放在哪里 | 显示什么 |
|---|---|---|
ChatDockColumn |
页面布局里,主内容右边的兄弟节点 | 停靠成一列的会话:上方标签条,下方当前会话 |
ChatFloatingSurfaces |
portal 到你给的 container |
浮动、可拖动、可缩放的会话窗,最小化后的头像坞,以及小屏底部抽屉 |
每扇窗里是同一个宿主下的会话头部(紧凑档,最小化、关闭在最右)和消息区,与主页面读写同一份消息:在浮窗里发的消息,主页面打开这个会话时已经在;主页面收到的新消息,浮窗里同时出现。窗里的东西不用你写。
何时使用
- 用户要一边看别的页面一边聊天,例如在 Agent 详情页上和这个 Agent 对话。
- 你想让会话跟着用户走:换页面后,开着的窗还在。
- 只有一个聊天页、不需要在别处打开会话时,不用这些组件。
代码示例
挂载
两个组件各挂一次,放在应用外壳里,在 ChatProvider 之内。必填的属性是 container 和 isCompact。isCompact 是整个页面的布局选择:为真时只有底部抽屉,浮窗、停靠列和坞都不渲染。
app-shell.tsx
import {
ChatDockColumn,
ChatFloatingSurfaces,
ChatProvider,
ChatRoot,
} from "@openmaxai/chat-sdk/react";
export function AppShell({ host, isCompact, children }: AppShellProps) {
const container = typeof document === "undefined" ? null : document.body;
return (
<ChatProvider host={host}>
<ChatRoot overlayContainer="body" style={{ display: "flex", height: "100dvh" }}>
<main style={{ flex: 1, minWidth: 0 }}>{children}</main>
<ChatDockColumn container={container} isCompact={isCompact} />
<ChatFloatingSurfaces container={container} isCompact={isCompact} />
</ChatRoot>
</ChatProvider>
);
}
ChatDockColumn 要做主内容的兄弟节点:它占宽度、把主内容挤窄,不是盖在内容上。没有停靠的会话时它什么都不渲染,不留空栏。
两个组件都放在 ChatRoot 里,从它拿到配色与落点;ChatFloatingSurfaces 先往 container 里放一个带作用域类的节点再渲染进去,ChatDockColumn 就地渲染、自带组件根。同时给 overlayContainer="body",否则主区里的弹出层、从坞拖出的卡片可能压在浮窗下面,原因见安装 · 浮出面与 overlayContainer。用 ChatShadowRoot 代替 ChatRoot 时也一样:两个组件都放在它的 children 里,ChatFloatingSurfaces 在 container 里建一个岛。
- 两个组件都必须在
ChatProvider之内,放在外面渲染时抛错。 - 一页只挂一份
ChatFloatingSurfaces和一份ChatDockColumn:记录打开了哪些窗的 store 一页只有一份,同种的第二份在挂载时抛ChatSdkConfigError。开发态 StrictMode 的「挂、卸、再挂」不算两份。 - 开着的窗(形态、位置、尺寸、标签顺序)与浮窗偏好存在宿主的
instanceScope.storage,键按instanceKey与当前用户分:createChatHost({ storage: "localStorage" })时跨刷新,换人、换instanceKey看不到上一份。刷新后还原出的窗先显示「加载中」、取回会话再画正文;会话没了(被移出群、群被解散、无权访问)时窗静默收掉。坞与停靠标签上的未读、@、静音跟着宿主的会话列表实时变,不用你传。 - 按钮文字(最小化、关闭、展开更多、标签条、调宽把手)经宿主的
i18n能力取;你的t认不得(原样回键或回空串)时退回useTranslation,那时外层要有I18nextProvider,见国际化。
打开一个会话
一次打开(host.openConversation、输入框遥控器、名片「发送消息」、消息里的会话链接、深链)落在主页面还是浮窗,由 createChatHost 的 routeConversation 决定:回 "primary" 交给主页面,回 "detached" 开进浮窗(按偏好开成浮窗或停靠标签,小屏为抽屉;已开着就提到最前),回 "handled" 表示你自己处理了(例如整页跳到聊天页)。不给时:页面挂着 useChatSdkOpenConversation 就落主页面,否则挂着浮窗就开进浮窗。只挂 ChatDockColumn、没挂 ChatFloatingSurfaces 时,开进浮出面的会话一律落成停靠标签,不按偏好开成浮窗(那时没有组件画浮窗)。
host.ts
import { createChatHost } from "@openmaxai/chat-sdk/react";
const host = createChatHost({
adapter,
routeConversation: () => (location.pathname === "/chat" ? "primary" : "detached"),
});
同一个 host 可以并列挂几份 ChatProvider(例如聊天页一份、浮窗层一份),宿主级的事(取当前用户、实时连接、会话列表、自带的看大图)只做一次。
只要浮窗、不要停靠
给 ChatFloatingSurfaces 传 docking={false},页面上不挂 ChatDockColumn。所有会落成停靠标签的入口都改开成浮窗:拖到右缘松手就落在松手的地方,偏好「默认停靠」不生效,刷新前停靠着的会话还原成浮窗。转成浮窗的记录会写回存储,之后改回 true 不会把它们放回停靠。docking={false} 和 ChatDockColumn 挂在同一页时,后挂的那一个抛 ChatSdkConfigError。保留默认的 docking 却不挂 ChatDockColumn 时,停靠的窗没有组件画;开发构建下第一扇停靠的窗会打一条 console.warn,指向这里。
app-shell.tsx
<ChatFloatingSurfaces container={container} isCompact={isCompact} docking={false} />
最小化收回你自己的入口
传 minimizedDock={false} 时 SDK 不挂最小化坞,入口由你自己画:用 useChatSdkMinimizedSurfaces() 读最小化着的窗,点击调它返回的 restore(id)。collapseAnchor 返回你的入口元素,最小化动画在开始那一刻量它的位置、飞过去;返回 null 或元素不在页面上时原地淡出。
minimized-chats.tsx
import { ChatFloatingSurfaces, useChatSdkMinimizedSurfaces } from "@openmaxai/chat-sdk/react";
// 收起的窗放在你自己的工具栏按钮旁边。按钮一直挂着,所以第一次最小化也能飞过去。
function MinimizedChats({ anchorRef }: { anchorRef: RefObject<HTMLButtonElement | null> }) {
const { chats, restore } = useChatSdkMinimizedSurfaces();
return (
<div>
<button ref={anchorRef} type="button">聊天</button>
{chats.map((c) => (
<button key={c.id} type="button" onClick={() => restore(c.id)}>
{c.title}
</button>
))}
</div>
);
}
// 应用外壳:不挂 ChatDockColumn
<ChatFloatingSurfaces
container={container}
isCompact={isCompact}
docking={false}
minimizedDock={false}
collapseAnchor={() => anchorRef.current}
/>;
未读数从 useChatSdkConversationList 的行上按 conversationId 读。
自己拼界面时用
不用 SDK、或者要自己决定窗里放什么时,直接用 @openmaxai/chat/surfaces 的四个承载面:
| 组件 | 放在哪里 | 显示什么 |
|---|---|---|
FloatingChatLayer |
portal 到你给的 container |
浮动、可拖动、可缩放的会话窗 |
ChatDockColumn |
页面布局里,主内容右边的兄弟节点 | 停靠成一列的会话:上方标签条,下方当前会话 |
ChatMinimizedDock |
portal 到 container |
最小化的浮窗,显示为一排头像 |
ChatMobileDrawer |
portal 到 container |
小屏底部抽屉,一次一个会话 |
这四个只画窗框、标签和控件。窗里的正文(消息区、输入框等)由你通过 renderBody 提供,用的就是主页面上那些组件。打开了哪些会话存在 useFloatingChatStore 里,任何地方都可以打开一个窗。
本节的示例用的是 @openmaxai/chat 的组件(承载面、MessageThread、ChatHeader),它们不带样式根:SDK 样式表只作用在 .omx-chat 节点之内,它们自己不带这样的根。所以要像下面自己挂载说的那样,把它们放进 ChatRoot、container 给带 omx-chat 类的节点;窗里的正文同样要你自己包一层带 omx-chat 类的元素(深色时另加 omx-dark),或者自己出样式。
自己挂载
四个组件挂一次,放在应用外壳里,在 ChatProvider 之内。
SDK 的样式表只作用在 .omx-chat 节点之内。把四个组件渲染在 ChatRoot 里,container 给你自己建的、带 omx-chat 类(深色时另加 omx-dark)的节点,不直接给 document.body,渲染在那里的窗才有样式;ChatFloatingSurfaces 替你做的就是这件事。
app-shell.tsx
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import {
ChatDockColumn,
ChatMinimizedDock,
ChatMobileDrawer,
FloatingChatLayer,
installChatSurfaceStorage,
type ChatSurfaceProps,
} from "@openmaxai/chat/surfaces";
installChatSurfaceStorage(window.localStorage);
export function AppShell({ host, isCompact, children }: AppShellProps) {
const surface: ChatSurfaceProps = {
isCompact,
container: typeof document === "undefined" ? null : document.body,
renderBody: (chat) => <ChatWindowBody chat={chat} />,
};
return (
<ChatProvider host={host}>
<div style={{ display: "flex", height: "100dvh" }}>
<main style={{ flex: 1, minWidth: 0 }}>{children}</main>
<ChatDockColumn {...surface} />
</div>
<FloatingChatLayer {...surface} />
<ChatMinimizedDock isCompact={isCompact} container={surface.container} />
<ChatMobileDrawer {...surface} />
</ChatProvider>
);
}
承载面在 ChatProvider 之内时按钮文字先经宿主的 i18n 能力取,认不得再退回 useTranslation;挂在 ChatProvider 之外时只用 useTranslation,外层要有 I18nextProvider。
窗里的正文
chat-window-body.tsx
import { ConversationScope } from "@openmaxai/chat-sdk/react";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { type FloatingChat, useFloatingChatStore } from "@openmaxai/chat/surfaces";
export function ChatWindowBody({ chat }: { chat: FloatingChat }) {
const hydrate = useFloatingChatStore((s) => s.hydrate);
const dropGone = useFloatingChatStore((s) => s.dropGone);
// 刷新后 chat.conversation 是空的:重新取一次。
useEffect(() => {
if (chat.conversation) return;
fetchConversation(chat.conversationId).then((conversation) =>
conversation ? hydrate(chat.id, conversation) : dropGone(chat.id),
);
}, [chat.id, chat.conversationId, chat.conversation, hydrate, dropGone]);
return (
<ConversationScope conversationId={chat.conversationId}>
<MessageThread conversation={chat.conversation ?? null} composerChrome="flush" />
</ConversationScope>
);
}
fetchConversation 是你自己的取数函数。服务端明确答复会话不存在或无权访问时才调 dropGone,它会关掉这个窗;网络失败不要调,窗留着,下次再取。
自己打开一个窗
import { useFloatingChatStore } from "@openmaxai/chat/surfaces";
useFloatingChatStore
.getState()
.open({ conversation, title: agentName, viewportWidth: window.innerWidth });
一个会话只开一个窗:再打开同一个会话,是把已开的窗提到最前、取消最小化,停靠着的就切到它的标签。新窗按偏好开成浮窗或停靠标签,见偏好。title 显示在标题栏和坞里,取到会话之前也用它占位;装了标题来源(setTitleSource)时窗的标题跟来源走,来源答不出才回落 title。viewportWidth 是此刻的视口宽(px):包内不读 window,由你从承载面所在的窗口读了传进来;不传的话新窗不按视口收进屏内(见浮窗)。
你装的 @openmaxai/chat 必须与 @openmaxai/chat-sdk 同一版本。版本不同时 store 有两份:窗开在你那份里,SDK 的承载面读的是另一份,永远看不到它。见安装。
自定义浮窗头部
不传 renderHeader 时,浮窗用自带的标题栏:标题加最小化、关闭按钮。想用和聊天页一样的会话头部,传 renderHeader,并把外壳给的 chrome 用上:
renderHeader: (chat, scope, chrome) =>
chat.conversation ? (
<ChatHeader
/* …必填 props */
conversation={chat.conversation}
mode="compact"
trailing={chrome.controls}
overlayContainer={chrome.overlayContainer}
rootProps={chrome.dragProps}
/>
) : (
<div {...chrome.dragProps}>
{chat.title}
{chrome.controls}
</div>
),
取到会话之前也要渲染 chrome.controls,否则这段时间里窗关不掉。
chrome.controls是最小化和关闭按钮,必须渲染出来,否则这个窗关不掉。chrome.overlayContainer是浮窗给的挂载点,层级高于所有浮窗。头部的弹出层要挂在这里,否则会落在浮窗后面。chrome.dragProps摊到头部根元素上,整条头部就成了拖动手柄。
renderHeader 只用于浮窗。停靠列的标签自带头像和标题,抽屉有自己的标题。
行为
浮窗
- 新窗默认外框 480 × 640 px(含标题栏),位置 (320, 96),每多开一个往右下错开 28 px。传了
viewportWidth且视口不窄于 768 px 时,x 不超过viewportWidth − w − 16(w是窗宽,且 x 不小于 0),整扇窗留在屏内,纵向照常错开。视口窄于 768 px 时承载面显示为抽屉,位置不按视口收,免得在窄屏开的窗拉宽视口后还停在挤出来的位置。开着「记住位置」偏好时,原样用上次移动或缩放过的那个窗的位置和尺寸。 - 拖标题栏移动,拖四边和四角缩放:最小宽 320 px(
MIN_W,外框),正文最小高 280 px(MIN_H),外框最小高 = 280 + 标题栏此刻的高。点窗里任意处把它提到最前。 - 最小化后窗缩向右下角、收进坞;点坞里的头像,窗按原来的位置和尺寸恢复。
- 拖到视口右缘松手,窗变成停靠列里的一个标签;
docking为false时落成浮窗,停在松手的地方。
停靠列
- 上方是标签条,下方是当前标签的会话。标签按最近有新消息的时间排,新的在前;你在收到消息时调
noteActivity(conversationId, at)。 - 一行放不下的标签收进「展开更多」,不出现滚动条。
- 关掉当前标签后,切到它左边的标签;它是最左一个时切到右边的;一个都不剩时整列消失。
- 把标签拖出列外松手,它变回浮窗,尺寸恢复成停靠之前的。
- 列宽可以拖左边缘调整,默认 400 px,范围 320–720 px,且不超过视口宽度的 60%;双击边缘恢复默认。宽度存在偏好的
dockWidth里。
底部抽屉
- 只在
isCompact为真时显示,一次只显示最前面的那个会话。关掉它(下滑或点遮罩)就露出下一个,其他会话一直在 store 里。 - 抽屉高 80% 视口。打开抽屉不会把光标放进输入框,免得弹出软键盘盖住消息。
API
SDK 组件
ChatDockColumn 与 ChatFloatingSurfaces 从 @openmaxai/chat-sdk/react 引入,挂法见挂载。ChatDockColumn 的属性类型是 ChatSdkSurfaceProps,ChatFloatingSurfaces 的是 ChatSdkFloatingSurfacesProps(多后三行):
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
container |
HTMLElement | null |
必填 | portal 的落点,通常是 document.body;null 时浮窗、坞和抽屉不渲染(服务端渲染时传 null)。ChatDockColumn 不 portal,传同一个值即可 |
isCompact |
boolean |
必填 | 小屏布局。为真时只有底部抽屉,浮窗、坞和停靠列都不渲染 |
renderThread |
(props: CwsMessageThreadProps) => ReactNode |
(props) => <CwsMessageThread {...props} /> |
实验性。画每扇窗、停靠标签和抽屉里的消息区,比如在外面包你自己的 Provider、或传 provisioningBlocked。参数是 SDK 本来要传的那份 props(还原出来的窗还在取会话时 conversation 是 null),必须用它们渲染恰好一个 CwsMessageThread。会话头部与窗口控件仍归 SDK |
docking |
boolean |
true |
只给 ChatFloatingSurfaces。false 时不停靠,见只要浮窗、不要停靠 |
minimizedDock |
boolean |
true |
只给 ChatFloatingSurfaces。false 时不挂最小化坞,见最小化收回你自己的入口 |
collapseAnchor |
() => Element | null |
— | 只给 ChatFloatingSurfaces,minimizedDock 为 false 时才调:最小化动画开始那一刻调一次,飞向返回元素的中心;拿不到就原地淡出 |
窗里的正文、窗口头部、记录打开了哪些窗的 store 都由 SDK 管,不从 SDK 导出;最小化着的窗经 useChatSdkMinimizedSurfaces() 读。
组件(自己拼界面时用)
四个组件都从 @openmaxai/chat/surfaces 引入,挂法见自己挂载。除 ChatMinimizedDock 外,属性类型都是 ChatSurfaceProps;组件不读的属性在表里注明。
FloatingChatLayer
未最小化的浮窗,portal 到 container。isCompact 为真、container 为 null 或没有浮窗时不渲染。
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
isCompact |
boolean |
必填 | 为真时不渲染 |
renderBody |
(chat: FloatingChat, scope: ChatSurfaceScope) => ReactNode |
必填 | 窗里的正文,scope 为 "floating-chat" |
renderHeader |
(chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfaceHeaderChrome) => ReactNode |
— | 浮窗头部;不传时用自带的标题栏(标题加最小化、关闭按钮),见自定义浮窗头部 |
renderPane |
(chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfacePaneChrome) => ReactNode |
— | 头部和正文一起画(同一宿主);给了就不再调 renderHeader / renderBody。presentation 为 "float" |
container |
HTMLElement | null |
必填 | portal 的落点,通常是 document.body;null 时不渲染(服务端渲染时传 null) |
collapseAnchor |
() => Element | null |
— | 最小化动画飞向哪;不给飞向坞。点最小化那一刻调一次,拿不到可用的元素就原地淡出 |
ChatDockColumn
停靠列,就地渲染在页面布局里,不 portal,要做主内容的兄弟节点。isCompact 为真或没有停靠的会话时不渲染;拖着浮窗到视口右缘时,先画出一条和列同宽的放置带。
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
isCompact |
boolean |
必填 | 为真时不渲染 |
renderBody |
(chat: FloatingChat, scope: ChatSurfaceScope) => ReactNode |
必填 | 当前标签的正文,scope 为 "docked-chat" |
renderHeader |
(chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfaceHeaderChrome) => ReactNode |
— | 不读。停靠标签自带头像和标题 |
renderPane |
(chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfacePaneChrome) => ReactNode |
— | 当前标签的头部和正文一起画,头部在标签条下面;presentation 为 "docked",不给窗口控件。不给 ⇒ 只调 renderBody |
container |
HTMLElement | null |
必填 | 不读。传和其他三个组件同一个值即可 |
unreadCountOf |
(conversationId: string) => number |
— | 标签右上角的未读数,见 ChatSurfaceProps |
unreadMentionOf |
(conversationId: string) => "direct" | "all" | null |
— | 标签头像左下角的 @ 圆标,见 ChatSurfaceProps |
mutedOf |
(conversationId: string) => boolean |
— | 静音会话的未读数与 @所有人 圆标转灰,见 ChatSurfaceProps |
ChatMinimizedDock
收进坞的浮窗,显示成一排头像,portal 到 container。isCompact 为真、container 为 null 或没有最小化的浮窗时不渲染;右侧有停靠列时让开它。
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
isCompact |
boolean |
必填 | 为真时不渲染 |
container |
HTMLElement | null |
必填 | portal 的落点;null 时不渲染 |
unreadCountOf |
(conversationId: string) => number |
— | 头像右上角的未读数,见 ChatSurfaceProps |
unreadMentionOf |
(conversationId: string) => "direct" | "all" | null |
— | 头像左下角的 @ 圆标,见 ChatSurfaceProps |
mutedOf |
(conversationId: string) => boolean |
— | 静音会话的未读数与 @所有人 圆标转灰,见 ChatSurfaceProps |
ChatMobileDrawer
小屏底部抽屉,一次显示最前面的那个会话,portal 到 container。isCompact 为假、container 为 null 或没有打开的会话时不渲染。
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
isCompact |
boolean |
必填 | 为假时不渲染 |
renderBody |
(chat: FloatingChat, scope: ChatSurfaceScope) => ReactNode |
必填 | 抽屉里的正文,scope 为 "floating-chat" |
renderHeader |
(chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfaceHeaderChrome) => ReactNode |
— | 不读。抽屉的标题是会话标题 |
renderPane |
(chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfacePaneChrome) => ReactNode |
— | 头部和正文一起画,头部替掉可见的标题(标题留给读屏);presentation 为 "drawer",窗口控件是一颗关闭钮。不给 ⇒ 只调 renderBody |
container |
HTMLElement | null |
必填 | portal 的落点;null 时不渲染 |
ChatSurfaceProps
FloatingChatLayer、ChatDockColumn、ChatMobileDrawer 的属性类型。三个组件各读哪几项见上面各自的表。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
isCompact |
boolean |
必填 | 小屏布局。为真时只有底部抽屉 |
renderBody |
(chat: FloatingChat, scope: ChatSurfaceScope) => ReactNode |
必填 | 一个会话的正文 |
renderHeader |
(chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfaceHeaderChrome) => ReactNode |
— | 浮窗头部;不传时用自带的标题栏 |
renderPane |
(chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfacePaneChrome) => ReactNode |
— | 一个会话的头部和正文一起画,两者在同一个宿主下。浮窗、停靠列、抽屉都调它,给了就不再调 renderHeader / renderBody;外壳交的窗框见 ChatSurfacePaneChrome |
container |
HTMLElement | null |
必填 | portal 的落点,通常是 document.body;null 时 portal 的组件不渲染 |
unreadCountOf |
(conversationId: string) => number |
— | 停靠标签和坞里的未读数,由你按自己的未读来源算。不传时用打开窗口那一刻 conversation.unread_count 的值(旁观会话为 0),之后不会变 |
unreadMentionOf |
(conversationId: string) => "direct" | "all" | null |
— | 停靠标签和坞里头像上的 @ 圆标:"direct" 有人 @你,"all" @所有人,null 不画;两种长得一样,读屏念法不同。不传时用打开窗口那一刻 conversation.unread_mention 的值(旁观会话不画),之后不会变 |
mutedOf |
(conversationId: string) => boolean |
— | 会话是否静音:静音时未读数和 "all" 的 @ 圆标转灰,"direct" 仍是红色。不传时用打开窗口那一刻 conversation.muted 的值(旁观会话不算静音) |
ChatSurfaceScope 是 "floating-chat" | "docked-chat",表示正文在哪种承载面里(抽屉里也是 "floating-chat"),只用于区分和排查,不影响行为。
ChatSurfaceHeaderChrome:
| 字段 | 类型 | 说明 |
|---|---|---|
controls |
ReactNode |
最小化和关闭按钮,必须渲染 |
overlayContainer |
HTMLElement | null |
头部弹出层的挂载点。浮窗给的是层级高于所有浮窗的那个;停靠列与抽屉给 null,弹出层用默认落点(body) |
dragProps |
{ onPointerDown, className } |
可选。摊到头部根元素上,作为拖动手柄;只有浮窗有 |
frameClassName |
string |
可选。叠到头部根元素上的窗框类;停靠标签与抽屉给的是只有底边、无圆角的平栏 |
ChatSurfacePaneChrome(renderPane 拿到的窗框):
| 字段 | 类型 | 说明 |
|---|---|---|
presentation |
"float" | "docked" | "drawer" |
这扇窗此刻是浮窗、停靠标签还是手机抽屉。停靠标签上已有头像和名字,头部不必再画 |
header |
ChatSurfaceHeaderChrome |
同上,给头部用。controls 按呈现给:浮窗是最小化 + 关闭,抽屉是关闭(下滑照样能关),停靠标签为 null;dragProps 只有浮窗有 |
bodyFrame |
(body: ReactNode) => ReactNode |
正文容器(浮窗里占满标题栏以下的剩余高度、裁切、把输入框聚焦请求交进去),必须用它包正文。头部与 bodyFrame(...) 必须是窗根的直接子项,或中间只隔 display: contents 的节点;多包一层普通 div 时正文按内容撑高、溢出窗外,不报错 |
FloatingChat
store 里的一个窗:
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string |
窗 id,floating-chat-<conversationId> |
conversationId |
string |
|
conversation |
ChatConversation |
可选。会话本身;不持久化,刷新后为空,要用 hydrate 补上 |
title |
string |
标题栏和坞里的文字 |
x、y、w、h |
number |
位置和外框尺寸(px,相对视口;h 含标题栏) |
z |
number |
叠放次序,大的在上 |
mode |
ChatSurfaceMode |
"list" | "float" | "docked" |
minimized |
boolean |
可选。只对 "float" 有意义:收进了坞 |
dockOrder |
number |
可选。停靠的先后,没有消息时间时用来排标签 |
restore |
{ x, y, w, h } |
可选。停靠或最小化之前的位置和尺寸 |
lastActivityAt |
string |
可选。最近一次有新消息的时间(ISO),由 noteActivity 写 |
useFloatingChatStore
一个 zustand store。在组件里用 useFloatingChatStore((s) => s.chats) 订阅,在组件外用 useFloatingChatStore.getState()。
| 成员 | 说明 |
|---|---|
chats |
FloatingChat[],打开的全部会话 |
dockActiveId |
停靠列当前标签的窗 id;没有停靠的会话时为 null |
open({ conversation, title?, viewportWidth? }) |
打开会话;已开就提到最前。title 不给时取会话的 name。viewportWidth(px)让新窗留在视口内 |
close(id) |
关掉一个窗 |
focus(id)、move(id, x, y)、resize(id, w, h) |
提到最前、移动、缩放(w、h 是外框;低于 MIN_W、MIN_H 时按它们夹,store 不知道标题栏多高,所以这里按外框夹) |
dock(id)、undock(id, x, y) |
停靠到右侧列;从列里拖出到某点,尺寸恢复成停靠之前的 |
minimize(id)、restoreFromDock(id) |
收进坞;从坞恢复。停靠的标签不能最小化 |
setDockActive(id) |
切换停靠列的当前标签 |
hydrate(id, conversation) |
刷新后把取到的会话补回去 |
dropGone(id) |
服务端答复会话不存在或无权访问时,关掉这个窗 |
clearDetached() |
关掉全部窗(浮窗、停靠标签、坞、抽屉),主聊天不受影响。换组织、登出时用 |
setTitleSource(source) |
装上窗标题的来源(ChatSurfaceTitleSource),返回卸载函数;已装着一份时再装会抛错。装了之后,存下的 title 只是来源答出之前、以及来源答不出时的占位;来源的答案不写回。@experimental |
noteActivity(conversationId, at) |
这个会话有新消息(at 是 ISO 时间)。只会往后推,没有这个会话的窗时什么都不做 |
composerFocus |
待处理的输入框聚焦请求 { chatId, seq },没有时为 null 或不存在。不持久化 |
requestComposerFocus(id)、settleComposerFocus(seq) |
请求把光标放进这个窗的输入框;正文处理完后清掉请求。承载面自己会调,一般不用你调 |
偏好
useChatPreferencesStore,和窗一起持久化:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
defaultSurface |
ChatSurfacePreference("float" | "docked") |
"float" |
open 新开的会话是浮窗还是停靠标签 |
rememberGeometry |
boolean |
true |
新窗用上次的位置和尺寸。关掉时仍然记录,只是新窗不用 |
lastGeometry |
RememberedGeometry | null |
null |
上次的 { x, y, w, h }(w、h 是外框) |
dockWidth |
number | null |
null |
用户拖出来的停靠列宽度;null 是默认 400 px |
infoSidebarOpen |
boolean |
false |
主区会话旁的会话信息侧栏开没开(宽屏;整台设备一份,不按会话分) |
infoSidebarWidth |
number | null |
null |
用户拖出来的会话信息侧栏宽度;null 是默认 380 px |
sendShortcut |
SendShortcut("enter" | "mod-enter") |
"enter" |
只存在这里,输入框不读它。要让这个设置生效,在宿主的 composerPreferences.sendShortcut 里返回它,见宿主能力 · composerPreferences |
对应的修改方法:setDefaultSurface、setRememberGeometry、setSendShortcut、rememberGeometryNow、setDockWidth、setInfoSidebarOpen、setInfoSidebarWidth。
持久化
| 导出 | 说明 |
|---|---|
installChatSurfaceStorage(storage) |
应用启动时调一次,传入 ChatSurfaceStorage(localStorage 就可以)。会重新载入两个 store |
setChatSurfaceStorage(storage) |
只换存储,不重新载入 |
clearPersistedChatSurfaces(storage) |
从 @openmaxai/chat/surfaces/store 引入。直接删掉存储里的窗,不管有没有载入过;换账号时用 |
不调用时只存在内存里,刷新后窗都没了。存储键是 cws-floating-chats(窗)和 cws-chat-preferences(偏好)。存的是窗的 id、标题、位置、尺寸和状态,不存会话本身和消息:会话刷新后由你重新取(hydrate),被删或被移出的会话不会留下一个打不开的窗。
依赖的能力
SDK 的两个组件要在 ChatProvider 之内,窗里的正文用到的能力与主页面的会话头部、消息区相同,见会话头部、消息区。自己拼界面时,承载面本身除按钮文案先问宿主的 i18n 外,不读宿主的其他能力;窗里的正文用到哪些能力由你放进去的组件决定。承载面自己依赖的是下面几样:
| 依赖 | 缺了会怎样 |
|---|---|
宿主的 i18n 能力,或 I18nextProvider |
在 ChatProvider 之内时按钮文字先问 i18n,认不得的退回 useTranslation;两边都取不到时显示成键名。见国际化 |
installChatSurfaceStorage |
窗和偏好只存在内存里,刷新后窗都没了。见持久化 |
container |
为 null 时浮窗、坞和抽屉不渲染,停靠列照常 |
无障碍
- 最小化、关闭按钮和坞里的头像都有无障碍名称(坞里的头像用会话标题)。
- 停靠标签条是
role="tablist",标签是role="tab",带aria-selected;用←/→在标签间切换,到头会绕回。「展开更多」按钮带aria-expanded。 - 停靠列的宽度把手是
role="separator",在 Tab 顺序里,带aria-valuenow、aria-valuemin、aria-valuemax,用←/→每次调 16 px。 - 浮窗的移动和缩放只能用指针操作,没有键盘方式。窗的位置不影响功能,关闭和最小化都有按钮。
- 抽屉的标题是会话标题。给了
renderPane时可见的标题换成会话头部,标题仍留给读屏;头部带一颗关闭钮,不用下滑手势也能关。
常见问题
刷新后窗还在,但里面是空的。
会话本身不持久化。在正文里发现 chat.conversation 为空时重新取,取到后调 hydrate,见窗里的正文。
刷新后窗都没了。
没有调 installChatSurfaceStorage,默认只存在内存里。
浮窗里点开的菜单或弹窗跑到了窗后面。
自定义头部时,把 chrome.overlayContainer 传给头部(ChatHeader 的 overlayContainer)。正文里的弹出层承载面会自己处理。
停靠列盖在了内容上,而不是把内容挤窄。
ChatDockColumn 要和主内容放在同一个 flex 行里做兄弟节点,不要 portal 出去或绝对定位。
页面上我自己的抽屉或对话框,一点浮窗就关了。
在它的 onInteractOutside 里调 isChatSurfaceInteraction(event),回 true 就 preventDefault(),见安装 · 你自己的抽屉和对话框。
