網站合約

描述您網站的元件、頁面類型、集合、全域內容、媒體設定檔與設計代碼的 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"]
    }
  ]
}

區域決定編輯者能做什麼：區塊可以是必要、預設或選用；區域可以鎖定或允許重新排序，並設有區塊數量的下限與上限，以及可插入的元件清單。欄位可以綁定到頁面的項目，因此可依集合為每個產品或產業各建立一個頁面。

欄位型別

型別	用途	限制
`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 個欄位。