输入框遥控器
从聊天之外的页面和模块操作聊天输入框:写入内容、挂建议条、锁住输入框、打开会话。每个宿主一个,即 host.controller。
输入框遥控器
页面和其他模块(例如 Issue 详情的「讨论此 Issue」、页面建议条)经输入框遥控器操作聊天输入框:先说清楚操作哪条会话,再写内容、挂建议条、锁输入框、聚焦或打开会话。调用方不碰编辑器,内容是一串片段,不是 HTML。
createChatHost 造的每个宿主持有一个遥控器,就是 host.controller。ChatProvider 把它交给子树:在 Provider 之内 useChatController() 拿到的是同一个对象,CwsMessageThread 挂上会话时把输入框登记进去。同一页两个宿主的遥控器互不影响。hook 和类型从 @openmaxai/chat/controller 转出:hook 在 @openmaxai/chat-sdk/react,类型在 @openmaxai/chat-sdk。
何时使用
- 聊天之外的页面要往某条会话的输入框里放内容,例如把一个 Issue 的引用插进和 Agent 的私聊。
- 页面要在某条会话的输入框上方挂几项建议,点了填进输入框。
- 某段流程进行中要暂时锁住输入框。
只在聊天组件内部操作输入框时用不到它。
怎么用
discuss-issue.tsx
import { useChatControllerScope } from "@openmaxai/chat-sdk/react";
function DiscussIssueButton({ conversationId, issue }: Props) {
const scope = useChatControllerScope("discuss-issue");
const discuss = async () => {
const handle = scope.conversation({ conversationId });
const result = await handle.composer.insert(
[{ type: "work-reference", item: issue }],
{ newParagraph: true },
);
if (result.ok) await handle.composer.focus();
};
return <button onClick={discuss}>讨论此 Issue</button>;
}
- 会话挂着(
CwsMessageThread正显示它):直接写进输入框。 - 没挂着:先写进宿主的
drafts,再经host.openConversation打开,与它落在同一处:交给页面用useChatSdkOpenConversation挂的监听者,消息区挂上后输入框里就是写入后的内容。 - 没有地方接这次打开(页面没挂
useChatSdkOpenConversation):草稿已写,结果是{ ok: false, kind: "not_found", reason: "not_open" };之后在本宿主挂上这条会话,输入框里照样是写入后的内容。 - 所有操作都不抛,结果是
{ ok: true }或{ ok: false, kind, reason },kind与ChatSdkError的种类同一套。 - 宿主
dispose()时遥控器现有的作用域都结掉:登记的锁与建议撤掉,在等的操作得cancelled / scope_disposed。收摊不是终结:在 effect 清理里 dispose、又被重新挂上的宿主(React StrictMode、<Activity>),页面模块的作用域随它们的 effect 复活,锁与建议重新登记。适配器的作用域结束(换用户、换组织)只结掉在等的操作。
位置与当前会话:消息区挂着的会话报 "primary";用户在消息区里点、键盘输入或聚焦之后,{ active: true } 指的就是消息区此刻那条会话。{ memberId } 寻址经适配器的 directMessages 找或建私聊再打开;适配器没有这一格时回 unavailable / open_failed。
hook
useChatController
本宿主的遥控器,即 host.controller。要在 ChatProvider 之内调用。
useChatControllerScope
带主人的作用域。主人名用于来源记录;卸载时撤销它登记的锁与建议,结束它在等的操作。
useChatConversationHandle
一条会话的句柄和它此刻的位置(primary,或没开着为 null)。
useChatConversationState
一个地址此刻解析到的会话与位置,随打开、关闭变化。
useChatLock
声明式锁住输入框:reason 为 null 时不锁,卸载或 reason 变了撤掉原来那把。
useChatSuggestions
声明式在一条会话的输入框上方登记建议条;按内容比对,每次渲染传新数组不会重登记。
类型
从 @openmaxai/chat-sdk 引入(只有类型,不依赖 React):ChatController、ChatControllerScope、ChatConversationHandle、ChatComposerHandle、ChatSuggestionsHandle、ChatAddress、ChatAddressOptions、ChatOpenTarget、ChatOpenResult、ChatComposerContent、ChatComposerPart、ChatComposerPartType、ChatInsertPosition、ChatSuggestion、ChatSuggestionAction、ChatSuggestionContext、ChatSuggestionOptions、ChatControllerResult、ChatControllerFailure、ChatControllerErrorKind、ChatControllerReason、ChatReadOnlyReason、ChatControllerSnapshot、ChatControllerEvent、ChatConversationState、ChatConversationPlacement。
