create-component

AEM 组件创建技能

按照 Adobe 最佳实践创建完整的 AEM 组件。

配置门检查 — 首先执行

必须先进行此配置检查，否则此技能会使用错误的项目路径和包名称，导致生成的每个文件都不正确。

首次工具调用：读取项目根目录（与 pom.xml 位于同一级别）中的 .aem-skills-config.yaml。

检查：文件是否存在，且是否包含 configured: true？

状态	操作
文件缺失或 configured: false	停止并显示下方的错误消息。不要检查代码库或继续操作——正确的文件路径和命名需要这些配置值。等待用户完成配置。
configured: true	从 YAML 文件中读取项目、包和组的值。继续创建组件。

如果未配置，显示此消息并停止：

Project configuration required!

Before creating components, configure your project settings in:
`.aem-skills-config.yaml` (in your project root, same level as pom.xml)

Open the file and update:
- project: Your AEM project name (e.g., 'mysite', 'wknd')
- package: Your Java package (e.g., 'com.mysite.core')
- group: Your component group (e.g., 'MySite Components')
- configured: true

After updating, ask me to create the component again.

为什么未配置时不应检查代码库：

在配置完成前执行以下任何操作，都会导致假设错误并浪费精力：

• 读取仓库中的任何其他文件
• 列出目录以“了解项目”
• 检查现有组件以寻找模式
• 查看 pom.xml、Java 文件或文件夹结构
• 从任何来源推断值

配置文件是项目值的唯一可信来源——跳过此步骤会导致每个生成文件的路径和包名称都错误。

禁止臆造规则

只创建用户明确指定的字段——添加额外字段会造成内容创作混乱并增加维护负担，重命名字段则会破坏内容契约。

完整规则参考： references/no-hallucination-rules.md

工作流概览

步骤	操作
0	配置验证（首先执行——见上文）
1	提取并验证组件名称
1.5	组件扩展决策（如需扩展）
2	收集需求并确认对话框规范
2.3	获取 Figma 设计（如提供 Figma URL）
3	创建所有组件文件
3.11	依赖项验证（Servlet 必须执行）
4	完成摘要

步骤 0：配置验证

0.1 读取配置

1. 从项目根目录读取 .aem-skills-config.yaml
2. 检查是否包含 configured: true
3. 读取 project、package 和 group 的值

0.2 验证 — 仅使用配置文件

不要根据文件系统、现有组件、Java 文件、pom.xml 或既有知识推断项目值。这些来源可能已经过时或彼此不一致——.aem-skills-config.yaml 是唯一可信来源，因为它由用户明确设置。

0.3 加载约定

1. 阅读 references/aem-conventions.md，了解文件结构模板、命名约定和模式

0.4 项目状态分析（配置验证通过后）

1. 检查组件名称是否唯一 - 查看 /apps/[project]/components/
2. 检查模型类冲突 - 查看 core/src/main/java/[package-path]/models/
3. 分析现有模式 - 查看 1–2 个最近的组件，以参考其风格

步骤 1：提取并验证组件名称

• 从用户消息中解析组件名称（如未提供则询问）
• 规范化为小写 kebab-case（例如，My Component -> my-component）
• 验证：以字母开头，只包含字母、数字和连字符，且不含连续连字符

步骤 1.5：组件扩展决策

当用户说“扩展 {component}”时：

第 1 层：先检查项目组件

• 搜索 /apps/{project}/components/{component}
• 如果找到 -> 用作 sling:resourceSuperType

第 2 层：检查核心组件

用户说	映射到
image	core/wcm/components/image/v3/image
teaser、card	core/wcm/components/teaser/v2/teaser
text、richtext	core/wcm/components/text/v2/text
title、heading	core/wcm/components/title/v3/title
list	core/wcm/components/list/v4/list
button、cta	core/wcm/components/button/v2/button
navigation、nav	core/wcm/components/navigation/v2/navigation
container、section	core/wcm/components/container/v1/container
accordion	core/wcm/components/accordion/v1/accordion
tabs	core/wcm/components/tabs/v1/tabs
carousel	core/wcm/components/carousel/v1/carousel
embed、video	core/wcm/components/embed/v2/embed

第 3 层：未找到 — 请用户进一步说明。

对于扩展模式，加载： references/extending-core-components.md

步骤 1.6：核心组件扩展要求

使用“隐藏”“移除”“添加自定义字段”或“覆盖”进行扩展时必须执行（这些操作需要 Sling Resource Merger 模式才能正确运行）：

加载参考文档： references/extending-core-components.md

用户请求	操作
“添加自定义字段”	创建新选项卡，或添加到现有选项卡
“隐藏 {tab}”	使用 sling:hideResource="{Boolean}true"
“隐藏 {field}”	使用 sling:hideResource="{Boolean}true"
“覆盖 {field}”	使用 sling:hideProperties + 新值

扩展核心组件时：

• 使用 @Self @Via(type = ResourceSuperType.class) 进行模型委托
• 实现 ComponentExporter 接口
• 将 resourceType 添加到 @Model 注解
• 在对话框中对继承的选项卡/字段使用 sling:hideResource

注意： 如果父组件是项目组件（而非核心组件），请使用直接 Java 类扩展（extends ParentModel），而不是委托模式。@Self @Via(type = ResourceSuperType.class) 模式仅适用于核心组件。加载 references/extending-core-components.md 以查看决策表。

步骤 2：收集需求

2.1 解析对话框规格

在创建之前，准确复述你理解的内容：

Dialog Specification Confirmed:
I will create exactly {N} fields:
| # | Field Label | Field Type | Property Name |
|---|-------------|------------|---------------|
| 1 | {label1}    | {type1}    | {name1}       |
No additional fields will be added.
Is this correct?

2.2 模型图像处理

• 同时提供模型图和规格： 以对话框规格为准。模型图仅用于 HTML/CSS。
• 仅提供模型图： 提出字段并请求确认。

2.3 Figma 设计输入

加载： references/figma-design-rules.md

当用户提供 Figma URL（figma.com/design/...、figma.com/make/... 或 figma.com/board/...）时：

1. 解析 URL，提取 fileKey 和 nodeId（参见 references/figma-design-rules.md 规则 1）

• 将 node-id 查询参数中的 - 转换为 :
• 对于分支 URL，使用 branchKey 作为 fileKey

1. **通过 plugin-figma-figma MCP 服务调用 **get_design_context（参见规则 2）：{ "server": "plugin-figma-figma", "toolName": "get_design_context", "arguments": { "nodeId": "<extracted-node-id>", "fileKey": "<extracted-file-key>", "clientLanguages": "html,css,javascript", "clientFrameworks": "htl" } }
2. 从响应中提取设计令牌——颜色、字体、尺寸、间距、布局（参见规则 3-4）
3. 使用 Figma 输出确定 HTL 结构、CSS 样式和 JS 行为——不要用它确定对话框字段

同时提供对话框规范和 Figma URL 时的优先级：

• 对话框规范 → 决定对话框字段（绝对优先，不得臆造）
• Figma 设计 → 仅决定 HTML 结构、CSS 样式和 JS 行为

仅提供 Figma URL 时（无对话框规范）：

• 分析设计并向用户提议对话框字段
• 继续之前先征求确认

处理 Figma 响应：

• 响应内容为 React+Tailwind；应将其视为参考，而非生产代码
• 将 JSX 转换为带有 BEM 类的语义化 HTL（参见规则 5）
• 将所有 CSS 值提取到组件 clientlib 中（参见规则 6）
• 仅在隐含需要交互时创建 JS（参见规则 7）
• 不要硬编码 Figma 临时图片 URL——它们会过期，在生产环境中失效（参见规则 8）

2.4 动态内容要求

用户指出	是否需要 Servlet？
外部 API 集成	是（GET）
动态数据加载	是（GET）
表单提交	是（POST）
搜索/筛选	是（GET）
静态对话框内容	否

第 3 步：创建组件文件

按以下顺序创建所有文件：

3.1 组件定义

路径： ui.apps/src/main/content/jcr_root/apps/[project]/components/{component-name}/.content.xml

加载：references/aem-conventions.md

3.2 组件对话框

路径： ui.apps/.../components/{component-name}/_cq_dialog/.content.xml

加载： references/dialog-patterns.md

对于扩展组件： 加载 references/extending-core-components.md——此处必须使用 Sling Resource Merger，因为对话框继承仅通过合并器起作用；否则将无法解析父级对话框节点。

3.2.1 图像字段处理

用户指定图像或照片字段时：

• 默认方式： 通过 data-sly-resource 嵌入 Core Image 组件——不要创建使用手动 <img> 渲染的 fileupload 对话框字段。
• Fileupload 仅适用于非图像文件（PDF、文档等）。仅当用户明确要求上传非图像文件时，才使用 cq/gui/components/authoring/dialog/fileupload。
• 加载 references/htl-patterns.md（图像处理部分），了解正确的嵌入模式。

3.3 HTL 模板

路径： ui.apps/.../components/{component-name}/{component-name}.html

加载： references/htl-patterns.md如果提供了 Figma URL，还要加载： references/figma-design-rules.md（规则 5、8）——将 JSX 结构转换为带有 BEM 类的语义化 HTL。将静态文本替换为 Sling Model 表达式。以 Figma 截图作为元素层级的视觉依据。

i18n 检查： 如果组件包含静态显示文本（标签、按钮文本、占位符字符串），请使用 HTL i18n 表达式：${'Label Text' @ i18n}。不要在 Sling Model 中处理静态文本翻译——将其保留在 HTL 中，以便自动翻译。

3.4 Sling 模型

路径： core/src/main/java/[package-path]/models/{ComponentName}Model.java

加载： references/model-patterns.md、references/java-standards.md

扩展时： 加载 references/extending-core-components.md

委托模式（用于核心组件扩展）：

@Model(adaptables = SlingHttpServletRequest.class,
       adapters = {CustomModel.class, ComponentExporter.class},
       resourceType = CustomModel.RESOURCE_TYPE)
@Exporter(name = ExporterConstants.SLING_MODEL_EXPORTER_NAME,
          extensions = ExporterConstants.SLING_MODEL_EXTENSION)
public class CustomModel implements ComponentExporter {
    @Self @Via(type = ResourceSuperType.class)
    private com.adobe.cq.wcm.core.components.models.List coreList;
    // Use FQN for core interfaces to avoid import collision
}

3.5 子项模型——用于多字段时

路径： core/src/main/java/[package-path]/models/{ItemName}.java

3.6 单元测试

路径： core/src/test/java/[package-path]/models/{ComponentName}ModelTest.java

加载： references/test-patterns.md

3.7 组件 Clientlib — 每个组件都要创建

路径： ui.apps/.../clientlibs/clientlib-{component-name}/

加载： references/clientlib-patterns.md如果提供了 Figma URL，还要加载： references/figma-design-rules.md（规则 6、7）——从 Figma 响应中提取准确的颜色、字体、尺寸、间距和圆角半径。使用 BEM 命名，将所有 CSS 放入 css/{component-name}.css。仅当设计包含交互时，才在 js/{component-name}.js 中创建 JS。对照 Figma 截图验证像素级还原度。

3.8 对话框 Clientlib — 用于条件逻辑时

路径： ui.apps/.../clientlibs/clientlib-{component-name}-dialog/

加载： references/clientlib-patterns.md（Dialog JavaScript Pattern 部分）

3.9 Sling Servlet — 用于动态内容时

路径： core/src/main/java/[package-path]/servlets/{ComponentName}Servlet.java

加载： references/sling-servlet-standards.md

3.10 Servlet 单元测试

路径： core/src/test/java/[package-path]/servlets/{ComponentName}ServletTest.java

3.11 依赖验证 — Servlet 必需

完成前，请验证 core/pom.xml 中的依赖：

• 不要硬编码版本——请检查父 pom.xml 中的版本属性，因为硬编码版本会逐渐不同步并导致构建冲突
• 最常见的 API 已包含在 aem-sdk-api 中（GSON、Jackson、Commons）
• AEM 运行时库请使用 provided 作用域

步骤 4：完成摘要

Component '{component-name}' created successfully!

## Files Created
- ui.apps/.../components/{component-name}/.content.xml
- ui.apps/.../components/{component-name}/_cq_dialog/.content.xml
- ui.apps/.../components/{component-name}/{component-name}.html
- core/.../models/{ComponentName}Model.java
- core/.../models/{ComponentName}ModelTest.java
- ui.apps/.../clientlibs/clientlib-{component-name}/
[+ servlet files if applicable]

## Dialog Fields (Exact Match)
{table matching specification}

Would you like me to add any additional fields or build the project?

快速参考：字段类型映射

用户说	Granite 资源类型
文本字段	granite/ui/components/coral/foundation/form/textfield
文本区域	granite/ui/components/coral/foundation/form/textarea
富文本、RTE	cq/gui/components/authoring/dialog/richtext
路径字段、路径	granite/ui/components/coral/foundation/form/pathfield
图像、照片	嵌入 Core Image 组件（参见 references/htl-patterns.md 的 Image Handling 部分）。请勿使用 fileupload 渲染图像。
文件上传	cq/gui/components/authoring/dialog/fileupload（用于非图像文件：PDF、文档）
多字段	granite/ui/components/coral/foundation/form/multifield
复选框	granite/ui/components/coral/foundation/form/checkbox
选择框、下拉菜单	granite/ui/components/coral/foundation/form/select
数字字段	granite/ui/components/coral/foundation/form/numberfield
日期选择器	granite/ui/components/coral/foundation/form/datepicker

完整映射请参阅：assets/field-type-mappings.md

参考文件

根据创建内容按需加载：

创建内容	加载参考文件
任何组件	.aem-skills-config.yaml（项目根目录，先加载 — 参见配置门禁检查），然后加载 references/aem-conventions.md
对话框 XML	references/dialog-patterns.md
HTL 模板	references/htl-patterns.md
Sling 模型	references/model-patterns.md、references/java-standards.md
单元测试	references/test-patterns.md
Clientlibs	references/clientlib-patterns.md
扩展 Core Component	references/extending-core-components.md
扩展 Core Component — 完整示例与检查清单	references/extending-core-components-example.md（需要扩展 Core Component 的完整示例、单元测试模式或实现检查清单时加载）
Sling Servlet	references/sling-servlet-standards.md
Core Component 模式	references/core-components.md
防止幻觉规则	references/no-hallucination-rules.md
Figma 设计集成	references/figma-design-rules.md
故障排查	references/troubleshooting.md
示例	references/examples.md

如果在创建组件期间或之后遇到问题，请参阅 references/troubleshooting.md，了解常见问题及解决方案。