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往前取的读接口。
