站点契约

描述您网站的组件、页面类型、集合、全局内容、媒体配置和设计令牌的 JSON 包。

本页面由英文翻译而来。如有任何差异，以英文版本为准。阅读英文版

站点契约是您网站的代码与 Atlas 之间的约定。它列出您的站点上存在什么，以及编辑人员可以更改什么。它不包含可执行代码：只有描述和类型化字段。

请将它保存在您的代码仓库中（例如 atlas/contract.bundle.json），并与代码一起进行版本管理。

生命周期

开发人员或通过 MCP 的 AI 智能体对该包进行验证并提出。
站点管理员在 Studio 的 Site setup 下审阅并激活（或拒绝）它。
您的网站报告它所渲染的包的摘要（POST /deployments）。Studio 显示代码与契约是否已同步。

摘要是该包规范化 JSON 的 SHA-256 哈希值，因此您代码仓库中的包必须与您所提出的包完全一致。

顶层结构

键	内容
`contractVersion`	此格式始终为 `1.0.0`
`bundleVersion`	您为此包设定的版本，例如 `1.4.0`
`site`	`key`、`displayName`、`runtimes`（`node`、`cloudflare-workers`）、`locales`（默认、支持、从右到左）、由您的代码负责的 `staticRoutes`
`tokens`	编辑人员可以选择的颜色、字体样式和间距
`motion`	由您的代码实现的命名动画预设，包含减少动态效果时的行为
`mediaProfiles`	允许的图片尺寸、比例和渲染图
`components`	最多 300 个组件，每个都有限定 id、版本、类型和字段
`collections`	重复性内容类型，包含字段、标题和 slug 字段以及唯一性规则
`pageTypes`	最多 100 个页面类型：路由模式、可选的绑定集合、区域和 SEO 规则
`globals`	共享内容，例如 `site-header` 和 `site-footer`

组件（节选）

{
  "id": "acme.home.hero",
  "version": "1.0.0",
  "kind": "section",
  "label": "Home hero",
  "fields": [
    { "key": "heading", "type": "text", "label": "Heading", "required": true, "maxLength": 80 },
    { "key": "intro", "type": "longText", "label": "Intro", "maxLength": 400 },
    { "key": "image", "type": "asset", "label": "Image", "profile": "hero" },
    { "key": "cta", "type": "link", "label": "Button" }
  ]
}

页面类型（节选）

{
  "key": "industry-landing",
  "version": "1.0.0",
  "label": "Industry landing",
  "route": { "pattern": "/industries/{entry.slug}" },
  "entry": { "collection": "industries", "mode": "one-page-per-entry" },
  "regions": [
    {
      "key": "hero",
      "reorder": "locked",
      "sections": [
        {
          "key": "hero",
          "component": { "id": "acme.industry.hero", "versionRange": "^1.0.0" },
          "presence": "required",
          "bind": { "headline": "entry.headline", "image": "entry.image" }
        }
      ]
    },
    {
      "key": "body",
      "reorder": "within-region",
      "min": 1,
      "max": 20,
      "insertable": ["acme.text", "acme.faq"]
    }
  ]
}

区域决定编辑人员可以做什么：区块可以是必需（required）、默认（default）或可选（optional）；区域可以锁定或允许重新排序，并可设置区块数量的最小值和最大值以及可插入组件的列表。字段可以绑定到页面的条目，因此可以根据集合为每个产品或行业创建一个页面。

字段类型

类型	用途	限制
`text`	简短的单行文本	最多 500 个字符
`longText`	段落，无格式	最多 10,000 个字符
`richText`	带格式文本，`basic` 或 `article` 配置	结构化，绝不是原始 HTML
`number`	数字，可选范围
`boolean`	开/关
`select`	固定列表中的一项	最多 100 个选项
`date`	日期
`link`	内部路由，或在允许时使用外部 URL
`asset`	某个媒体配置中的图片	每个字段最多 50 个
`reference`	指向某个集合条目的链接	每个字段最多 200 个
`list`	重复的字段组	最多 200 项，每项 40 个字段
`group`	放在一起的字段	最多 40 个字段
`table`	行和类型化的列	最多 12 列，200 行
`token`	您的某个设计令牌（颜色、字体样式、间距）
`icon`	由您的代码提供的命名图标集中的一个	最多 200 个选项

字段可以标记为 required 和 localized。一个组件或集合最多可以有 80 个字段。