输入框
消息区底部的输入框,支持 @ 提及、# 工作项,插件集由你决定。
输入框

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): composer-basic.tsx
"use client";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
export default function ComposerDemo() {
// The composer is part of MessageThread. With the default plugin set it supports
// `@` (mention a member, needs `identity`) and `#` (reference a work item, needs `workItems`).
const host = useDemoHost();
const { conversations } = useDemoData();
return (
<ChatHostProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<MessageThread conversation={conversations[2]} />
</div>
</ChatHostProvider>
);
}
演示代码中的 useDemoHost() 是内存宿主,接入真实宿主的写法见概览。
何时使用
- 每个
MessageThread底部都自带输入框(富文本、附件、回复条、工具条),无需单独渲染。 - 你要配置的是插件集:有哪些触发符和工具条按钮,每个插件声明它需要的能力。插件集随宿主一起交给
ChatProvider。插件能做什么、怎么自己写,见插件。
| 插件 id | 触发 | 作用 | requiredPorts |
|---|---|---|---|
emoji 规划中 |
工具条按钮 | 打开表情面板,选中的表情作为文字插入;收起和展开时都有 | 无 |
mention |
@(工具条也有按钮) |
候选为会话成员,会话允许时还有「所有人」「所有 Agent」;发出结构化的 @ | identity、i18n |
work-reference |
#(工具条也有按钮) |
搜索项目和问题,插入引用标签;以 [#label](resourceUri) 发出 |
workItems |
各插件的细节见内置插件。
示例
换一套插件
不传 plugins 就装默认插件(COMPOSER_PLUGINS)。要换一套,传给 ChatProvider:
app.tsx
import { COMPOSER_PLUGINS } from "@openmaxai/chat/composer";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
<ChatProvider host={host} plugins={COMPOSER_PLUGINS.filter((p) => p.id === "mention")}>
{/* MessageThread …… */}
</ChatProvider>;
宿主缺 requiredPorts 里某项能力的插件,SDK 不装,不用自己过滤,见能力。列表可以像上面这样写在组件里:SDK 按插件 id 比较,id 不变就不重建编辑器(所以同一个 id 换了插件对象不会生效)。
没有工作项

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): composer-without-work-items.tsx
"use client";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
export default function ComposerWithoutWorkItems() {
const host = useDemoHost({ without: ["workItems"] });
const { conversations } = useDemoData();
// The legacy MessageThread reads react-query and the host brings none: wrap a QueryClientProvider
// yourself.
const [queryClient] = useState(() => new QueryClient());
return (
<QueryClientProvider client={queryClient}>
{/* The host has no `workItems`, so ChatProvider leaves out the `#` plugin; `@` stays. */}
<ChatProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<MessageThread conversation={conversations[2]} />
</div>
</ChatProvider>
</QueryClientProvider>
);
}
宿主没有 workItems,work-reference 就不装:# 只是普通字符,工具条上也没有 # 按钮,@ 照常可用。
@ 提及
输入 @ 或点工具条按钮,方向键加 Enter 或点击选中。被 @ 的人会在消息区看到 @me 胶囊。
# 工作项
输入 # 搜索项目和问题,展开项目可在同一面板列出其问题。搜索由宿主的 workItems 能力提供:
work-items.ts
import type { ChatWorkItemsPort } from "@openmaxai/chat/host";
export const workItems: ChatWorkItemsPort = {
search: async ({ search, projectId, cursor }) => {
const page = await api.searchWorkItems({ q: search, project: projectId, after: cursor });
return {
items: page.items.map((w) => ({
id: w.id,
kind: w.type === "project" ? "project" : "issue",
label: w.type === "project" ? w.name : `${w.projectName} / ${w.title}`,
resourceUri: w.uri,
projectId: w.type === "project" ? undefined : w.projectId,
})),
nextCursor: page.next ?? undefined,
};
},
};
返回扁平列表;带了 projectId 时只返回该项目下的问题。
用 @openmaxai/chat-sdk 时,适配器的 workItems 是同一个类型,SDK 自有名为 ChatSdkAdapterWorkItems,适配器不必从 @openmaxai/chat/host 引。
展开编辑
输入框有收起和展开两种状态。平时是收起的普通输入框;点底栏发送按钮左边的展开按钮,输入框原地长高、撑满会话区,写长消息用,消息列表让出高度,输入框顶上留出与左右同宽的一圈间距,不贴着会话头部;正文再长就在编辑区里滚动,+ 菜单、插件按钮、附件和发送按钮一直留在底栏上。点收起按钮回到普通输入框。
- 展开和收起不动已输入的内容、光标位置、附件和引用条,焦点留在编辑区。
- 展开时
Enter换行,Ctrl/Cmd+Enter发送;收起时按composerPreferences的设置,默认Enter发送。输入法组字时的Enter交给输入法。 - 发出一条消息后自动收起;切换会话时回到收起,展开状态不保存。
Escape不收起。- 窄屏(手机布局)没有展开按钮。编辑已发消息的输入框没有展开。
- 展开是输入框自带的功能,不是插件,默认打开;不要时把
ChatProvider的composerExpandable设为false,就没有展开按钮。
格式与 Markdown
规划中
收起的输入框是展开的精简版:格式、表情和其余插件在两种状态下都能用,展开后格式工具条固定在编辑区顶部。展开不加别的输入项,没有单独的标题:想要标题就在正文里用 Markdown 写,比如行首打 # 。关掉展开(composerExpandable 为 false)时,收起状态下格式照常能用。
格式:粗体、删除线、斜体、下划线、有序列表、无序列表、引用、链接、代码。
- 收起时有两个入口:点底栏的「Aa」按钮出格式工具条;选中文字时,选区上方浮出一条格式条,按钮相同。
- 展开后格式工具条固定在编辑区顶部。
- 不点按钮也行:输入框边打边认 Markdown,收起和展开时一样。打完
**xxx**,这段立刻变成粗体,*xxx*变成斜体;~~xxx~~变成删除线,用反引号包住的一段变成代码;行首的-、1.、>变成列表和引用。 - 输入框不转义照字面打的 Markdown 符号:没被认成格式的
*、#等原样留在正文里发出去,收到的人那边按 Markdown 画。
两种状态的布局:
- 收起:正文,下面是底栏:「Aa」、插件的工具条按钮(表情、
@、#等)、附件、+菜单、展开按钮、发送按钮。 - 展开:从上到下是格式工具条、正文、底栏。底栏是插件的工具条按钮、附件、
+菜单、收起按钮和发送按钮。
格式按钮和边打边认的 Markdown 不看宿主能力,任何宿主上都有。
发出去是什么: 一条消息就是一段 Markdown 字符串,不分标题和正文,也没有单独的格式标记。
SendMessageInput的text是 Markdown 源文,收起和展开时一样。没用格式时就是普通文字。- 宿主照常把
text交给后端,不用为格式做别的事,见宿主能力 ·messaging。 - 人发的消息正文都按 Markdown 画(
render.renderMessageText),@ 提及和链接照常。见数据模型。
插件在展开时: @、# 的触发符、候选面板和内容节点照常工作,发送时带的结构化数据(如 mentions)也照常。插件的工具条按钮挪到底栏,收进 + 菜单的仍在 + 菜单里。见输入框插件 · 工具条按钮。
发出正在输入
规划中
用户在输入框里打字时,输入框经宿主的 messaging.sendTyping 告诉会话里的其他人,他们的会话头部显示「正在输入」。
| 时刻 | 调用 |
|---|---|
| 正文从空变成非空,或打字时距上一次发出已过 3 秒 | sendTyping(conversationId, true) |
| 发送、清空正文、切走会话、输入框卸载,或停止打字 5 秒 | sendTyping(conversationId, false) |
- 只在正文真的变了时算打字:移动光标、选中文字、输入法组字中途、只加附件都不算。
- 正文为空时不发
true;只发过false之后不再重复发false。 - 只读的会话(旁观、Agent 协作、不能发言的单聊)不发。
sendTyping失败时静默,不提示、不重试,下一次打字照常再发。- 宿主没有
sendTyping就不发,输入框其余照常。
API
ChatProvider 上的输入框属性
输入框没有自己的 Provider,插件和工具条落点都在 ChatProvider 上设,整个聊天用同一套。ChatProvider 的其余属性见 @openmaxai/chat-sdk。
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
plugins |
readonly ComposerPlugin[] |
COMPOSER_PLUGINS |
要装的插件。宿主缺能力的插件不装;按插件 id 比较,同一个 id 换了插件对象不会生效 |
toolbarPlacement |
ComposerToolbarPlacementOverrides |
— | 按工具条项 id 指定 "bar"(直接显示)或 "plus-menu"(收进 + 菜单)。不设时按插件自己的默认位置 |
composerExpandable |
boolean |
true |
是否有展开编辑按钮 |
@openmaxai/chat/composer 的其他导出
| 导出 | 说明 |
|---|---|
COMPOSER_PLUGINS |
全部已注册插件 |
defineComposerPlugin |
定义插件:文档节点、触发符与候选面板、发送数据、工具条按钮、requiredPorts。触发符或节点名冲突在组装插件集时抛错。见编写输入框插件 |
ChatFileDropZone |
包住头部和消息区,拖到头部的文件也能进输入框,属性见下文 |
ComposerPlugin、ComposerToolbarPanelProps |
写插件用的类型 |
ComposerCandidate、ComposerPanelProps、ComposerToolbarItem、ComposerNodeSpec |
写插件用的类型:候选、候选面板属性、工具条按钮、内容节点规格 规划中 |
ChatFileDropZone
包住头部和消息区:文件拖到它范围内任何位置(包括头部)松手,都交给里面那个 MessageThread 的输入框,按输入框的规则收(超过大小的不收、按剩余名额截断)。会话只读,或里面没有 MessageThread 时,不显示拖放遮罩,松手也不收。不包它时,只有消息区和输入框接收拖放。
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
children |
ReactNode |
必填 | 头部和 MessageThread |
className |
string |
— | 加在包裹元素上 |
一个 ChatFileDropZone 里只放一个 MessageThread;放了两个时,后挂载的那个接收文件。
依赖的能力
| 能力 | 缺了会怎样 |
|---|---|
workItems |
需要它的插件不装,没有 #,其余照常 |
composerPreferences |
Enter 发送、Shift+Enter 换行。提供后按其设置,可改为 Ctrl/Cmd+Enter 发送 |
attachments(附件数量上限为 0) |
没有附件按钮 |
drafts |
必需;按会话保存和恢复草稿 |
identity、i18n |
必需;@ 提及要用 |
messaging(sendTyping) 规划中 |
别人看不到你「正在输入」 |
无障碍
- 编辑区是可聚焦的
role="textbox",aria-multiline="true",标签为占位文案。 - 候选面板中
ArrowUp/ArrowDown移动、Enter选中、Escape关闭;可展开的#行带aria-expanded。 - 输入法组字时的
Enter交给输入法,不会发送。 - 工具条图标按钮、发送按钮和
+菜单按钮都有标签,+菜单报告aria-expanded。
常见问题
能单独渲染输入框吗?
不能。输入框不单独导出:它的 props 由消息区内部传入(编辑器 ref、发送回调、回复状态)。请用 MessageThread 自带的输入框,通过插件集合和 ChatProvider 的 toolbarPlacement、composerExpandable 调整它(见插件)。
