AI助手与对话
PromptComposer
@mox-hub/patterns · AI · 助手与对话 · canonical
prompt-composer@mox-hub/patternsAI Executioncanonicalsrc/components/prompt-composer.tsx变体演示prompt-composer
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value* | string | — | — |
| onValueChange* | (value: string) => void | — | — |
| onSubmit* | (value: string) => void | — | — |
| placeholder* | string | — | — |
| disabled* | boolean | false | — |
| busy* | boolean | false | — |
| onStop* | () => void | — | — |
| attachments* | PromptComposerAttachment[] | [] | — |
| onAttach* | (files: FileList) => void | — | — |
| onRemoveAttachment* | (id: string) => void | — | — |
| accept* | string | — | — |
| multiple* | boolean | true | — |
| models* | PromptComposerModel[] | — | — |
| model* | string | — | — |
| onModelChange* | (value: string) => void | — | — |
| tokenUsage* | { used: number; limit: number; } | — | — |
| shortcutHint* | ReactNode | — | — |
| enterToSend* | boolean | true | — |
| labels* | Partial<PromptComposerLabels> | — | — |
| className* | string | — | — |
源码
import {
useId,
useRef,
type ComponentProps,
type KeyboardEvent,
type ReactNode,
} from 'react';
import { ArrowUp, Paperclip, Square, X } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import {
InputGroup,
InputGroupAddon,
InputGroupButton,
InputGroupTextarea,
} from '@mox-hub/ui/components/input-group';
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from '@mox-hub/ui/components/select';
import { Spinner } from '@mox-hub/ui/components/spinner';
import { formatBytes, formatCompact, formatPercent } from '@mox-hub/ui/format';
import { usePatternLabels } from '../lib/i18n';
/**
* PromptComposer —— AI 输入区(对话平面)。
*
* 把「附件 + 多行输入 + 模型选择 + token 用量 + 发送/停止」收在一个受控件里:
* - Enter 发送、Shift+Enter 换行;输入法组合态(IME)不发送;
* - 附件 chips 在本体内渲染,未删除的附件由消费方持有(本件不做上传);
* - `busy` 时发送键变停止键(需要 onStop);否则维持发送;
* - token 用量 70% / 90% 两档变色,只用颜色辅助、百分比文本始终可读;
* - 不持有会话状态、不调用模型接口,所有数据经 props 注入。
*/
export interface PromptComposerLabels {
placeholder: string;
send: string;
stop: string;
attach: string;
removeAttachment: (name: string) => string;
composer: string;
tokenUsage: (used: string, limit: string) => string;
}
export const PROMPT_COMPOSER_DEFAULT_LABELS: PromptComposerLabels = {
placeholder: '输入消息,Enter 发送,Shift+Enter 换行',
send: '发送',
stop: '停止生成',
attach: '添加附件',
removeAttachment: (name) => `移除附件 ${name}`,
composer: '消息输入区',
tokenUsage: (used, limit) => `上下文 ${used} / ${limit}`,
};
export interface PromptComposerAttachment {
id: string;
name: string;
/** 字节数;用于展示 */
size?: number;
/** MIME 类型 */
type?: string;
/** 上传/解析状态;缺省 ready */
status?: 'pending' | 'ready' | 'error';
}
export interface PromptComposerModel {
value: string;
label: string;
}
export interface PromptComposerProps
extends Omit<ComponentProps<'form'>, 'onSubmit' | 'children'> {
value: string;
onValueChange: (value: string) => void;
/** 提交(已 trim;空串不会触发) */
onSubmit: (value: string) => void;
placeholder?: string;
disabled?: boolean;
/** 生成中:发送键切换为停止键(需 onStop) */
busy?: boolean;
onStop?: () => void;
/** 附件(受控) */
attachments?: PromptComposerAttachment[];
/** 选择文件回调;未传则不渲染附件钮 */
onAttach?: (files: FileList) => void;
onRemoveAttachment?: (id: string) => void;
accept?: string;
multiple?: boolean;
/** 模型选择(受控);未传则不渲染选择器 */
models?: PromptComposerModel[];
model?: string;
onModelChange?: (value: string) => void;
/** token 用量;limit 为 0/缺省时不渲染 */
tokenUsage?: { used: number; limit: number } | null;
/** 输入框右侧的附加提示(如快捷键 <Kbd>) */
shortcutHint?: ReactNode;
/** Enter 发送(默认 true) */
enterToSend?: boolean;
labels?: Partial<PromptComposerLabels>;
}
function attachmentTone(status: PromptComposerAttachment['status']) {
if (status === 'error') return 'text-accent-red';
if (status === 'pending') return 'text-content-text-muted';
return 'text-content-text-secondary';
}
export function PromptComposer({
value,
onValueChange,
onSubmit,
placeholder,
disabled = false,
busy = false,
onStop,
attachments = [],
onAttach,
onRemoveAttachment,
accept,
multiple = true,
models,
model,
onModelChange,
tokenUsage,
shortcutHint,
enterToSend = true,
labels,
className,
...props
}: PromptComposerProps) {
const D = usePatternLabels('promptComposer', PROMPT_COMPOSER_DEFAULT_LABELS);
const text: PromptComposerLabels = {
placeholder: labels?.placeholder ?? D.placeholder,
send: labels?.send ?? D.send,
stop: labels?.stop ?? D.stop,
attach: labels?.attach ?? D.attach,
removeAttachment: labels?.removeAttachment ?? D.removeAttachment,
composer: labels?.composer ?? D.composer,
tokenUsage: labels?.tokenUsage ?? D.tokenUsage,
};
const inputId = useId();
const fileRef = useRef<HTMLInputElement>(null);
const canSubmit = !disabled && !busy && value.trim().length > 0;
const submit = () => {
const next = value.trim();
if (!next || disabled || busy) return;
onSubmit(next);
};
const handleKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
if (!enterToSend) return;
if (event.key !== 'Enter') return;
if (event.shiftKey) return;
if (event.nativeEvent.isComposing) return;
event.preventDefault();
submit();
};
const showTokenUsage = tokenUsage && tokenUsage.limit > 0;
const usageRatio = showTokenUsage ? tokenUsage.used / tokenUsage.limit : 0;
const usageTone =
usageRatio >= 0.9
? 'text-accent-red'
: usageRatio >= 0.7
? 'text-accent-yellow'
: 'text-content-text-muted';
return (
<form
data-ai-component="prompt.composer"
className={cn('w-full', className)}
onSubmit={(event) => {
event.preventDefault();
submit();
}}
{...props}
>
<InputGroup data-align="block-end" className="flex-col">
{attachments.length > 0 ? (
<InputGroupAddon
align="block-start"
className="flex-wrap justify-start gap-1.5"
>
{attachments.map((file) => (
<span
key={file.id}
className="inline-flex h-6 max-w-56 items-center gap-1 rounded-full bg-content-bg-secondary px-2 text-2xs text-content-text-secondary"
>
{file.status === 'pending' ? (
<Spinner size="sm" aria-hidden className="size-3 shrink-0" />
) : null}
<span className={cn('truncate', attachmentTone(file.status))}>
{file.name}
</span>
{file.size !== undefined ? (
<span className="shrink-0 text-content-text-muted">
{formatBytes(file.size)}
</span>
) : null}
{onRemoveAttachment ? (
<button
type="button"
aria-label={text.removeAttachment(file.name)}
className="shrink-0 rounded-full p-0.5 text-content-text-muted transition-colors duration-fast hover:text-content-text"
onClick={() => onRemoveAttachment(file.id)}
>
<X aria-hidden className="size-3" />
</button>
) : null}
</span>
))}
</InputGroupAddon>
) : null}
<InputGroupTextarea
id={inputId}
value={value}
placeholder={placeholder ?? text.placeholder}
disabled={disabled}
aria-label={text.composer}
rows={1}
onChange={(event) => onValueChange(event.target.value)}
onKeyDown={handleKeyDown}
/>
<InputGroupAddon align="block-end" className="justify-between">
<div className="flex min-w-0 items-center gap-1">
{onAttach ? (
<>
<input
ref={fileRef}
type="file"
accept={accept}
multiple={multiple}
className="sr-only"
aria-hidden
tabIndex={-1}
onChange={(event) => {
const files = event.target.files;
if (files && files.length > 0) onAttach(files);
event.target.value = '';
}}
/>
<InputGroupButton
type="button"
size="icon-xs"
disabled={disabled}
aria-label={text.attach}
title={text.attach}
onClick={() => fileRef.current?.click()}
>
<Paperclip aria-hidden />
</InputGroupButton>
</>
) : null}
{models && models.length > 0 ? (
<Select
value={model}
onValueChange={(next) => onModelChange?.(String(next))}
disabled={disabled}
>
<SelectTrigger
size="sm"
aria-label={text.composer}
className="h-control-xs gap-1 border-0 bg-transparent px-1.5 text-xs shadow-none"
>
<SelectValue />
</SelectTrigger>
<SelectContent>
{models.map((item) => (
<SelectItem key={item.value} value={item.value}>
{item.label}
</SelectItem>
))}
</SelectContent>
</Select>
) : null}
</div>
<div className="flex items-center gap-2">
{showTokenUsage ? (
<span
className={cn('text-2xs tabular-nums', usageTone)}
title={text.tokenUsage(
formatCompact(tokenUsage.used),
formatCompact(tokenUsage.limit),
)}
>
{formatPercent(usageRatio, { maximumFractionDigits: 0 })}
</span>
) : null}
{shortcutHint ? (
<span className="hidden items-center text-2xs text-content-text-muted sm:inline-flex">
{shortcutHint}
</span>
) : null}
{busy && onStop ? (
<InputGroupButton
type="button"
size="icon-xs"
aria-label={text.stop}
title={text.stop}
onClick={onStop}
>
<Square aria-hidden className="fill-current" />
</InputGroupButton>
) : (
<InputGroupButton
type="submit"
size="icon-xs"
disabled={!canSubmit}
aria-label={text.send}
title={text.send}
>
<ArrowUp aria-hidden />
</InputGroupButton>
)}
</div>
</InputGroupAddon>
</InputGroup>
</form>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
AI 输入区:附件 chips + 多行输入 + 模型选择 + token 用量 + 发送/停止;Enter 发送、Shift+Enter 换行、IME 不误发。