Ordo UI
AI助手与对话

CitationList

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

citation-list@mox-hub/patternsAI Executioncanonicalsrc/components/citation-list.tsx
变体演示citation-list

Props API

Prop类型默认值说明
citations*Citation[]——
variant*"inline" | "panel"'inline'—
onSelect*(citation: Citation) => void——
labels*Partial<CitationListLabels>——
className*string——

源码

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

用法说明

来源引用:inline 角标行 / panel 列表;交互优先级 onSelect > url > 纯展示,外链固定 target=_blank + noreferrer noopener;CitationMarker 供正文上标。