AI助手与对话
CitationList
@mox-hub/patterns · AI · 助手与对话 · canonical
citation-list@mox-hub/patternsAI Executioncanonicalsrc/components/citation-list.tsx变体演示citation-list
- 登录页设计规范
- 验收标准模板
- 登录页设计规范design.example.com
- 验收标准模板验收标准应包含可测的通过条件与失败条件。
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| citations* | Citation[] | — | — |
| variant* | "inline" | "panel" | 'inline' | — |
| onSelect* | (citation: Citation) => void | — | — |
| labels* | Partial<CitationListLabels> | — | — |
| className* | string | — | — |
源码
import type { ComponentProps } from 'react';
import { ExternalLink } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { usePatternLabels } from '../lib/i18n';
/**
* CitationList —— 来源引用(对话平面)。
*
* 两种形态:
* - `inline`:消息末尾的编号角标行(`1 标题 · 2 标题`),适合回答下方的来源条;
* - `panel`:右侧来源列表,标题 + 来源域名 + 摘要,适合与 ArtifactPanel 并列。
*
* 交互优先级:`onSelect` > `url` > 纯展示。外链一律
* `target="_blank" rel="noreferrer noopener"`,不接管消费方路由。
*/
export interface Citation {
id: string;
title: string;
url?: string;
/** 摘要 / 摘录 */
snippet?: string;
/** 来源名(域名、文档名等) */
source?: string;
/** 展示序号(缺省按数组顺序 +1) */
index?: number;
}
export interface CitationListLabels {
region: string;
open: string;
citation: (index: number) => string;
}
export const CITATION_LIST_DEFAULT_LABELS: CitationListLabels = {
region: '来源引用',
open: '打开来源',
citation: (index) => `引用 ${index}`,
};
export interface CitationListProps
extends Omit<ComponentProps<'ol'>, 'children' | 'onSelect'> {
citations: Citation[];
variant?: 'inline' | 'panel';
onSelect?: (citation: Citation) => void;
labels?: Partial<CitationListLabels>;
}
/** 消息正文里的上标角标;配合 inline 列表的序号使用。 */
export interface CitationMarkerProps
extends Omit<ComponentProps<'sup'>, 'children'> {
index: number;
/** 无障碍名;缺省「引用 N」 */
label?: string;
onClick?: () => void;
}
export function CitationMarker({
index,
label,
onClick,
className,
...props
}: CitationMarkerProps) {
const D = usePatternLabels('citationList', CITATION_LIST_DEFAULT_LABELS);
const name = label ?? D.citation(index);
return (
<sup className={cn('ms-0.5', className)} {...props}>
{onClick ? (
<button
type="button"
aria-label={name}
title={name}
className="inline-flex size-3.5 items-center justify-center rounded-full bg-accent-blue-light text-3xs font-semibold text-accent-blue align-super outline-none transition-colors duration-fast hover:bg-accent-blue/20 focus-visible:ring-2 focus-visible:ring-ring/50"
onClick={onClick}
>
{index}
</button>
) : (
<span
aria-label={name}
title={name}
className="inline-flex size-3.5 items-center justify-center rounded-full bg-accent-blue-light text-3xs font-semibold text-accent-blue align-super"
>
{index}
</span>
)}
</sup>
);
}
export function CitationList({
citations,
variant = 'inline',
onSelect,
labels,
className,
...props
}: CitationListProps) {
const D = usePatternLabels('citationList', CITATION_LIST_DEFAULT_LABELS);
const text: CitationListLabels = {
region: labels?.region ?? D.region,
open: labels?.open ?? D.open,
citation: labels?.citation ?? D.citation,
};
if (variant === 'inline') {
return (
<ol
aria-label={text.region}
data-ai-component="citation.list"
data-variant="inline"
className={cn('flex flex-wrap items-center gap-1', className)}
{...props}
>
{citations.map((citation, position) => {
const number = citation.index ?? position + 1;
const body = (
<>
<span
aria-hidden
className="flex size-3.5 shrink-0 items-center justify-center rounded-full bg-accent-blue-light text-3xs font-semibold text-accent-blue"
>
{number}
</span>
<span className="max-w-40 truncate">{citation.title}</span>
</>
);
return (
<li key={citation.id} className="min-w-0">
{onSelect ? (
<button
type="button"
aria-label={`${text.citation(number)}:${citation.title}`}
className="inline-flex max-w-full items-center gap-1 rounded-full border border-content-border bg-background px-1.5 py-0.5 text-2xs text-content-text-secondary outline-none transition-colors duration-fast hover:border-accent-blue/40 hover:text-content-text focus-visible:ring-2 focus-visible:ring-ring/50"
onClick={() => onSelect(citation)}
>
{body}
</button>
) : citation.url ? (
<a
href={citation.url}
target="_blank"
rel="noreferrer noopener"
aria-label={`${text.citation(number)}:${citation.title}`}
className="inline-flex max-w-full items-center gap-1 rounded-full border border-content-border bg-background px-1.5 py-0.5 text-2xs text-content-text-secondary transition-colors hover:border-accent-blue/40 hover:text-content-text focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
>
{body}
</a>
) : (
<span className="inline-flex max-w-full items-center gap-1 rounded-full border border-content-border bg-background px-1.5 py-0.5 text-2xs text-content-text-secondary">
{body}
</span>
)}
</li>
);
})}
</ol>
);
}
return (
<ol
aria-label={text.region}
data-ai-component="citation.list"
data-variant="panel"
className={cn('space-y-2', className)}
{...props}
>
{citations.map((citation, position) => {
const number = citation.index ?? position + 1;
const content = (
<>
<span className="flex items-start gap-2">
<span
aria-hidden
className="mt-0.5 flex size-4 shrink-0 items-center justify-center rounded-full bg-accent-blue-light text-3xs font-semibold text-accent-blue"
>
{number}
</span>
<span className="min-w-0 flex-1">
<span className="block text-xs font-medium text-content-text">
{citation.title}
</span>
{citation.source ? (
<span className="mt-0.5 block text-2xs text-content-text-muted">
{citation.source}
</span>
) : null}
{citation.snippet ? (
<span className="mt-1 block line-clamp-2 text-2xs text-content-text-secondary">
{citation.snippet}
</span>
) : null}
</span>
{citation.url && !onSelect ? (
<ExternalLink
aria-hidden
className="mt-0.5 size-3 shrink-0 text-content-text-muted"
/>
) : null}
</span>
</>
);
return (
<li key={citation.id}>
{onSelect ? (
<button
type="button"
aria-label={`${text.citation(number)}:${citation.title}`}
className="block w-full rounded-md border border-content-border bg-background px-2 py-1.5 text-start outline-none transition-colors duration-fast hover:border-accent-blue/40 hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring/50"
onClick={() => onSelect(citation)}
>
{content}
</button>
) : citation.url ? (
<a
href={citation.url}
target="_blank"
rel="noreferrer noopener"
aria-label={`${text.open}:${citation.title}`}
className="block rounded-md border border-content-border bg-background px-2 py-1.5 no-underline outline-none transition-colors duration-fast hover:border-accent-blue/40 hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring/50"
>
{content}
</a>
) : (
<div className="rounded-md border border-content-border bg-background px-2 py-1.5">
{content}
</div>
)}
</li>
);
})}
</ol>
);
}
可访问性与 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。
用法说明
来源引用:inline 角标行 / panel 列表;交互优先级 onSelect > url > 纯展示,外链固定 target=_blank + noreferrer noopener;CitationMarker 供正文上标。