为 AEM Edge Delivery Services…

当需要让 EDS/Franklin 区块在 Universal Editor 中可被作者拖拽、编辑属性、控制嵌套位置时，生成或修改 component-definition.json、component-models.json、component-filters.json。

适用场景

解决思路

1. 先阅读区块的 JS 文件（blocks/<name>/<name>.js），分析 decorate(block) 期望的内容：从 block div 读取什么（图片、链接、文本、class）、是扁平结构还是多行 items、是否使用 block.querySelector('a')（链接/URL）、block.querySelector('picture')（图片）、是否检查 CSS class/variant。
2. 阅读区块的 CSS 文件（blocks/<name>/<name>.css），查找 variant 相关样式。
3. 检查现有配置是否已有条目：在 component-definition.json 搜索该 block ID，在 component-models.json 搜索 model ID，在 component-filters.json 的 section components 列表中搜索该 block，并检查是否存在 blocks/<name>/_<name>.json 分布式配置文件。
4. 根据 JS 分析确定区块类型：简单区块（单一组件带自己的字段，如 Hero、Embed，单 model 无子项）；容器区块（有可重复子项，如 cards、slides、tabs，线索是 JS 遍历 block.children 或从行创建 items，需要容器定义 + item 定义 + filter）；键值区块（配置型 2 列键值对，线索是每个属性独立而非内容网格，需要在 template 中加 "key-value": true）。
5. 设计 model 字段，把区块内容期望映射到组件模型字段：图片用 reference（name: image）并搭配名为 imageAlt 的 text 字段；URL/链接用 aem-content（name: link 或 url）；富文本用 richtext；单行纯文本用 text；多行纯文本用 textarea；标题级别选择用 select 并提供 h1-h6 选项，命名为 titleType 以与 title 自动折叠；样式变体用 multiselect（name: classes），值会成为 block div 上的 CSS class；多个开关用 checkbox-group；布尔开关用 boolean；数值用 number；Content Fragment 用 aem-content-fragment；Experience Fragment 用 aem-experience-fragment；内容标签用 aem-tag。
6. 遵循字段命名规则（语义折叠）：image + imageAlt 折叠为 <picture><img alt="...">；link + linkText + linkTitle + linkType 折叠为 <a href="..." title="...">text</a> 并可带 class；title + titleType 折叠为 <h2>title</h2>（级别来自 titleType）；以 group_ 前缀（下划线分隔）的字段会被分组到同一个单元格。
7. 判断项目使用集中式还是分布式配置：若区块目录中存在 _<blockname>.json 文件（如 blocks/hero/_hero.json），则创建分布式配置文件而非编辑中央文件。
8. 集中式配置：在 component-definition.json 的 "Blocks" 组的 components 数组中添加条目，包含 title、id、plugins.xwalk.page.resourceType 为 core/franklin/components/block/v1/block、template 中设置 name 和 model；容器区块需同时添加容器和 item 定义，容器用 "filter" 而非 "model"，item 的 resourceType 用 core/franklin/components/block/v1/block/item；键值区块在 template 中加 "key-value": true；template 可为任意 model 字段设置默认值（如 "titleType": "h3"、"classes": ["light"]）。
9. 集中式配置：在 component-models.json 中添加新的 model 条目，包含 id 和 fields 数组，每个字段含 component、name、label、valueType。
10. 集中式配置：在 component-filters.json 的 section filter 的 components 数组中添加该 block ID；容器区块还需新增一个 filter 条目定义允许的子项。
11. 分布式配置：创建单个 blocks/<name>/_<name>.json 文件，包含 definitions、models、filters 三部分；仍需在中央 component-filters.json 的 section filter 中添加该 block。
12. 校验：definition 中的 id 与 component-filters.json 中使用的 id 一致，template.model 与 component-models.json 中的 id 一致。
13. 校验：block 的 ID 出现在 section filter 的 components 数组中，否则作者无法将其添加到页面。
14. 校验：model 字段的 name 属性应产生区块 decorate() 函数能消费的 HTML。
15. 校验：成对字段使用正确的后缀（如 image/imageAlt，而非 image/altText，除非有意为之）。
16. 校验：编辑后三个文件仍是合法 JSON。
17. 校验：没有 model 或 filter ID 与现有条目冲突。
18. 按需阅读参考文件：references/architecture.md（三个文件如何连接、AEM→Markdown→HTML 完整流水线、resource types、字段命名约定、语义折叠规则、RTE filter 配置）；references/field-types.md（全部 17 种字段组件类型 text、textarea、richtext、reference、aem-content、aem-content-fragment、aem-experience-fragment、aem-tag、select、multiselect、checkbox-group、radio-group、boolean、number、date-time、container、tab 的完整参考，valueType 约束、必需属性、字段属性、校验类型、条件字段、选项格式）；references/examples.md（Hero 简单、Embed 带 URL 简单、Cards 容器、Teaser 变体、Product Details 键值、Article content fragment、Section 配置、Metadata textarea、Feature Toggles checkbox-group、RTE filter 配置等真实示例）。

适用边界 · 注意事项

• 项目不使用 AEM Edge Delivery Services 或 Universal Editor 时。
• 区块不需要作者在 UE 中编辑或拖拽（纯代码/静态区块）时。
• 没有权限或不需要修改这三个 JSON 配置文件时。