OpenMax
免费试用

浮窗、停靠列与抽屉

在主页面之外打开会话:可拖动的浮窗、右侧停靠列、最小化坞和小屏底部抽屉。用 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(),见安装 · 你自己的抽屉和对话框。