OpenMax
免费试用

输入框

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

输入框

composer-basic demo

演示截图。演示跑在内存里的示例 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 换了插件对象不会生效)。

没有工作项

composer-without-work-items demo

演示截图。演示跑在内存里的示例 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 调整它(见插件)。