Ordo UI
AI助手与对话

ArtifactPanel

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

artifact-panel@mox-hub/patternsAI Executioncanonicalsrc/components/artifact-panel.tsx
变体演示artifact-panel

Login.tsx

Login.tsxtsx
export function Login() {
  return <form onSubmit={handleSubmit} />
}

Props API

Prop类型默认值说明
title*string——
content*ArtifactContent——
versions*ArtifactVersion[]——
versionId*string——
onVersionChange*(id: string) => void——
view*ArtifactView——
defaultView*ArtifactView'preview'—
onViewChange*(view: ArtifactView) => void——
diff*ReactNode——
onDownload*() => void——
onClose*() => void——
renderCode*(content: { kind: "code"; code: string; language?: string; filename?: string; }) => ReactNode——
renderMarkdown*(content: { kind: "markdown"; markdown: string; }) => ReactNode——
labels*Partial<ArtifactPanelLabels>——
className*string——

源码

packages/patterns/src/components/artifact-panel.tsx
import { useId, useState, type ComponentProps, type ReactNode } from 'react';
import { Download, FileCode2, FileText, Image, Table, X } from 'lucide-react';

import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';
import {
  SegmentedControl,
  type SegmentedOption,
} from '@mox-hub/ui/components/segmented-control';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@mox-hub/ui/components/select';

import { usePatternLabels } from '../lib/i18n';
import { CodeBlock } from './code-block';
import { StreamingMarkdown } from './streaming-markdown';

/**
 * ArtifactPanel —— 产物面板(产物平面核心件)。
 *
 * 四类产物同一外壳:
 * - `code`:代码视图(缺省 CodeBlock,Shiki 高亮)
 * - `markdown`:渲染视图 + 源码视图
 * - `image`:图片预览
 * - `data`:JSON / 表格两种预览 + 源码视图
 *
 * 三个视图:preview / source / diff(diff 内容由消费方注入,通常传 InlineDiff)。
 * `versions` 与 `versionId` 同时存在时进入受控版本切换;否则用传入的 `content`。
 *
 * 本件静态依赖 code-block(shiki)与 streaming-markdown(streamdown),
 * 因此**不进根 barrel**,只能按子路径引入:
 * `@mox-hub/patterns/components/artifact-panel`。
 */
export type ArtifactKind = 'code' | 'markdown' | 'image' | 'data';
export type ArtifactView = 'preview' | 'source' | 'diff';

export type ArtifactContent =
  | { kind: 'code'; code: string; language?: string; filename?: string }
  | { kind: 'markdown'; markdown: string }
  | { kind: 'image'; src: string; alt?: string }
  | { kind: 'data'; data: unknown; format?: 'json' | 'table' };

export interface ArtifactVersion {
  id: string;
  /** 版本标签(v1 / 10:23 等) */
  label: string;
  content: ArtifactContent;
}

export interface ArtifactPanelLabels {
  region: string;
  preview: string;
  source: string;
  diff: string;
  version: string;
  download: string;
  close: string;
  empty: string;
  imageAlt: string;
  tableEmpty: string;
}

export const ARTIFACT_PANEL_DEFAULT_LABELS: ArtifactPanelLabels = {
  region: '产物',
  preview: '预览',
  source: '源码',
  diff: '变更',
  version: '版本',
  download: '下载',
  close: '关闭',
  empty: '产物为空',
  imageAlt: '产物图片',
  tableEmpty: '没有可展示的数据行',
};

const KIND_ICON = {
  code: FileCode2,
  markdown: FileText,
  image: Image,
  data: Table,
} as const;

function jsonText(data: unknown): string {
  try {
    return JSON.stringify(data, null, 2) ?? '';
  } catch {
    return String(data);
  }
}

function DataTablePreview({
  data,
  emptyLabel,
}: {
  data: unknown;
  emptyLabel: string;
}) {
  if (!Array.isArray(data) || data.length === 0) {
    return <p className="text-xs text-content-text-muted">{emptyLabel}</p>;
  }
  const rows = data.filter(
    (row): row is Record<string, unknown> =>
      typeof row === 'object' && row !== null && !Array.isArray(row),
  );
  if (rows.length === 0) {
    return <p className="text-xs text-content-text-muted">{emptyLabel}</p>;
  }
  const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))];

  return (
    <div className="overflow-auto rounded-md border border-content-border">
      <table className="w-full border-collapse text-xs">
        <thead>
          <tr className="bg-content-bg-secondary">
            {columns.map((column) => (
              <th
                key={column}
                scope="col"
                className="border-b border-content-border px-2 py-1 text-start font-semibold whitespace-nowrap"
              >
                {column}
              </th>
            ))}
          </tr>
        </thead>
        <tbody>
          {rows.map((row, index) => (
            <tr key={index} className="even:bg-content-bg-secondary/40">
              {columns.map((column) => (
                <td
                  key={column}
                  className="border-b border-content-border-light px-2 py-1 align-top"
                >
                  {typeof row[column] === 'object'
                    ? jsonText(row[column])
                    : String(row[column] ?? '')}
                </td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

export interface ArtifactPanelProps
  extends Omit<ComponentProps<'section'>, 'children' | 'title' | 'content'> {
  title: string;
  /** 当前产物(versions 未传或非受控且无选中版本时使用) */
  content: ArtifactContent;
  /** 版本列表;与 versionId 同时使用 */
  versions?: ArtifactVersion[];
  /** 受控版本 id */
  versionId?: string;
  onVersionChange?: (id: string) => void;
  /** 受控视图 */
  view?: ArtifactView;
  defaultView?: ArtifactView;
  onViewChange?: (view: ArtifactView) => void;
  /** 变更视图内容;不传则不出现「变更」选项 */
  diff?: ReactNode;
  onDownload?: () => void;
  onClose?: () => void;
  /** 代码视图渲染器;缺省 CodeBlock */
  renderCode?: (content: Extract<ArtifactContent, { kind: 'code' }>) => ReactNode;
  /** Markdown 渲染视图渲染器;缺省 StreamingMarkdown(static 模式) */
  renderMarkdown?: (
    content: Extract<ArtifactContent, { kind: 'markdown' }>,
  ) => ReactNode;
  labels?: Partial<ArtifactPanelLabels>;
}

export function ArtifactPanel({
  title,
  content,
  versions,
  versionId,
  onVersionChange,
  view,
  defaultView = 'preview',
  onViewChange,
  diff,
  onDownload,
  onClose,
  renderCode,
  renderMarkdown,
  labels,
  className,
  ...props
}: ArtifactPanelProps) {
  const D = usePatternLabels('artifactPanel', ARTIFACT_PANEL_DEFAULT_LABELS);
  const text: ArtifactPanelLabels = {
    region: labels?.region ?? D.region,
    preview: labels?.preview ?? D.preview,
    source: labels?.source ?? D.source,
    diff: labels?.diff ?? D.diff,
    version: labels?.version ?? D.version,
    download: labels?.download ?? D.download,
    close: labels?.close ?? D.close,
    empty: labels?.empty ?? D.empty,
    imageAlt: labels?.imageAlt ?? D.imageAlt,
    tableEmpty: labels?.tableEmpty ?? D.tableEmpty,
  };

  const panelId = useId();
  const [innerView, setInnerView] = useState<ArtifactView>(defaultView);
  const currentView = view ?? innerView;

  const [innerVersionId, setInnerVersionId] = useState<string | undefined>(
    versionId ?? versions?.[0]?.id,
  );
  const currentVersionId = versionId ?? innerVersionId;
  const selectedVersion = versions?.find(
    (version) => version.id === currentVersionId,
  );
  const active = selectedVersion?.content ?? content;

  const changeView = (next: ArtifactView) => {
    if (view === undefined) setInnerView(next);
    onViewChange?.(next);
  };

  const changeVersion = (next: string) => {
    if (versionId === undefined) setInnerVersionId(next);
    onVersionChange?.(next);
  };

  const options: SegmentedOption<ArtifactView>[] = [
    { value: 'preview', label: text.preview },
  ];
  if (active.kind !== 'image') {
    options.push({ value: 'source', label: text.source });
  }
  if (diff !== undefined) {
    options.push({ value: 'diff', label: text.diff });
  }
  // 受控视图可能指向当前 kind 不可用的档位:回落到预览
  const effectiveView = options.some((option) => option.value === currentView)
    ? currentView
    : 'preview';

  const Icon = KIND_ICON[active.kind];

  return (
    <section
      aria-label={title || text.region}
      data-ai-component="artifact.panel"
      data-kind={active.kind}
      className={cn(
        'flex min-h-0 flex-col overflow-hidden rounded-lg border border-content-border bg-content-bg',
        className,
      )}
      {...props}
    >
      <header className="flex flex-wrap items-center gap-2 border-b border-content-border bg-content-bg-secondary px-3 py-2">
        <Icon aria-hidden className="size-4 shrink-0 text-content-text-muted" />
        <h3 className="min-w-0 flex-1 truncate text-xs font-semibold text-content-text">
          {title}
        </h3>

        {versions && versions.length > 1 ? (
          <Select value={currentVersionId} onValueChange={(next) => changeVersion(String(next))}>
            <SelectTrigger
              size="sm"
              aria-label={text.version}
              className="h-control-xs gap-1 border-0 bg-transparent px-1.5 text-2xs shadow-none"
            >
              <SelectValue />
            </SelectTrigger>
            <SelectContent>
              {versions.map((version) => (
                <SelectItem key={version.id} value={version.id}>
                  {version.label}
                </SelectItem>
              ))}
            </SelectContent>
          </Select>
        ) : null}

        <SegmentedControl
          value={effectiveView}
          options={options}
          onChange={changeView}
          variant="rect"
          className="shrink-0"
        />

        {onDownload ? (
          <Button
            type="button"
            variant="ghost"
            size="icon-xs"
            aria-label={text.download}
            title={text.download}
            onClick={onDownload}
          >
            <Download aria-hidden />
          </Button>
        ) : null}
        {onClose ? (
          <Button
            type="button"
            variant="ghost"
            size="icon-xs"
            aria-label={text.close}
            title={text.close}
            onClick={onClose}
          >
            <X aria-hidden />
          </Button>
        ) : null}
      </header>

      <div id={panelId} className="min-h-0 flex-1 overflow-auto p-3">
        {effectiveView === 'diff' ? (
          diff
        ) : effectiveView === 'source' ? (
          active.kind === 'code' ? (
            <pre className="overflow-auto rounded-md bg-content-bg-secondary p-3 font-mono text-xs whitespace-pre text-content-text">
              <code>{active.code}</code>
            </pre>
          ) : active.kind === 'markdown' ? (
            <pre className="overflow-auto rounded-md bg-content-bg-secondary p-3 font-mono text-xs whitespace-pre-wrap break-words text-content-text">
              {active.markdown}
            </pre>
          ) : active.kind === 'data' ? (
            <pre className="overflow-auto rounded-md bg-content-bg-secondary p-3 font-mono text-xs whitespace-pre-wrap break-words text-content-text">
              {jsonText(active.data)}
            </pre>
          ) : null
        ) : active.kind === 'code' ? (
          renderCode ? (
            renderCode(active)
          ) : (
            <CodeBlock
              code={active.code}
              language={active.language}
              filename={active.filename}
              showLineNumbers
            />
          )
        ) : active.kind === 'markdown' ? (
          renderMarkdown ? (
            renderMarkdown(active)
          ) : (
            <StreamingMarkdown content={active.markdown} />
          )
        ) : active.kind === 'image' ? (
          <img
            src={active.src}
            alt={active.alt ?? text.imageAlt}
            className="mx-auto max-h-full max-w-full rounded-md object-contain"
          />
        ) : active.format === 'table' ? (
          <DataTablePreview data={active.data} emptyLabel={text.tableEmpty} />
        ) : (
          <pre className="overflow-auto rounded-md bg-content-bg-secondary p-3 font-mono text-xs whitespace-pre-wrap break-words text-content-text">
            {jsonText(active.data)}
          </pre>
        )}
      </div>
    </section>
  );
}

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

用法说明

产物面板:code/markdown/image/data 四类;preview/source/diff 三视图;版本切换受控/非受控双模。静态依赖 code-block 与 streaming-markdown,只能按子路径引入。