组件与注册表

Atlas 绝不会向您的网站交付组件。您的组件始终保留在您的代码仓库中。站点契约告诉 Atlas 存在哪些组件，以及编辑人员可以填写哪些字段。

如何声明组件

契约中的每个组件都有：

• 一个限定 id，例如 acme.home.hero，以及一个版本；
• 一个类型（kind）：section、block 或 layout；
• 类型化字段，例如 heading（文本，必填，最多 80 个字符）、image（资源）和 cta（链接）。

编辑人员看到的是根据这些字段生成的表单。他们无法添加字段、粘贴 HTML 或修改您的标记。

您的网站如何渲染它

请在代码中维护一个小型注册表，将每个组件 id 映射到渲染它的 React 组件：

atlas/sections.tsx

import { Hero } from '@/components/hero';
import { FeatureGrid } from '@/components/feature-grid';
import type { AtlasSection } from '@/lib/atlas';

const registry = {
  'acme.home.hero': Hero,
  'acme.home.features': FeatureGrid,
} as const;

export function renderSection(
  section: AtlasSection,
  assets: Record<string, { url: string; alt?: string }>,
) {
  const Component = registry[section.component.id as keyof typeof registry];
  if (!Component) return null; // unknown component: skip it, never guess
  return <Component key={section.id} {...section.props} assets={assets} />;
}

请像验证任何外部输入一样，验证组件接收到的 props。

保持代码与内容同步

您的网站在启动时会报告它所构建的组件（POST /deployments）。Studio 会将其与当前生效的契约进行比较，并显示以下状态之一：

状态	含义
In sync（已同步）	已部署的构建渲染的是当前生效的契约
Missing components（缺少组件）	契约使用了此构建中没有的组件。请先部署代码
Different contract（契约不同）	此构建是为契约的另一个版本而制作的
Unknown contract（未知契约）	Atlas 从未见过此构建所报告的契约
No contract（无契约）	尚未激活任何契约

在网站与契约不同步时，生产环境的发布版本无法获得批准。这可防止编辑人员使用线上站点尚不存在的组件。

添加新组件

1. 在您的网站代码中构建并测试该组件。
2. 将它连同其字段添加到契约包中，并添加到允许编辑人员插入它的页面类型中。
3. 验证并提出契约。由站点管理员将其激活。
4. 部署网站。Studio 显示 In sync。
5. 编辑人员现在即可使用它。