canvas-regions

旧版范围

Region 和 RegionsProvider 已弃用，应改用页面变体和组合式页面树。现有集成仍可正常工作；请勿引入新的区域提供程序集成，也不要自动迁移现有区域文件。

以下说明仅适用于维护现有的主题全局区域工作流。对于新的网站框架，请查阅目标 Canvas 版本的页面变体文档，不要将这些区域规范视为当前的创作模型。页面变体迁移是单独的任务。

项目类型

应用此技能前，请检查 package.json 中是否有名为 @drupal-canvas/headless 或以 @drupal-canvas/headless- 开头的依赖。如果存在，则这是 Canvas Headless 代码库——请先阅读 canvas-headless。Headless 项目不支持全局区域；此技能不适用于这类项目。如果不存在此类依赖，则这是 Canvas 渲染的 React 代码库：组件使用 React（index.jsx/.tsx）；仅当项目已使用主题全局区域时，才应用以下旧版指南。这是仅有的两种项目类型。

规范定义

Canvas 区域是一个 JSON 区域规范，存储在仓库配置的 regionsDir 中。每个区域对应特定主题的一个 Drupal 主题区域（例如 header、 footer、sidebar_first），其 elements 树会在使用该主题的每个页面中渲染到此区域。

Canvas CLI 的 push/pull 工作流使用这些文件，在本地项目和 Drupal Canvas 之间同步区域。

最低要求（MUST）

每个 Canvas 区域都 MUST 满足以下所有检查：

• 区域文件存在于配置的区域目录中（canvas.config.json 中的 regionsDir；默认为 ./regions）
• 区域文件是一个 JSON 对象
• 文件名为 <region-machine-name>.json，其中机器名称符合 ^[a-z0-9_]+$
• JSON 中包含布尔值 status（表示区域是否已启用）
• JSON 中包含 elements 对象（可以为空）
• elements 中的每个元素都包含已发现的组件 type
• 所有 slots 条目均引用同一文件中定义的元素 ID

位置和命名

在配置的区域目录（canvas.config.json 中的 regionsDir）中编写规范的本地区域规范。如果未设置 regionsDir，则默认为顶层 regions/ 目录。

• 将每个区域放在 <regions-dir>/<region-machine-name>.json 中
• 区域文件在配置的区域目录中保持平铺；嵌套文件会被忽略
• 去掉 .json 后的文件名即为区域机器名称
• 文件名允许使用的字符：小写字母、数字和下划线 （^[a-z0-9_]+$）

示例：

• <regions-dir>/header.json
• <regions-dir>/footer.json
• <regions-dir>/sidebar_first.json

区域文件格式

每个区域文件都必须是一个包含以下内容的 JSON 对象：

• status：布尔值 — true 表示启用区域，false 表示禁用区域
• elements：由编写的区域元素组成的对象（对于没有 Canvas 管理内容的区域，可以为空）

元素

elements 的结构与 Canvas 页面规范相同——完整的元素要求、插槽语义、图像属性结构和格式约束，请参阅 canvas-page-definition 技能。

简而言之，elements 中的每个条目都必须包含：

• type：已发现的组件类型（例如 js.section、js.heading）

每个条目还可以包含：

• props：该元素的根属性
• slots：将插槽名称映射到同一文件中元素 ID 数组的映射

构建区域时会保留元素的插入顺序——请按所需的渲染顺序放置顶层分区。

除非有意保留来自其他来源（例如导出的 Canvas 区域）的 ID，否则请使用稳定且描述清晰的元素 ID。

示例

{
  "status": true,
  "elements": {
    "header-section": {
      "type": "js.section",
      "props": {
        "width": "wide"
      },
      "slots": {
        "content": ["site-logo", "primary-nav"]
      }
    },
    "site-logo": {
      "type": "js.logo",
      "props": {
        "alt": "Site logo"
      }
    },
    "primary-nav": {
      "type": "js.navigation",
      "props": {
        "menu": "main"
      }
    }
  }
}

空白但已启用的区域是有效的，可用作远程服务上已存在但尚无 Canvas 编写内容的区域的占位符：

{
  "status": true,
  "elements": {}
}

格式约束

区域沿用页面规范格式，并遵循相同的约束。区域规范仅支持已发现的组件元素及其 props 和 slots。它们无法直接表示：

• 手写的 React 包装组件
• 原始 HTML 布局元素，例如 <div> 或 <section>
• 由 className 控制的间距或自定义包装样式
• 内联代码重复编写现有组件的标记

如果需要布局基元，请先查找现有组件。如果没有，请先将其创建为组件（参见 canvas-component-definition），再在区域规范中使用。

布局

区域文件声明每个区域中有哪些组件——它们不会决定页眉、页脚或侧边栏在页面周围的位置。该排列由项目级布局组件负责。

布局组件

在 canvas.config.json 中 layoutPath 配置的路径下创建一个布局文件（默认为 ./src/layout.jsx）。该文件必须：

• 默认导出一个接受 { children } 的 React 组件。
• 将 children 放置在每页内容应呈现的位置。
• 使用 drupal-canvas 中的 Region 组件，按名称（与本地区域文件名匹配）将每个区域放置在 children 周围的所需位置。

布局是唯一用于安排区域彼此之间以及相对于页面位置的地方——请用它控制垂直顺序（例如，页眉 → 页面 → 页脚）、侧边栏位置以及任何结构性框架。各个区域 JSON 文件没有同级区域的概念。

如果不存在布局文件，区域文件仍会通过验证并可执行 push，但不会出现在本地预览中。

布局组件示例

import { Region } from 'drupal-canvas';

export default function Layout({ children }) {
  return (
    <>
      <Region name="header" />
      <main>{children}</main>
      <Region name="footer" />
    </>
  );
}

每个 <Region name="…" /> 都会渲染匹配区域 JSON 文件中的元素（例如 regions/header.json）。name 属性必须与区域文件名（不含 .json 扩展名）匹配。

区域与布局各自包含的内容

• 区域 — Canvas 编写的可替换内容（徽标、主导航、页脚列、促销横幅）。可在 Canvas 中编辑，并通过 push/pull 同步。
• 布局 — 结构性脚手架（外层页面包装元素、<header>/<footer> HTML 元素、跳过链接、主题提供程序、children 周围的区域顺序）。这些是代码，不是编写的内容。
• JSON 中的区域机器名称必须与布局读取的名称匹配。添加新区域意味着：(1) 添加 <regions-dir>/<name>.json；(2) 在布局组件中渲染该名称。

布局范围

布局组件仅控制本地预览。在 Drupal 线上站点中，主题会根据自身的区域定义决定区域位置。请使布局与目标主题保持一致，以便预览忠实反映生产环境。

区域与页面

• 页面通过 path 寻址，并在单个 URL 上渲染。区域通过区域机器名称寻址，并使用该主题在每个页面上渲染。
• 区域文件不包含 title、path 或 description。
• 使用区域承载站点框架内容（页眉、页脚、侧边栏）。使用页面承载具有唯一 URL 的内容。
• 应在每个页面上显示的内容应放在区域中，而不是在多个页面规范中重复。

工作流

创建新区域

1. 确认区域机器名称 — 文件名必须与目标主题声明的区域机器名称一致。如果不确定，请检查 Drupal 主题的 .info.yml，或询问用户。
2. 检查是否已有区域文件 — 列出已配置的区域目录； 除非用户要求，否则不要覆盖现有区域。每个区域机器名称只能有一个文件。
3. 选择组件 — 查看 src/components/，并选择 component.yml 属性/插槽与布局相匹配的组件。优先使用现有组件，而不是创建新组件。
4. 选择元素 ID — 使用稳定且描述性强的 ID。
5. 按照上述格式编写 JSON 文件；文件名必须与某个区域的机器名称一致。

修改现有区域

1. 读取现有区域文件，了解其当前结构。
2. 保留未更改元素的现有元素 ID — 远程端可能会通过 ID 引用这些元素。
3. 为新增元素选择描述性 ID。
4. 验证插槽引用 — 插槽中的所有 ID 都必须存在于 elements 中。
5. 除非有意更改目标，否则不要重命名文件；重命名会更改该区域在远程端的标识，并可能创建重复项。

验证

完成前，验证每个编写的区域。

npx canvas validate