Ordo UI
AI助手与对话

MessageActions

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

message-actions@mox-hub/patternsAI Executioncanonicalsrc/components/message-actions.tsx
变体演示message-actions

Props API

Prop类型默认值说明
copyText*string——
onCopy*(text: string) => void | Promise<void>——
onRetry*() => void——
onEdit*() => void——
feedback*MessageFeedbacknull—
onFeedback*(value: MessageFeedback) => void——
alwaysVisible*booleanfalse—
disabled*booleanfalse—
labels*Partial<MessageActionsLabels>——
className*string——

源码

packages/patterns/src/components/message-actions.tsx
import type { ComponentProps } from 'react';
import {
  Check,
  Copy,
  Pencil,
  RefreshCw,
  ThumbsDown,
  ThumbsUp,
} from 'lucide-react';

import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';

import { usePatternLabels } from '../lib/i18n';
import { useCopyToClipboard } from '../lib/use-copy-to-clipboard';

/**
 * MessageActions —— 单条消息的操作行(对话平面)。
 *
 * 复制 / 重试 / 编辑 / 反馈四类动作的**唯一实现**:动作存在性由回调决定,
 * 未传回调的动作不渲染(不给用户一个点了没反应的按钮)。
 *
 * 行为契约:
 * - 复制按钮自己持「已复制」2s 回执态;`onCopy` 抛错则不显示回执;
 * - 反馈是二选一开关:再次点击同一项取消(onFeedback 收到 null);
 * - 所有按钮都带 aria-label,图标本身 aria-hidden;
 * - 操作行默认在消息 hover/focus-within 才显现,由消费方经 `alwaysVisible` 控制。
 */
export interface MessageActionsLabels {
  copy: string;
  copied: string;
  retry: string;
  edit: string;
  thumbsUp: string;
  thumbsDown: string;
  actions: string;
}

export const MESSAGE_ACTIONS_DEFAULT_LABELS: MessageActionsLabels = {
  copy: '复制',
  copied: '已复制',
  retry: '重新生成',
  edit: '编辑',
  thumbsUp: '有帮助',
  thumbsDown: '没帮助',
  actions: '消息操作',
};

export type MessageFeedback = 'up' | 'down';

export interface MessageActionsProps
  extends Omit<ComponentProps<'div'>, 'children' | 'onCopy'> {
  /** 复制内容;未传则不渲染复制按钮 */
  copyText?: string;
  /** 复制成功回调(可用于埋点);复制本身由组件完成 */
  onCopy?: (text: string) => void | Promise<void>;
  onRetry?: () => void;
  onEdit?: () => void;
  /** 当前反馈;受控 */
  feedback?: MessageFeedback | null;
  onFeedback?: (value: MessageFeedback | null) => void;
  /** 常显(默认 hover/focus-within 显现) */
  alwaysVisible?: boolean;
  disabled?: boolean;
  labels?: Partial<MessageActionsLabels>;
}

export function MessageActions({
  copyText,
  onCopy,
  onRetry,
  onEdit,
  feedback = null,
  onFeedback,
  alwaysVisible = false,
  disabled = false,
  labels,
  className,
  ...props
}: MessageActionsProps) {
  const D = usePatternLabels('messageActions', MESSAGE_ACTIONS_DEFAULT_LABELS);
  const text: MessageActionsLabels = {
    copy: labels?.copy ?? D.copy,
    copied: labels?.copied ?? D.copied,
    retry: labels?.retry ?? D.retry,
    edit: labels?.edit ?? D.edit,
    thumbsUp: labels?.thumbsUp ?? D.thumbsUp,
    thumbsDown: labels?.thumbsDown ?? D.thumbsDown,
    actions: labels?.actions ?? D.actions,
  };

  const { copied, copy } = useCopyToClipboard();

  const handleCopy = async () => {
    if (copyText === undefined) return;
    const ok = await copy(copyText);
    if (ok) await onCopy?.(copyText);
  };

  const toggleFeedback = (value: MessageFeedback) => {
    onFeedback?.(feedback === value ? null : value);
  };

  const hasActions =
    copyText !== undefined ||
    onRetry !== undefined ||
    onEdit !== undefined ||
    onFeedback !== undefined;

  if (!hasActions) return null;

  return (
    <div
      role="toolbar"
      aria-label={text.actions}
      data-ai-component="message.actions"
      className={cn(
        'flex items-center gap-0.5 transition-opacity duration-fast',
        alwaysVisible
          ? 'opacity-100'
          : 'opacity-0 group-hover/message:opacity-100 group-focus-within/message:opacity-100',
        className,
      )}
      {...props}
    >
      {copyText !== undefined ? (
        <Button
          type="button"
          variant="ghost"
          size="icon-xs"
          disabled={disabled}
          aria-label={copied ? text.copied : text.copy}
          title={copied ? text.copied : text.copy}
          onClick={handleCopy}
        >
          {copied ? (
            <Check aria-hidden className="text-accent-green" />
          ) : (
            <Copy aria-hidden />
          )}
        </Button>
      ) : null}

      {onRetry ? (
        <Button
          type="button"
          variant="ghost"
          size="icon-xs"
          disabled={disabled}
          aria-label={text.retry}
          title={text.retry}
          onClick={onRetry}
        >
          <RefreshCw aria-hidden />
        </Button>
      ) : null}

      {onEdit ? (
        <Button
          type="button"
          variant="ghost"
          size="icon-xs"
          disabled={disabled}
          aria-label={text.edit}
          title={text.edit}
          onClick={onEdit}
        >
          <Pencil aria-hidden />
        </Button>
      ) : null}

      {onFeedback ? (
        <>
          <Button
            type="button"
            variant="ghost"
            size="icon-xs"
            disabled={disabled}
            aria-label={text.thumbsUp}
            title={text.thumbsUp}
            aria-pressed={feedback === 'up'}
            className={feedback === 'up' ? 'text-accent-green' : undefined}
            onClick={() => toggleFeedback('up')}
          >
            <ThumbsUp aria-hidden />
          </Button>
          <Button
            type="button"
            variant="ghost"
            size="icon-xs"
            disabled={disabled}
            aria-label={text.thumbsDown}
            title={text.thumbsDown}
            aria-pressed={feedback === 'down'}
            className={feedback === 'down' ? 'text-accent-red' : undefined}
            onClick={() => toggleFeedback('down')}
          >
            <ThumbsDown aria-hidden />
          </Button>
        </>
      ) : null}
    </div>
  );
}

可访问性与 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。

用法说明

单条消息操作行:复制/重试/编辑/反馈,回调缺席的动作不渲染;复制自带 2s 回执,反馈二选一再点取消(回传 null)。