canvas-component-definition

项目类型

应用此技能前，请检查 package.json 中是否存在名为 @drupal-canvas/headless 或以 @drupal-canvas/headless- 开头的依赖项。如果存在， 这是一个 Canvas Headless 代码库——请先阅读 canvas-headless；其中的指导优先于下方针对 React 的说明。如果不存在此类依赖项，则这是一个 Canvas 渲染的 React 代码库：组件采用 React（index.jsx/.tsx），且本技能中的所有内容均按原样适用。这是仅有的两种项目类型。

规范定义

Canvas 组件是由以下部分组成的包：

1. 实现入口文件（React 项目中的 index.jsx；无头项目中的 index.vue、index.astro 或类似文件——参见 canvas-headless）
2. Canvas 元数据/架构（component.yml）
3. 命名和结构兼容性（machineName、文件夹路径、Workbench mock 路径）
4. 符合 Canvas 规范的 props/slots 建模
5. 用于编写预览状态的 Workbench mock 覆盖

前四部分是组件可在 Drupal Canvas 中使用的必要条件。Workbench mock 是 Workbench 内置的 Default 标签页之外，编写命名预览状态的受支持方式。

最低契约（MUST）

每个 Canvas 组件都必须满足以下所有检查项：

• 组件文件夹位于 <components-root>/<machine-name>/（使用仓库配置的组件根目录，该目录可能在 .env 中定义）
• 实现入口文件位于 <components-root>/<machine-name>/index.jsx（无头项目中则使用相应框架的扩展名）
• 元数据位于 <components-root>/<machine-name>/component.yml
• component.yml 包含必需的顶层键（name、machineName、 status、required、props、slots）
• 文件夹名称与 component.yml 中的 machineName 完全一致（kebab-case）
• Props/slots 符合 Canvas 规则（例如，避免使用不受支持的对象数组 prop 结构；对于可重复的复杂内容，应使用 slots）
• 不要将可重复的卡片/项目扁平化为编号 prop 组，例如 card1Title、card2Title 或 car3Image；应将其建模为父级 slot 内容加子项组件
• 任何表示图片的 prop 都应使用单个对象 prop，并设置 $ref: json-schema-definitions://canvas.module/image；不要将一张图片拆分为 imageUrl、imageAlt、imageWidth 或类似的字符串/数字 props
• 任何表示已选 Drupal 实体的 prop 都应使用 $ref: json-schema-definitions://canvas.module/content-entity-reference，并在 component.yml 中包含匹配的 dataDependencies.entityFields.<propName> 条目

如果缺少任何一项，该组件对于 Canvas 使用而言就不完整。

对于本地编写和审查，请在组件源文件和元数据旁添加匹配的 Workbench mock 文件：

• 在组件入口文件和 component.yml 旁使用 mocks.json
• 只要组件需要自动生成的 Default 标签页之外的预览，就至少编写一个命名 mock；该标签页会使用 component.yml 中每个 prop 的第一个示例值渲染组件

如果组件的渲染输出发生变化，但 Workbench 预览覆盖不足，则变更尚未完成。

命名指南

此代码库已针对某个项目或产品，因此组件名称不需要（也不得使用）项目或产品前缀。machineName、文件夹名称和显示名称应保持通用且可移植（例如 hero、contact-form），不要使用 acme-hero 或 nebula-contact-form。

默认使用最简洁且可复用的基础名称。像“simple hero”“solid hero”“cream hero”或“two cards”这样的需求，通常仍应使用 Hero 或 Card，并通过 props、变体、组合或 mock 名称表达差异，而不是体现在组件名称本身。仅当组件确实是一次性专用组件时，才使用专门名称。

命名规则和示例请参阅 references/naming.md。

创建前检查复用情况

创建新组件前，请检查现有工作区组件是否可以满足请求，尤其是用户指定要复用、组合或包装特定组件时。

这是复用优先政策的权威说明。其他技能应链接到此处，而不是重述相同的决策树。

• 如果现有组件已经适用，或通过合理的扩展、变体或轻量包装即可适用，则应复用。
• 不要悄悄创建替代组件，绕过现有组件。
• 不要悄悄用新的实现替换用户指定的现有组件。
• 如果现有组件不适用，请说明不匹配之处，并审慎决定是扩展、包装，还是创建新的专用组件。
• 如果不匹配和取舍会影响请求是否仍得到遵循，请明确说明。

Workbench 模拟组件

有关模拟组件的命名、放置、格式选择和验证，请使用 references/component-mocks.md。

技能协作

按以下顺序评估是否使用配套技能。

0. canvas-design-decomposition
   • 当需要将设计（Figma 画板、截图、抓取的页面或文字规格）拆解为区域、组件树以及明确的 props 与 slots 时，应在规划工作结构之前使用。此技能负责制定计划；本技能（canvas-component-definition）负责执行生成的文件夹规范和实现。若只是在编辑边界已明确的现有组件，则跳过步骤 0。
1. canvas-component-metadata
   • 创建或更改 component.yml、props/slots、枚举，或修复 prop 验证错误时使用。
2. canvas-component-composability
   • 设计 prop/slot 结构、拆分大型组件、决定使用 props 还是 slots、复用/组合/包装现有组件，或建模可重复的列表/网格内容时使用。
3. canvas-styling-conventions
   • 所有样式工作均使用：新组件、样式 props、Tailwind 令牌的使用、CVA 变体、类名变更，以及会影响样式的 prop 变更。
4. canvas-component-utils
   • 使用 FormattedText 和 Image 渲染格式化 HTML 文本或媒体时使用。
5. canvas-data-fetching
   • 使用 JSON:API、SWR、includes 和过滤模式获取/渲染 Drupal 内容，或读取页面/站点上下文以生成面包屑、品牌信息、实体元数据和语言切换器时使用。
6. 预览覆盖就绪情况
   • 确保 Default 示例和任何编写的 mocks.json 状态足以供审查所请求的更改。
7. canvas-component-push（可选）
   • 仅当用户明确要求将组件推送/发布/同步到 Canvas 时使用。
   • 实现或静态验证后不要自动运行推送。