OpenMax
免费试用

React 绑定

@openmaxai/chat-store/react:把仓库交给组件的 ChatStoreProvider,只订阅、取数交给取数协调器的 useMessages、useMessage,以及 useChatStore。

React 绑定

@openmaxai/chat-store/react 入口的导出:把仓库交给组件的 Provider,以及读仓库的 hook。状态、在宿主里怎么接和全部导出的索引见概览。本页的 hook 是应用代码将来读仓库用的 hook 在仓库包里的实现(将由 SDK 再导出),目前只有其中的 useMessages、useMessage、useConversation 和 useUnread,另有按 client_msg_id 读一条的 useMessageByClientId,和读会话列表的 useConversationList。

hook 只订阅、不取数:ChatStoreProvider 用收到的参数建一个根入口的取数协调器,hook 用 useSyncExternalStore 订阅它给的读取状态,挂载、卸载、翻页和重试都交给它。所以只在读的那部分变了时重渲染,取数行为和不用 React 时一样。它们不含界面。

chat-store-provider.tsx

import { createChatGapFillScheduler, createChatStore } from "@openmaxai/chat-store";
import { ChatStoreProvider, useMessages } from "@openmaxai/chat-store/react";

// 每个宿主(每个登录用户)一份。
const store = createChatStore();
const gapFill = createChatGapFillScheduler({ store, source: host.messaging });

export function ChatRoot({ children }: { children: React.ReactNode }) {
  return (
    <ChatStoreProvider store={store} source={host.messaging} gapFill={gapFill}>
      {children}
    </ChatStoreProvider>
  );
}

function Thread({ conversationId }: { conversationId: string }) {
  const { messages, status, hasOlder, loadOlder } = useMessages(conversationId);
  // …
}

重连、回到前台和 messages 信号仍由你交给补洞调度(gapFill.reconnected() 等),见概览 · 在宿主里怎么用。

ChatStoreProvider

function ChatStoreProvider(props: ChatStoreProviderProps): ReactElement;

把仓库交给下面的组件:用收到的参数建一个取数协调器,本页的 hook 经它读和取。本页的 hook 必须放在它里面,不在时抛错。store、source、gapFill、requestCache 换了对象、newerPageLimit 换了值时重建协调器,取数状态从头记。

ChatStoreProviderProps

interface ChatStoreProviderProps extends ChatThreadLoaderOptions {
  conversations?: ChatConversationStore<ChatStoreConversationRow>;
  readCursors?: ChatReadCursorStore;
  children?: ReactNode;
}

建取数协调器的参数(见 ChatThreadLoaderOptions),加上会话的 hook 读的会话仓库 conversations(可选,不给时那几个 hook 抛错)和子组件 children。

useChatStore

function useChatStore(): ChatStore;

拿到 Provider 交下来的仓库,例如经 dispatch 写入。

useMessages

function useMessages(conversationId: string): UseMessagesResult;

读一个会话的消息窗口,带翻页。读取状态是协调器的 getThread,挂载时调 openThread、卸载时离开,翻页和重试也交给协调器(各自的行为见 ChatThreadLoader)。在 React 里看得到的是:

  • 第一拍就准。 第一次渲染就按仓库此刻的数据给,不等 effect:已加载过的会话直接是 ready 和已有的消息,没加载过的是 loading。「仓库里有没有这个会话」这类渲染那一拍就要知道的判断,看第一次渲染的 status 即可。
  • 订阅即打开。 某个会话的第一个 useMessages 挂载算作打开,最后一个卸载时离开;StrictMode 的「卸载又立刻挂载」不会关了又开。
  • 同一份数据只取一次。 几个组件同时读同一个会话,只取一窗、只补一次洞;loadOlder、loadNewer 同时调几次也只取一次。
  • 只在读的那部分变了时重渲染。 别的会话变了、没改到数据的写入(比如视图提示)都不重渲染;一次写入改了多条消息只重渲染一次。

UseMessagesResult

interface UseMessagesResult extends ChatThreadReadState {
  retry(): void;
  loadOlder(): Promise<void>;
  loadNewer(): Promise<void>;
  jumpTo(target: ChatMessageTarget, options?: ChatJumpOptions): Promise<ChatJumpResult>;
}

useMessages 的返回值,没有变化时是同一个对象。字段同 ChatThreadReadState,另加四个方法:

方法 说明
retry 协调器的 retry:重做失败的那一步;没有失败的时什么都不做。
loadOlder 协调器的 loadOlder:往更早翻一页。失败时 reject,已有消息不动。
loadNewer 协调器的 loadNewer:往更新翻一页。失败时 reject,已有消息不动。
jumpTo 协调器的 jumpTo:跳到一条消息,不在窗口里时换入围着它的一窗,见跳到一条消息。目标可以是服务端那条的 id,也可以是自己发出的那条的 client_msg_id。

useMessage

function useMessage(conversationId: string, messageId: string): UseMessageResult;

读一条消息,例如画引用条。读取状态是协调器的 getMessage,挂载时调 openMessage、卸载时离开(行为见 ChatThreadLoader)。

  • 这条在会话的内存窗口里时直接返回仓库里的那条,随更新重渲染;这条没变时不重渲染。
  • 不在时由协调器调 source.loadMessage 取一次,取回的那条存在请求结果缓存里,不随实时更新变化;之后这条进了窗口,就换成仓库里那条。

useMessageByClientId

function useMessageByClientId(conversationId: string, clientMessageId: string): UseMessageResult;

按 client_msg_id 读自己发出的那条,例如发出后跟着它的发送状态、等它换成服务端那条。读取状态是协调器的 getMessageByClientId,挂载时调 openMessageByClientId、卸载时离开(行为见按 client_msg_id 读一条)。

  • 还没换成服务端那条时返回本端那条(发送中、失败、被拦,或已确认还没对上),随它的状态重渲染。
  • 换上之后返回服务端那条,同 useMessage:在窗口里时是仓库里那条,不在时按它的 id 取一次。
  • 仓库里没有这个 client_msg_id 时 status 为 ready、message 为 undefined。

UseMessageResult

interface UseMessageResult extends ChatMessageReadState {
  retry(): void;
}

useMessage、useMessageByClientId 的返回值,没有变化时是同一个对象。字段同 ChatMessageReadState;retry 是协调器的 retryMessage(useMessageByClientId 是 retryMessageByClientId),取失败后再取一次,没有失败时什么都不做。

useConversationList

function useConversationList<C extends ChatStoreConversationRow = ChatStoreConversationRow>(): UseConversationListResult<C>;

读会话列表,带翻页。读取状态是会话仓库的 getList,挂载时调 openList、卸载时离开,翻页、重取、重试也交给会话仓库(行为见 ChatConversationStore)。第一个读者挂载时取第一页;列表失效时有读者就重取。只在列表的读取状态变了时重渲染:别的会话按 id 写入不重渲染。

ChatStoreProvider 要给 conversations(createChatConversationStore 建的),否则抛错;useConversation、useUnread 同。类型参数 C 是会话行的完整形状,不给时按 ChatStoreConversationRow。

UseConversationListResult

interface UseConversationListResult<C extends ChatStoreConversationRow> extends ChatConversationListState<C> {
  retry(): void;
  loadMore(): Promise<void>;
  refetch(): Promise<void>;
}

useConversationList 的返回值,没有变化时是同一个对象。字段同 ChatConversationListState;retry 是会话仓库的 retryList,loadMore、refetch 同会话仓库的同名方法。

useConversation

function useConversation<C extends ChatStoreConversationRow = ChatStoreConversationRow>(conversationId: string): UseConversationResult<C>;

读一个会话。读取状态是会话仓库的 getConversation,挂载时调 openConversation、卸载时离开,重试是 retryConversation。在仓库里(列表取到的、按 id 写进来的)时直接返回,置顶、隐藏、未读等变了时重渲染;不在当前默认列表里时(包括行缓存还在、但重取已把它从列表里去掉)由会话仓库调读接口的 loadConversation 取一次,取到后按 id 写进仓库,不改列表的内容和顺序;listed 告诉你它在不在列表里。取回 undefined(不存在、看不到)时 status 为 ready、conversation 为 undefined,读者都离开后再来会再取;读接口没有 loadConversation 时等列表第一页,到了之后不在里面才是 ready、conversation 为 undefined。

UseConversationResult

interface UseConversationResult<C extends ChatStoreConversationRow> extends ChatConversationReadState<C> {
  retry(): void;
}

useConversation 的返回值,没有变化时是同一个对象。字段同 ChatConversationReadState;retry 是会话仓库的 retryConversation,按 id 取失败后再取一次,没有失败时什么都不做。

useUnread

function useUnread(conversationId: string): ChatUnreadState;

读一个会话的未读(ChatUnreadState):count、mention、lastReadSeq。只订阅、不取数:仓库里没有这个会话时 count 为 0。只在这三格变了时重渲染。

useReadCursors

function useReadCursors(conversationId: string): ChatReadCursorState;

读一个会话的已读游标(ChatReadCursorState):自己的已读位置和回执用的别人的游标。只订阅、不取数:打开会话、取快照由取数层(createChatReadCursorLoader)做。只在这个会话的游标变了时重渲染。ChatStoreProvider 要给 readCursors(createChatReadCursorStore 建的),否则抛错。

与 SDK 目标的差别

目标是由 SDK 再导出这些 hook,本页按现有源码写。两边目前的差别:

  • 只有 useMessages、useMessage、useConversation、useUnread(另有 useMessageByClientId、useConversationList)。 其余 hook 要读的数据(未读总数、Agent 运行、正在输入、连接状态)仓库里还没有。
  • 会话的 hook 带类型参数。 仓库包不认识宿主的 ChatConversation,useConversationList、useConversation 的会话行类型由调用方给;SDK 再导出时定成 ChatConversation。
  • error 是读接口 reject 的原样值。 仓库包这一层不包装;@openmaxai/chat-sdk/react 再导出这些 hook 时由 SDK 把它包成 SDK 的错误类型,那一步不在本包。
  • Provider 是仓库包自己的 ChatStoreProvider。 SDK 的 Provider 接上仓库之后,hook 放在 SDK 的 Provider 里即可。
  • 最后一个读者卸载后,内存里的消息不卸。 只关掉补洞,「只保留水位」还没做。
  • 往上翻读不了本机存储。 仓库还不读写 ChatStorage,更早一端被卸掉后只能等按 seq 往前取的读接口。