在 Magento 2 中创建自定义 Hyvä CMS…

当需要为 Magento 2 的 Hyvä CMS 新建自定义 CMS 组件（含字段、变体、子组件与模板）时使用。

适用场景

解决思路

1. 确定组件创建位置：若用户未指定，先询问是在新模块还是已有模块中创建。
2. 新模块方案：向用户询问 Vendor name（必填、无默认值、不要自行建议），Module name 建议默认 CmsComponents 让用户回车接受；然后用 hyva-create-module 技能创建模块，dependencies 设为 ["Hyva_CmsBase"]，composer_require 设为 {"hyva-themes/commerce-module-cms": "^1.0"}。
3. 已有模块方案：获取模块路径（可在 app/code/、vendor/ 或自定义位置）；确认 etc/module.xml 中依赖 Hyva_CmsBase，没有就加上；确认 composer.json 中依赖 hyva-themes/commerce-module-cms，没有就加上。
4. 收集组件信息：组件名（snake_case，如 feature_card）、Label（编辑器显示名）、Category（Layout、Elements、Media、Content 或 Other）。
5. 选择图标：先用 hyva-cms-components-dump 技能导出所有现有 CMS 组件，提取已使用的 icon 值；再列出 vendor/hyva-themes/magento2-theme-module/src/view/base/web/svg/lucide/ 下的 SVG 文件得到全部可用图标；从「未被占用」的图标中按语义选最贴# 的一个（如购物车用 shopping-cart.svg、图片用 image.svg、网格布局用 layout-grid.svg），格式为 Hyva_Theme::svg/lucide/[icon-name].svg；若找不到合适且未占用的图标，或 lucide 目录不存在，则不设置 icon 属性。
6. 选择字段：提供字段预设（Basic Card、Image Card、CTA Block、Text Block、Feature Item、Testimonial、Accordion Item，见 references/field-types.md 的 Field Presets）或允许自定义字段；字段类型优先以项目实时列表为准，通过 hyva-exec-shell-cmd 包装执行 bin/magento hyva:cms:list-fields，命令不可用时才回退到 references/field-types.md。
7. 自定义字段逐个询问：字段名（snake_case）、字段类型、Label、默认值（可选）、是否必填（yes/no，注意要写入 attributes.required 而不是直接字段属性）、以及任何额外 attributes（放入 attributes 对象）。
8. 询问是否需要模板变体：需要则收集变体名与标签（如 default、compact、wide，配置见 references/variant-support.md）；不需要则使用单一模板。
9. 生成文件：新模块由 hyva-create-module 生成基础结构后，补充 etc/hyva_cms/components.json 与 view/frontend/templates/elements/[component-name].phtml（多变体时为 [component-name]/ 目录）；已有模块则创建或合并 etc/hyva_cms/components.json，并创建 view/frontend/templates/elements/[component-name].phtml。
10. components.json 中组件结构包含 label、category、template（如 [Vendor]_[Module]::elements/[component-name].phtml）、content（生成的字段）、design.includes（Hyva_CmsBase::etc/hyva_cms/default_design.json 与 default_design_typography.json）、advanced.includes（Hyva_CmsBase::etc/hyva_cms/default_advanced.json）。
11. 只使用合法的组件级属性：label（必填）、category、template、icon、children、require_parent、content、design、advanced、disabled、custom_properties；不要使用 hidden 等不存在的属性（子组件专用请用 require_parent: true，禁用请用 disabled: true）。
12. children 必须声明在组件根级，绝不能作为 content/design/advanced 里的字段类型；模板中通过 $block->getData('children') 访问，而不是自定义字段名。
13. 字段校验属性必须放在 attributes 对象内，例如 "attributes": {"required": true}，不要写成直接字段属性；required、minlength/maxlength、min/max、pattern、placeholder、comment 及自定义校验消息 data 属性都放 attributes。
14. 子组件专用组件（如列表项）设置 require_parent: true 与 template: false；父组件通过 children.config.accepts 声明可接受的子组件，template: false 时父组件直接渲染子数据，不使用 $block->createChildHtml()。
15. PHTML 模板头部固定为：<?php declare(strict_types=1); use Hyva\CmsLiveviewEditor\Block\Element; use Hyva\Theme\ViewModel\ViewModelRegistry; use Magento\Framework\Escaper; /** @var Element $block */ /** @var Escaper $escaper */ /** @var ViewModelRegistry $viewModels */。
16. 模板中在根元素调用 $block->getEditorAttrs()，在每个可编辑元素上调用 $block->getEditorAttrs('field_name')，并用 $escaper->escapeHtml() / $escaper->escapeHtmlAttr() 正确转义。
17. 按字段类型写模板：文本字段用 $block->getData('title') 并 escapeHtml；richtext/HTML 字段不转义直接输出；图片字段用 hyva-render-media-image 技能与 \Hyva\Theme\ViewModel\Media 视图模型，$block->getData('image') 可直接传给 getResponsivePictureHtml()；链接字段用 $block->getLinkData($link) 取 url/target/title 并 escapeUrl/escapeHtmlAttr；布尔字段用 (bool) $block->getData('show_title')；select 字段用 match 映射样式类。
18. 子组件带自身模板时用 $block->createChildHtml($child, 'child-' . $index) 渲染；子组件为 template: false 时，子数据是扁平的（用 $elementData['field_name']，不是 $elementData['content']['field_name']），每个子项有 uid，用 $block->getEditorAttrs('field_name', $childUid) 启用子字段实时编辑，根元素用 $block->getEditorAttrs('', $childUid)，图片检查 !empty($image['src']) 并用 $block->getResponsiveImageData($image) 处理。
19. 生成文件后，通过 hyva-exec-shell-cmd 技能检测到的命令包装执行 bin/magento setup:upgrade。
20. 生成组件前先读 references/critical-patterns.md 避免常见错误；需要完整示例时读 references/example-component.md；校验组件结构或遇到 schema 报错时，优先读取项目内 vendor/hyva-themes/commerce-module-cms/src/liveview-editor/etc/hyva_cms/jsonschema/ 下的 component-declaration.json 与 component-field-declaration.json，未安装 Hyvä Commerce 时才回退到 references/component-schema.md。
21. 遵守重要准则：根元素与每个可编辑字段元素都要用 getEditorAttrs()；模板中禁止使用 <script> 标签，改用 Alpine.js 的 alpine:init 事件；所有用户内容都要转义；为商户体验提供有意义的默认值；通过 includes 引入 design/advanced 段；组件名必须是 snake_case（仅小写字母、数字、下划线）；默认值键名必须是 default_value 而不是 default。

适用边界 · 注意事项

• 不适用于非 Hyvä CMS 的普通 Magento CMS 组件或 Page Builder 组件。
• 不适用于未安装 Hyvä Commerce / Hyva_CmsBase 依赖的项目（此时只能参考回退 schema，无法真正生成可用组件）。
• 不适用于仅需修改现有组件样式或模板、而不新增组件的场景。