编写输入框插件
用 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) 规划中 |
