Ordo UI
AI助手与对话

PromptComposer

@mox-hub/patterns · AI · 助手与对话 · canonical

prompt-composer@mox-hub/patternsAI Executioncanonicalsrc/components/prompt-composer.tsx
变体演示prompt-composer
login-spec.pdf277 KB
1%

Props API

Prop类型默认值说明
value*string——
onValueChange*(value: string) => void——
onSubmit*(value: string) => void——
placeholder*string——
disabled*booleanfalse—
busy*booleanfalse—
onStop*() => void——
attachments*PromptComposerAttachment[][]—
onAttach*(files: FileList) => void——
onRemoveAttachment*(id: string) => void——
accept*string——
multiple*booleantrue—
models*PromptComposerModel[]——
model*string——
onModelChange*(value: string) => void——
tokenUsage*{ used: number; limit: number; }——
shortcutHint*ReactNode——
enterToSend*booleantrue—
labels*Partial<PromptComposerLabels>——
className*string——

源码

packages/patterns/src/components/prompt-composer.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

AI 输入区:附件 chips + 多行输入 + 模型选择 + token 用量 + 发送/停止;Enter 发送、Shift+Enter 换行、IME 不误发。