消息展示插件
用自己的组件画某类消息:怎么写、怎么装、需要的能力、画正文的先后、没装上时的只读画法、发事件。
消息展示插件
消息展示插件认领某类消息(按 message.type),用自己的组件画这条消息的正文。交互卡片就是一个消息展示插件:卡片插件 cardRenderer 认领 CARD 消息,见交互卡片。
写一个插件
用 defineMessageRenderer 定义:
poll-renderer.tsx
import {
type ChatMessageRendererProps,
defineMessageRenderer,
} from "@openmaxai/chat/message-thread";
function PollView({ message, readOnly, emit }: ChatMessageRendererProps) {
const poll = JSON.parse(message.content ?? "{}") as { question?: string; options?: string[] };
return (
<div className="rounded-xl border p-3">
<p>{poll.question}</p>
{(poll.options ?? []).map((option) => (
<button
key={option}
type="button"
disabled={readOnly}
onClick={() => emit("voted", { option })}
>
{option}
</button>
))}
</div>
);
}
export const pollRenderer = defineMessageRenderer({
id: "acme-poll",
types: ["ACME_POLL"],
layout: "bare",
View: PollView,
});
字段(ChatMessageRenderer) |
类型 | 必填 | 说明 |
|---|---|---|---|
id |
string |
是 | 唯一;和另一个消息展示插件重名时,装的时候抛错 |
types |
readonly string[] |
是 | 认领的消息类型(message.type)。不能为空,不能含内置类型(见认领规则) |
matches |
(message: ChatMessage) => boolean |
否 | 在 types 之内再细分,例如只认某种 schema。不给就是这些类型全归它。渲染时调用,不要抛错 |
requiredPorts |
readonly (keyof ChatHost)[] |
否 | 需要的宿主能力,缺一项就不装,不抛错 |
layout |
"bare" | "bubble" |
否 | 默认 "bubble",正文套在气泡里。"bare" 不套气泡,正文自带外壳(卡片就是这样) |
excerptQuote |
boolean |
否 | 默认 false。true 时用户可以在正文里划选文字引用,见划选引用 |
View |
ComponentType<ChatMessageRendererProps> |
是 | 正文组件。可以用 hook,也可以是 React.lazy:加载期间显示这条消息的 fallback_text |
View 收到的东西(ChatMessageRendererProps):
| 属性 | 类型 | 说明 |
|---|---|---|
message |
ChatMessage |
这条消息 |
host |
ChatHost |
当前宿主。只读你在 requiredPorts 里声明过的能力,没声明的不保证在 |
readOnly |
boolean |
会话是只读的:旁观、Agent 协作、对端不能再收消息的私聊、开通中、被遥控器锁住,和输入框是不是只读同一个判据。只读时画成什么样由插件决定 |
senderIsAgent |
boolean |
发送者是不是 Agent,按参与者的 kind 判 |
participantMap |
Readonly<Record<string, ChatParticipant>> |
可选。会话成员,按成员 id,解析名字用 |
interactions |
ChatMessageInteractions |
这条消息的幂等键与防连点,见幂等键与防连点 |
emit |
(name: string, payload?: ChatPluginEventPayload) => void |
发一个事件给应用,见发事件 |
locale、t |
界面语言与取文案的函数,同宿主的 i18n |
以后只会新增可选的属性。
认领规则
- 按安装数组的顺序,第一个
types含这条消息的类型、matches为真(或没给)的插件画它。同一类型可以有几个插件,靠matches分开,越具体的放越前面。 - 按
message.type认领,排在消息区内置的形状判定之前。 - 内置类型
TEXT、AGENT_TEXT、IMAGE、FILE、SYSTEM不能认领(不分大小写),装的时候抛错:编辑、撤回、@、图注和媒体判定都挂在这几类上,系统通知更早就整条单独画了。完整列表是CORE_MESSAGE_TYPES。
安装
用 SDK 时经 ChatProvider 的 messageRenderers 安装:
app.tsx
import { CHAT_SDK_MESSAGE_RENDERERS, ChatProvider } from "@openmaxai/chat-sdk/react";
import { pollRenderer } from "./poll-renderer";
<ChatProvider host={host} messageRenderers={[pollRenderer, ...CHAT_SDK_MESSAGE_RENDERERS]}>
{/* …… */}
</ChatProvider>;
- 不传
messageRenderers就装CHAT_SDK_MESSAGE_RENDERERS(选择卡插件formCardRenderer与卡片插件cardRenderer)。传了就只装你给的这些,要保留默认插件,把它们放进同一个数组。 - 数组可以直接写在 JSX 里:插件 id 序列不变就沿用上一次那一份。
- 插件经
emit发的事件、插件出错都交给createChatHost({ onEvent }),见发事件。
直接用 @openmaxai/chat 时用 MessageRenderersProvider。下面的 MessageThread 是 @openmaxai/chat 的组件,不带样式根:SDK 样式表只作用在 SDK 组件自带的 .omx-chat 组件根之内,要你把它放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。
app.tsx
import { MESSAGE_RENDERERS, MessageRenderersProvider } from "@openmaxai/chat/message-thread";
<MessageRenderersProvider
renderers={[pollRenderer, ...MESSAGE_RENDERERS]}
onPluginEvent={(event) => track(event)}
>
<MessageThread conversation={conversation} />
</MessageRenderersProvider>;
- 不包这一层就装
MESSAGE_RENDERERS(formCardRenderer、cardRenderer),插件事件不交给任何人。 onPluginEvent收插件发的事件,onRendererError收插件出错的报告。- 不能嵌套:
ChatProvider里面已经有一层,再包一层挂载时就抛。要换插件集,改外层。
缺能力的插件不装
插件用 requiredPorts 写明需要哪些能力。宿主缺其中任何一项,这个插件就不装,不抛错,它要认领的消息交给后面的插件或内置画法。例如宿主没有 cards,卡片插件不装,卡片按只读画法显示。宿主在运行时变了,插件跟着重新挑。
这一点和输入框插件不同:单用 @openmaxai/chat 时,输入框插件缺能力会抛错;消息展示插件不抛,因为没有某项能力(例如没有 cards)本来就是合法状态。
画正文的先后
消息区画一条消息的正文,按这个顺序问,第一个给出结果的画:
- 消息展示插件(按安装顺序)
- 消息区内置的画法:Agent 回复、只读卡片、图片和文件、文本
- 这条消息的
fallback_text
正文和气泡外壳用的是同一次判定。宿主的 render 能力只管怎么画文本、Markdown 和图片,不决定一条消息由谁画;原来的 render.renderStructuredMessage 与 render.renderCustomMessage 已删除,迁移见自定义消息渲染。
没装上卡片插件时
CARD 消息没有插件认领时(宿主没有 cards,或没装卡片插件),消息区按只读画:正文、结果行(含作答人)、「已被取代」「已过期」照常;不画业务按钮;选项和「创建 Agent」禁用,悬停说明「这里暂不支持作答」(只读会话里说「当前会话是只读的」);被截断的卡片只提示内容未完整,没有「展开」。点什么都不发请求,也不会发一条消息代替作答。
划选引用
用户在消息正文里划选一段文字,点选区旁的「引用」,这段文字就进了输入框上方的引用位。插件画的正文只有在插件声明 excerptQuote: true 时才有这个按钮;不声明时照样能划选、原生复制照常,只是不出「引用」。默认关,是因为消息区看不到插件的结构:整张可点的正文会把拖选松手当成一次点击。formCardRenderer、cardRenderer 与只读画法都是开的。
声明了 excerptQuote: true 之后:
- 引文是正文里看得见的文字。按钮、输入框、下拉框、图片、
svg与aria-hidden的元素不进。其余界面字(状态标签、时间、计数、提示)打上data-excerpt-skip属性,连同它里面的一切都不进。文字本身就是内容的控件(例如画成button的选项)可以打data-excerpt-text,它的文字就会进,单独成一行。 - 选区里只剩这些不进的部分时,不出「引用」。
- 在正文里拖选(或触屏长按选文)松手的那次点击,在到达正文之前就被拦下:划选不会按到按钮、打开链接或点开整张卡。单纯点击、键盘触发的点击不受影响。
- 从引用条跳回时高亮正文里的那段文字。正文此后变了(展开了、答过了、内容更新了)、位置对不上时,高亮第一次出现处;找不到就高亮整条消息。
发事件
插件用 emit(name, payload) 把事件交给应用。应用收到的是一个信封:
{
type: "plugin";
pluginKind: "message-renderer";
pluginId: string; // 插件的 id
name: string; // emit 的第一个参数
payload: ChatPluginEventPayload; // emit 的第二个参数,没给是 {}
}
type、pluginKind、pluginId由包按安装的插件填,插件给不了。插件冒充不了 SDK 自己的事件(它们的type不是"plugin"),也冒充不了别的插件。payload只放 JSON 值,不放函数、React 节点或Error。包原样转交、不克隆;不是 JSON 值时告警。- 同步投递,顺序就是调用顺序。接收方抛的错被接住(
console.error),不影响插件。 - 没有接收方(SDK 里没给
onEvent,或MessageRenderersProvider没给onPluginEvent)时emit什么都不做。 - 只在事件处理和 effect 里调。渲染期调用会告警:严格模式和并发渲染下会重复发。
幂等键与防连点
interactions 是这条消息的交互句柄,插件只取不建:
| 成员 | 说明 |
|---|---|
idempotencyKey(actionId) |
这条消息这个按钮的幂等键。网络重试、超时重试、拿到失败后再点一次都是同一把 |
resetIdempotencyKey(actionId) |
宿主的判决点名换键时调,只换这一个按钮的 |
pending |
这条消息有提交在途 |
run(task) |
防连点:有提交在途时不执行、返回 null;否则占住,task 结束后释放 |
subscribe(listener) |
订阅这条消息在途状态的变化 |
它们挂在宿主上,组件被虚拟列表卸载再挂上时键和在途状态都还在;换了账号(新的宿主)就是新的一份。「同一个宿主」按宿主的 instanceScope 对象认:手写宿主要在整个生命周期里交出同一个 instanceScope,别随成员、在线态这类数据一起重建它,否则在途的按钮会重新可点、重试换新键。
出错
插件的 View 渲染时抛错,只有这条消息退回 fallback_text,别的消息照常;matches 抛错时这条消息也按 fallback_text 画。出错会报给应用:SDK 里是 onEvent 的 renderer.failed,单用 @openmaxai/chat 时是 MessageRenderersProvider 的 onRendererError,同一条消息同一个插件只报一次。
