OpenMax
免费试用

消息展示插件

用自己的组件画某类消息:怎么写、怎么装、需要的能力、画正文的先后、没装上时的只读画法、发事件。

消息展示插件

消息展示插件认领某类消息(按 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)本来就是合法状态。

画正文的先后

消息区画一条消息的正文,按这个顺序问,第一个给出结果的画:

  1. 消息展示插件(按安装顺序)
  2. 消息区内置的画法:Agent 回复、只读卡片、图片和文件、文本
  3. 这条消息的 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,同一条消息同一个插件只报一次。