OpenMax
免费试用

输入框插件

输入框插件能做的四件事:触发符和候选面板、工具条按钮、内容节点、发送时的结构化数据,以及它需要的宿主能力。

输入框插件

输入框插件是用 defineComposerPlugin 定义的一个对象,类型是 ComposerPlugin,两者都从 @openmaxai/chat/composer 导出。除了 id,每个字段都可以不写:写了哪个字段,插件就参与哪件事。一个插件可以同时做几件,例如 @ 提及四件都做。

能力 字段 做什么 mention work-reference
触发符和候选面板 trigger 输入某个字符后弹出候选,选中后换成内容 @ #
工具条按钮 toolbar 在工具条上或 + 菜单里放按钮 有 有
内容节点 nodes 往输入框里插入一整块内容,如 @ 胶囊、工作项标签 mention work_reference
发送时的结构化数据 sendKeys + contributeSend 发送时除了正文再带一份结构化数据 mentions —

另外,每个插件用 requiredPorts 写明它要宿主提供哪些能力。id 是插件的名字,同一套插件里不能重复,报错信息靠它指出是哪个插件。

触发符和候选面板

trigger 让插件响应一个触发字符:用户在行首或空白后输入它,SDK 把它和之后输入的文字(到下一个空白为止)交给插件查候选,在光标旁弹出插件的面板。

字段 说明
chars 触发字符,每项恰好一个字符。同一个触发符的全角写法放在同一个数组里,如 ["@", "@"]
search(query, ctx) query 是触发符之后已输入的文字。返回候选数组,可以同步返回,也可以返回 Promise;返回空数组就不弹面板。ctx 里有 conversationId、readOnly 和宿主 host
insert(view, range, candidate) 选中一条候选后,把触发符连同已输入的文字(range)整段换掉。view 是 ProseMirror 的 EditorView
Panel 候选面板组件,可以是 React.lazy(...)
keepPanelOpenWhenEmpty 可选。search 返回空数组时面板照样打开,由面板自己填内容。@ 用它在组织目录里找不在会话里的人
listbox 可选。声明 Panel 画出一个 role="listbox"(id 用收到的 listboxId),每条候选一个 role="option"(id 用 optionId(index),带 aria-selected)。面板开着时输入框随之带上 aria-controls 和指向高亮选项的 aria-activedescendant,读屏能跟着 ArrowUp / ArrowDown 念出高亮。段标题、状态行不能用这些 id

每条候选要有一个本次结果里唯一的 id,其余字段由你的面板和 insert 自己解释。

面板收到的属性:

属性 说明
candidates 要显示的候选。面板画出的行必须和它一一对应,ArrowUp / ArrowDown 和 Enter 按下标走
query 和交给 search 的是同一个值
activeIndex、onActiveIndexChange 高亮的那一行;鼠标悬停时调用后者
onSelect 点击某一行时调用,参数是下标
host 宿主,只读 requiredPorts 里列出的能力
setCandidates 面板要增减行时(例如展开一组),把新的完整列表交回;高亮按 id 跟随
registerKeyHandler 可选。面板要处理 ArrowLeft / ArrowRight 时注册,返回 true 表示已处理;卸载时传 null 注销
listboxId、optionId 只在触发符声明了 listbox 时给:列表元素的 id,以及第 index 行选项元素的 id

ArrowUp、ArrowDown、Enter、Escape 由 SDK 处理,焦点始终留在输入框里。两个插件声明同一个触发字符时,组装插件集时抛错,SDK 不替你挑。

工具条按钮

toolbar 是一组按钮,按插件顺序、插件内按声明顺序排在工具条上。每个按钮:

字段 说明
id 按钮 id,同一套插件里不能重复;指定按钮位置时也用它
icon 图标组件,收到 className;可以是 React.lazy(...)
titleKey 提示文字的翻译 key,经宿主的 i18n 能力翻译
menuLabelKey、menuLabel 可选。收进 + 菜单时那一行的文字:menuLabel 是现成文字,menuLabelKey 是翻译 key;都不给时用 titleKey
defaultPlacement 可选。"bar"(直接显示在工具条上,默认)或 "plus-menu"(收进 + 菜单)
disabled 可选。为真时在菜单里照样显示,但置灰
onActivate(ctx) 点击时做的事。ctx.insertText(text) 往光标处插入文字;插入的是触发符时,候选面板会跟着打开。插触发符的按钮应改用 ctx.activateTrigger(char):光标前已经是这个触发符、后面还没打字时,它只重新打开候选面板,不再插第二个
Panel 可选。按钮自己的面板,点击时打开或关上,收到 close;可以是 React.lazy(...)。面板要用宿主能力时调用 useChatHost()

onActivate 和 Panel 至少给一个;都给时先执行 onActivate 再打开面板。

按钮最终放在哪里:ChatProvider 的 toolbarPlacement 按按钮 id 指定的位置优先,其次是插件的 defaultPlacement,都没有就是 "bar"。

输入框展开时,放在工具条上的按钮挪到展开后的底栏,收进 + 菜单的仍在 + 菜单里;按钮本身和 onActivate、Panel 不变,插件不用为展开写任何东西。规划中

内容节点

nodes 往输入框的文档结构里加节点类型,键是节点名,值是 ProseMirror 的节点规格,外加两个字段:

字段 说明
toText 这块内容变成纯文本时是什么。发送的正文和复制到剪贴板的文字都用它
chip 为真时这块内容是一个整体:光标整块跳过,退格一下整块删掉

草稿以 HTML 保存,节点靠规格里的 parseDOM / toDOM 存进去、读回来。节点由插件自己的 insert 或按钮插入。

节点名不能和输入框自带的节点(doc、paragraph、text、hard_break)或别的插件重复,重复时组装插件集时抛错。

发送时的结构化数据

插件要在发送时除了正文再带一份结构化数据,就同时写 sendKeys 和 contributeSend:

  • contributeSend(doc) 在发送时读输入框里的内容,返回一个对象,键是字段名;这次没有就返回 undefined。值为 undefined 的键不发送。
  • sendKeys 事先列出 contributeSend 会返回的键。写了 contributeSend 就必须写 sendKeys;返回了没列出的键,发送时抛错。

这些键会作为发送请求(SendMessageInput)的字段交给宿主的 messaging.sendMessage。能带哪些键由 SDK 的转发名单决定,名单里是 mentions;sendKeys 里列了别的键,组装插件集时抛错。两个插件返回同一个键,发送时抛错。

让插件带自己定义的字段还没有设计。规划中

需要的能力

requiredPorts 列出插件需要的宿主能力,写的是 ChatHost 的字段名,例如 ["workItems"]。插件只应读取这里列出的能力:search 的 ctx.host、候选面板的 host、按钮面板里的 useChatHost() 都一样。

宿主缺其中任何一项,ChatProvider 就不装这个插件,其余照常。

内置插件需要的能力见内置插件。

声明要是现成的值

nodes、trigger、toolbar、sendKeys、requiredPorts 在定义插件时就必须是现成的值,不能是函数或 Promise,组装插件集时会检查。这样插件需要什么能力、和别的插件冲不冲突,启动时就知道。能延迟加载的只有组件:trigger.Panel、按钮的 icon 和 Panel。

组装时抛错的情况

装进同一套的插件在组装时一起检查,出现下面任何一种就抛错,错误信息里写明是哪个插件、哪一项:

  • 两个插件的 id 相同。
  • 两个插件声明同一个节点名,或节点名和输入框自带的节点重复。
  • 两个插件声明同一个触发字符。
  • 两个工具条按钮的 id 相同。
  • 写了 contributeSend 却没写 sendKeys,或 sendKeys 里有 SDK 不转交的键。
  • 上面列的声明字段是函数或 Promise,或 chars 为空、某一项不是恰好一个字符。

自己写插件见编写输入框插件。