AI助手与对话
Suggestion
@mox-hub/patterns · AI · 助手与对话 · canonical
suggestion@mox-hub/patternsSemanticcanonicalsrc/components/suggestion.tsx变体演示suggestion
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| items* | SuggestionItem[] | — | — |
| onSelect* | (item: SuggestionItem) => void | — | — |
| disabled* | boolean | false | — |
| loading* | boolean | false | — |
| emptyLabel* | string | — | — |
| labels* | Partial<SuggestionLabels> | — | — |
| className* | string | — | — |
源码
import type { ReactNode } from 'react';
import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';
import { Spinner } from '@mox-hub/ui/components/spinner';
import { usePatternLabels } from '../lib/i18n';
/**
* Suggestion —— 通用建议 chips(对话 / AI 平面,W4 P1 / B14)。
*
* 可换行的建议按钮列表,覆盖快捷问法、下一步动作、追问提示等场景:
* 点选即回调 `onSelect`,由消费方决定「填入输入框」还是「立即发送」。
* 本件用于后续替换 `assistant-quick-prompts` 的内部实现,但自身不依赖它。
*
* 边界:
* - 纯展示 / 受控件,不取数、不发请求;loading / 空态由 props 驱动;
* - 建议项的外观(图标 / 描述)由 `SuggestionItem` 描述,不自造业务语义;
* - a11y:列表为 `role="list"`、条目为 `listitem`,按钮原生可聚焦、可键盘触发。
*/
export interface SuggestionItem {
id: string;
label: string;
description?: string;
icon?: ReactNode;
}
export interface SuggestionLabels {
/** 列表区域无障碍名 */
region: string;
/** 空列表文案 */
empty: string;
/** 加载中文案 */
loading: string;
}
export const SUGGESTION_DEFAULT_LABELS: SuggestionLabels = {
region: '建议',
empty: '暂无建议',
loading: '正在生成建议…',
};
export interface SuggestionProps {
items: SuggestionItem[];
/** 点选建议(回调携带完整 item,便于消费方区分 id 与文案) */
onSelect: (item: SuggestionItem) => void;
disabled?: boolean;
/** 加载中优先于空态展示 */
loading?: boolean;
/** 覆写空列表文案(优先级高于 labels.empty) */
emptyLabel?: string;
labels?: Partial<SuggestionLabels>;
className?: string;
}
export function Suggestion({
items,
onSelect,
disabled = false,
loading = false,
emptyLabel,
labels,
className,
}: SuggestionProps) {
const D = usePatternLabels('suggestion', SUGGESTION_DEFAULT_LABELS);
const text: SuggestionLabels = {
region: labels?.region ?? D.region,
empty: labels?.empty ?? D.empty,
loading: labels?.loading ?? D.loading,
};
return (
<div
data-ai-component="suggestion"
className={cn('w-full', className)}
>
{loading ? (
<div className="flex items-center gap-2 text-xs text-content-text-muted">
<Spinner size="sm" label={text.loading} />
<span>{text.loading}</span>
</div>
) : items.length === 0 ? (
<p className="text-xs text-content-text-muted">
{emptyLabel ?? text.empty}
</p>
) : (
<ul aria-label={text.region} className="flex flex-wrap gap-1.5">
{items.map((item) => (
<li key={item.id} className="min-w-0 max-w-full">
<Button
type="button"
variant="outline"
size="xs"
disabled={disabled}
onClick={() => onSelect(item)}
className="h-auto max-w-full rounded-full px-2.5 py-1 text-xs font-normal text-content-text-secondary"
>
{item.icon ? (
<span
aria-hidden
className="flex shrink-0 items-center [&_svg:not([class*='size-'])]:size-3"
>
{item.icon}
</span>
) : null}
<span className="min-w-0 truncate">{item.label}</span>
{item.description ? (
<span className="min-w-0 truncate text-2xs text-content-text-muted">
{item.description}
</span>
) : null}
</Button>
</li>
))}
</ul>
)}
</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。
用法说明
通用建议 chips:items 注入、loading/empty/disabled、onSelect 回调;替代产品专用的快捷问法内部实现。