OpenMax
免费试用

编写输入框插件

用 defineComposerPlugin 写一个输入框插件,再和默认插件一起交给 ChatProvider。

编写输入框插件

内置的表情插件是点按钮从面板里挑表情。下面写的是另一个:表情短码插件,输入 : 加几个字母弹出表情候选,选中后插入表情;+ 菜单里有一个按钮,点击插入 :。它只用到触发符和候选面板和工具条按钮两项能力,不需要宿主提供额外能力。

定义插件

emoji-shortcode-plugin.tsx

import { defineComposerPlugin } from "@openmaxai/chat/composer";

interface EmojiCandidate {
  id: string; // 本次候选里唯一,键盘高亮和列表 key 都用它
  emoji: string;
}

const EMOJIS: EmojiCandidate[] = [
  { id: "smile", emoji: "😄" },
  { id: "thumbsup", emoji: "👍" },
  { id: "tada", emoji: "🎉" },
];

function SmileIcon({ className }: { className?: string }) {
  return <span className={className} aria-hidden>🙂</span>;
}

export const emojiShortcodePlugin = defineComposerPlugin<EmojiCandidate>({
  id: "emoji-shortcode",
  trigger: {
    chars: [":", ":"],
    // 只输入了 : 时不弹面板
    search: (query) =>
      query ? EMOJIS.filter((e) => e.id.startsWith(query.toLowerCase())) : [],
    // 把 : 和已输入的字母整段换成表情
    insert: (view, range, candidate) => {
      view.dispatch(view.state.tr.insertText(`${candidate.emoji} `, range.from, range.to));
      view.focus();
    },
    Panel: ({ candidates, activeIndex, onSelect, onActiveIndexChange }) => (
      <ul role="listbox" className="rounded-md border bg-popover p-1 text-sm">
        {candidates.map((c, i) => (
          <li
            key={c.id}
            role="option"
            aria-selected={i === activeIndex}
            className={i === activeIndex ? "rounded bg-accent px-2 py-1" : "px-2 py-1"}
            onMouseOver={() => onActiveIndexChange(i)}
            onMouseDown={(e) => {
              e.preventDefault(); // 焦点留在输入框里
              onSelect(i);
            }}
          >
            {c.emoji} :{c.id}:
          </li>
        ))}
      </ul>
    ),
  },
  toolbar: [
    {
      id: "emoji-shortcode",
      icon: SmileIcon,
      titleKey: "emojiShortcode.tooltip",
      defaultPlacement: "plus-menu",
      onActivate: (ctx) => ctx.activateTrigger(":"),
    },
  ],
});

要点:

  • defineComposerPlugin<EmojiCandidate> 让 search 的返回值、insert 收到的候选和 Panel 的 candidates 是同一个类型,写错当场报类型错误。
  • 触发符前面要是行首或空白,所以 10:30 这样的文字不会弹面板。
  • 面板每一行对应 candidates 里的一项,不多画也不少画;ArrowUp / ArrowDown、Enter、Escape 由 SDK 处理。
  • 悬停高亮用 onMouseOver,不用 onMouseEnter。在 ChatShadowRoot 里,指针从你页面上由 React 渲染的节点直接移进面板时,React 不会在面板上派 onMouseEnter:聊天经 portal 渲染在 shadow root 里,React 在你的根容器和这个 portal 容器上各挂一套监听,enter 的两半(mouseout 与 mouseover)落在不同的监听上,根容器那一半看到的是 shadow 宿主元素而不是真实节点。onMouseOver 照常冒泡,重复调用也没关系。SDK 只改了自己的组件:你自己挂进 ChatShadowRoot 里的 onMouseEnter / onPointerEnter(不止这个面板)仍会这样丢,要悬停触发的都改用 onMouseOver / onPointerOver。
  • titleKey 经宿主的 i18n 能力翻译,emojiShortcode.tooltip 要加进你的翻译里。
  • 插入的是普通文字,所以不需要 nodes,也不需要 sendKeys 和 contributeSend。没有 requiredPorts,任何宿主都装得上。

和默认插件一起装

把它和 COMPOSER_PLUGINS 放进同一个数组,交给 ChatProvider 的 plugins:

app.tsx

import { COMPOSER_PLUGINS } from "@openmaxai/chat/composer";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { emojiShortcodePlugin } from "./emoji-shortcode-plugin";

<ChatProvider host={host} plugins={[...COMPOSER_PLUGINS, emojiShortcodePlugin]}>
  {/* ConversationList、MessageThread …… */}
</ChatProvider>;
  • 只传 [emojiShortcodePlugin] 就只有这个插件,没有 @、# 和内置的表情按钮。
  • 数组的顺序决定工具条按钮的先后;这个按钮默认收在 + 菜单里,要直接放到工具条上,用 ChatProvider 的 toolbarPlacement 把 emoji-shortcode 设成 "bar"。
  • 触发字符、节点名、按钮 id 和默认插件冲突时,组装插件集时抛错,见组装时抛错的情况。

需要宿主数据时

插件要读宿主的数据(例如搜人、搜工作项),在 requiredPorts 里列出用到的能力,再从 search 的 ctx.host 或面板的 host 上读:

interface MemberCandidate {
  id: string;
  name: string;
}

defineComposerPlugin<MemberCandidate>({
  id: "assign",
  requiredPorts: ["identity"],
  trigger: {
    chars: ["~"],
    search: async (query, ctx) => {
      const page = await ctx.host.identity.searchDirectory({ search: query });
      return page.members.map((m) => ({ id: m.memberId, name: m.displayName }));
    },
    // insert、Panel ……
  },
});

宿主缺 requiredPorts 里的任何一项,这个插件就不装,见宿主缺能力的插件不装。插件只能用 ChatHost 上已有的能力。

写插件用的类型

defineComposerPlugin 和下面两个类型从 @openmaxai/chat/composer 导出:

类型 用途
ComposerPlugin 插件本身;COMPOSER_PLUGINS 是它的数组
ComposerToolbarPanelProps 工具条按钮自己的面板收到的属性(close)

把面板、按钮、节点规格写成单独的组件或常量时,还要用到下面几个类型,它们将从 @openmaxai/chat/composer 导出:

类型 用途
ComposerCandidate 候选的最小形状(只有 id),自己的候选类型要满足它 规划中
ComposerPanelProps 候选面板收到的属性,如 ComposerPanelProps<EmojiCandidate> 规划中
ComposerToolbarItem 一个工具条按钮 规划中
ComposerNodeSpec 一个内容节点的规格(ProseMirror 节点规格加 toText、chip) 规划中