企业官网建设流程全解析

导读

Artifact是 ZCode（Z.ai 的开源 coding agent harness）中用于承载 AI 生成内容（代码、文档、分析结果等）的结构化容器组件：它自带头部区域与内容区域，头部可容纳标题、描述与一组带 tooltip 的操作按钮，从而把"展示生成结果"与"对结果执行动作"统一到同一个可复用的 UI 单元中。本文以仓库中的 artifact.md 为骨架，结合 artifact.tsx 示例与 packages/ui 中的组件实现，完整讲解组件树、全部 Props、典型组合方式以及底层实现细节，帮助你在 ZCode 及其 UI 包中快速上手并二次定制。

Artifact 是什么：定位与适用场景

Artifact组件为"展示 AI 生成内容"这一高频交互提供结构化容器。典型场景包括：

• 展示模型生成的代码片段（如算法实现、脚本），并配合"运行 / 复制 / 下载"操作；
• 展示生成文档或分析结果，头部给出标题与更新时间等元信息；
• 在 AI 对话界面中组织一个可操作、可关闭、可复用的"产出物"卡片。

在 ZCode 仓库中，Artifact 属于ai-elements组件体系。这一体系源自 Vercel 的 ai-elements，ZCode 将其本地化集成，并注入了"use client"指令与 ZCode 自有的 UI 基础件。组件本体位于 packages/ui/src/components/ai-elements/artifact.tsx，可组合示例位于 .agents/skills/ai-elements/scripts/artifact.tsx，组件文档则记录于 .agents/skills/ai-elements/references/artifact.md。

注：references 中提到的scripts/artifact.tsx是相对该 skill 目录的示例文件，并非仓库根目录脚本；它演示"如何使用 Artifact"，而不是应用内置功能。

特性一览

按原文档归纳，Artifact 具备以下能力：

• 结构化的容器：头部区域与内容区域分离；
• 内置头部：支持标题（title）与描述（description）；
• 灵活的操作按钮：可带 tooltip，支持任意动作；
• 所有子组件均可定制样式（通过className）；
• 支持关闭按钮与操作按钮组；
• 简洁现代的外观：边框、圆角与阴影；
• 响应式布局：内容区可滚动，自适应内容；
• 完整的 TypeScript 类型定义；
• 可组合架构：以Artifact为根，自由拼装子组件。

组件树与职责划分

Artifact 采用复合组件（compound component）设计，完整结构如下：

<Artifact> <ArtifactHeader> <div> <ArtifactTitle>...</ArtifactTitle> <ArtifactDescription>...</ArtifactDescription> </div> <ArtifactActions> <ArtifactAction ... /> <ArtifactClose ... /> </ArtifactActions> </ArtifactHeader> <ArtifactContent>...</ArtifactContent> </Artifact>

各组件职责：

全部 Props 参考

<Artifact />

<ArtifactHeader />

<ArtifactTitle />

<ArtifactDescription />

<ArtifactActions />

<ArtifactAction />

<ArtifactClose />

<ArtifactContent />

完整示例：展示一段生成的代码

原文档与示例脚本都演示了"Artifact + 代码展示"的典型用法。下面给出与 artifact.tsx 示例 等价的完整可运行代码：

"use client"; import { Artifact, ArtifactAction, ArtifactActions, ArtifactContent, ArtifactDescription, ArtifactHeader, ArtifactTitle, } from "@/components/ai-elements/artifact"; import { CodeBlock } from "@/components/ai-elements/code-block"; import { CopyIcon, DownloadIcon, PlayIcon, RefreshCwIcon, ShareIcon } from "lucide-react"; const handleRun = () => console.log("Run"); const handleCopy = () => console.log("Copy"); const handleRegenerate = () => console.log("Regenerate"); const handleDownload = () => console.log("Download"); const handleShare = () => console.log("Share"); const code = `# Dijkstra's Algorithm implementation import heapq def dijkstra(graph, start): distances = {node: float('inf') for node in graph} distances[start] = 0 heap = [(0, start)] visited = set() while heap: current_distance, current_node = heapq.heappop(heap) if current_node in visited: continue visited.add(current_node) for neighbor, weight in graph[current_node].items(): distance = current_distance + weight if distance < distances[neighbor]: distances[neighbor] = distance heapq.heappush(heap, (distance, neighbor)) return distances # Example graph graph = { 'A': {'B': 1, 'C': 4}, 'B': {'A': 1, 'C': 2, 'D': 5}, 'C': {'A': 4, 'B': 2, 'D': 1}, 'D': {'B': 5, 'C': 1} } print(dijkstra(graph, 'A'))`; const Example = () => ( <Artifact> <ArtifactHeader> <div> <ArtifactTitle>Dijkstra&apos;s Algorithm Implementation</ArtifactTitle> <ArtifactDescription>Updated 1 minute ago</ArtifactDescription> </div> <div className="flex items-center gap-2"> <ArtifactActions> <ArtifactAction icon={PlayIcon} label="Run" onClick={handleRun} tooltip="Run code" /> <ArtifactAction icon={CopyIcon} label="Copy" onClick={handleCopy} tooltip="Copy to clipboard" /> <ArtifactAction icon={RefreshCwIcon} label="Regenerate" onClick={handleRegenerate} tooltip="Regenerate content" /> <ArtifactAction icon={DownloadIcon} label="Download" onClick={handleDownload} tooltip="Download file" /> <ArtifactAction icon={ShareIcon} label="Share" onClick={handleShare} tooltip="Share artifact" /> </ArtifactActions> </div> </ArtifactHeader> <ArtifactContent className="p-0"> <CodeBlock className="border-none" code={code} language="python" showLineNumbers /> </ArtifactContent> </Artifact> ); export default Example;

要点说明：

• 每个ArtifactAction同时给出icon（视觉图标）、label（无障碍文本）与tooltip（悬停提示）；若未传icon，也可直接以children放入自定义内容；
• ArtifactContent通过className="p-0"去掉内边距，让内嵌的CodeBlock紧贴内容区；CodeBlock使用className="border-none"消除重复边框，实现"无边框嵌合"效果；
• 在 ZCode 的 UI 包中，CodeBlock是增强版组件，支持 shiki 语法高亮、行号、Mermaid 渲染与行定位（见 code-block.tsx），示例中的language、showLineNumbers均由其透传处理。

源码级实现解析

packages/ui/src/components/ai-elements/artifact.tsx 完整实现了上述组件树，关键细节如下：

容器与布局（Artifact）：使用flex flex-col overflow-hidden rounded-lg border bg-background shadow-sm，即纵向弹性布局、圆角边框、背景色与轻阴影，配合overflow-hidden保证内容溢出时不破坏圆角。

头部条（ArtifactHeader）：使用flex items-center justify-between border-b bg-muted/50 px-4 py-3，左标题右操作，底部边框分隔，浅灰底与内边距形成视觉分区。

标题与描述：ArtifactTitle渲染为<p>，使用font-medium text-foreground text-ui-base；ArtifactDescription同样为<p>，使用text-muted-foreground，与标题形成主次层次。

操作按钮（ArtifactAction）：默认size="sm"、variant="ghost"的Button，图标尺寸size-4，同时渲染一个sr-only的隐藏文本（取label || tooltip）保证无障碍可读性。当传入tooltip时，按钮会被包进TooltipProvider > Tooltip > TooltipTrigger(asChild)结构，借助 ZCode 基于 Radix 的 Tooltip 组件（tooltip.tsx）实现悬停提示。

关闭按钮（ArtifactClose）：同样是 ghost 风格的小按钮，未提供children时默认渲染XIcon，并附带sr-only的 "Close" 文本。

内容区（ArtifactContent）：使用flex-1 overflow-auto p-4，即占据剩余高度并支持独立滚动，配合Artifact的overflow-hidden形成"头部固定、内容滚动"的经典布局。

从类型定义看，ArtifactActionProps = ComponentProps<typeof Button> & { tooltip?: string; label?: string; icon?: LucideIcon }，因此onClick、disabled、variant等 Button 原生能力全部可用。

在 ZCode 中的集成方式与前置条件

在 ZCode 仓库中，ai-elements 组件已作为源码直接集成进 UI 包：组件目录为 packages/ui/src/components/ai-elements/，其中artifact.tsx与code-block.tsx、message.tsx等组件共享同一套基于 shadcn/ui 的基础件（Button、Tooltip 等）。

接入 Artifact 组件需要满足以下前置条件（均已在 packages/ui/components.json 与 ui 包中配置就绪）：

• 项目基于 shadcn/ui 风格配置，components.json中aliases将@/指向源码根目录（"components": "@/components"、"ui": "@/components/ui"），并声明了@ai-elements注册源；
• Tailwind 使用 CSS 变量（cssVariables: true）与 lucide 图标库（iconLibrary: "lucide"）；
• 依赖lucide-react（ui 包 package.json 中声明）与 Radix 系列组件（Tooltip 等）。

在其他项目中使用时，可通过以下任一方式安装：

# 方式一：使用 ai-elements CLI 安装（推荐） npx ai-elements@latest add artifact # 方式二：使用 shadcn/ui CLI，指定 @ai-elements 注册源 npx shadcn@latest add artifact --registry @ai-elements

安装后组件代码会落到项目的components/ai-elements/目录，随后即可像上文示例那样直接导入使用。由于组件以源码形式存在，你可以直接打开artifact.tsx修改默认样式或扩展行为。

提示：如果项目已有 shadcn 工作流，建议按项目的packageManager选择对应的 runner，例如pnpm dlx ai-elements@latest或bunx --bun ai-elements@latest。

常见问题排查

• 组件未渲染任何样式：确认全局样式文件（globals.css）已引入 Tailwind 与 shadcn/ui 基础样式；ZCode 的 ui 包以src/styles.css为样式入口（见 components.json）。
• 导入报 "module not found"：确认tsconfig.json已配置@/*路径别名指向组件目录，并确认目标文件确实存在。
• 希望调整按钮数量或布局：直接增删ArtifactActions内的ArtifactAction，或替换ArtifactContent中的内容组件即可，无需改动 Artifact 本体。

小结

Artifact是 ZCode 中组织 AI 生成内容的标准容器：Artifact+ArtifactHeader（标题/描述）+ArtifactActions（带 tooltip 的动作按钮）+ArtifactContent（可滚动内容区）的组合，既能整齐呈现代码、文档等产出物，又能把运行、复制、重新生成、下载、分享等操作就近安放。无论是直接复用仓库中的 组件实现，还是参考 示例脚本 在自有项目中组合定制，本文列出的组件树、Props 表与实现要点都可以作为你接入和改造的直接依据。