OpenMax
免费试用

输入框遥控器

从聊天之外的页面和模块操作聊天输入框:写入内容、挂建议条、锁住输入框、打开会话。每个宿主一个,即 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。