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* | MessageFeedback | null | — |
| onFeedback* | (value: MessageFeedback) => void | — | — |
| alwaysVisible* | boolean | false | — |
| disabled* | boolean | false | — |
| labels* | Partial<MessageActionsLabels> | — | — |
| className* | string | — | — |
源码
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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
单条消息操作行:复制/重试/编辑/反馈,回调缺席的动作不渲染;复制自带 2s 回执,反馈二选一再点取消(回传 null)。