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 | — | — |
源码
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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
产物面板:code/markdown/image/data 四类;preview/source/diff 三视图;版本切换受控/非受控双模。静态依赖 code-block 与 streaming-markdown,只能按子路径引入。