ue-component-model

Universal Editor 组件模型配置

此技能可帮助你创建或编辑三个 JSON 配置文件，以控制 AEM Edge Delivery Services (EDS) 块在 Universal Editor (UE) 中的显示方式和行为：

1. component-definition.json — 在 UE 组件面板中注册块
2. component-models.json — 定义每个块的属性面板字段
3. component-filters.json — 控制块的放置位置

适用场景

• 创建需要 UE 创作支持的新块
• 为现有块的属性面板添加或修改字段
• 注册块，使其显示在作者的组件面板中
• 设置带有子项的容器块
• 添加块变体／样式选项

工作流

第 1 步：了解块

生成任何配置之前，请阅读并分析：

1. 块的 JS 文件（blocks/<name>/<name>.js）——了解 decorate(block) 函数需要哪些内容：

   • 它会从块 div 中读取什么？（图像、链接、文本、类）
   • 它需要扁平结构还是项目行？
   • 它是否会使用 block.querySelector('a')（链接／URL）、block.querySelector('picture')（图像）等？
   • 它是否会检查 CSS 类／变体？

2. 块的 CSS 文件（blocks/<name>/<name>.css）——查找特定于变体的样式。

3. 现有配置——检查是否已有相关条目：

   • 在 component-definition.json 中搜索块 ID
   • 在 component-models.json 中搜索模型 ID
   • 在 component-filters.json 的 section 组件列表中搜索该块
   • 检查是否存在 blocks/<name>/_<name>.json 分发配置文件

第 2 步：确定块类型

根据 JS 分析结果：

• 简单块：一个带有自身字段的组件。大多数块都属于此类型。

  • 示例：Hero、Embed——单个模型，无子项

• 容器块：包含可重复的子项（卡片、幻灯片、选项卡）。

  • 线索：JS 会遍历 block.children，或根据行创建项目
  • 需要：容器定义 + 项目定义 + 过滤器

• 键值块：配置型块（两列键值对）。

  • 线索：每个属性都是独立的，不是内容网格
  • 需要：在模板中设置 "key-value": true

步骤 3：设计模型字段

将区块的内容需求映射到组件模型字段。请阅读 references/field-types.md，查看完整的字段类型参考。

常见字段映射：

区块需要……	使用组件类型	说明
图像	reference（名称：image）	搭配名为 imageAlt 的 text 字段
URL/链接	aem-content（名称：link 或 url）	用于页面链接和外部 URL
富文本内容	richtext	用于包含标题、列表和链接的格式化文本
纯文本（单行）	text	用于标题、标签和简短字符串
纯文本（多行）	textarea	用于说明、备注和不带格式的长文本
标题级别选项	带有 h1-h6 选项的 select	将其命名为 titleType，以便与标题自动折叠
样式变体	multiselect（名称：classes）	值会成为区块 div 上的 CSS 类
多个切换选项	checkbox-group	用于多个相互独立的布尔选项
布尔切换选项	boolean	用于显示/隐藏选项
数值	number	用于计数和限制
内容片段	aem-content-fragment	用于由 CF 驱动的区块
体验片段	aem-experience-fragment	用于可复用的内容+布局片段
内容标签	aem-tag	用于通过 AEM 标签选择器进行分类

字段命名规则（语义折叠）：

• image + imageAlt → 折叠为 <picture><img alt="...">
• link + linkText + linkTitle + linkType → 折叠为 <a href="..." title="...">text</a>，并可选添加类
• title + titleType → 折叠为 <h2>title</h2>（级别由 titleType 决定）
• 以 group_（下划线分隔）为前缀的字段会分组到同一个单元格中

步骤 4：生成配置

为这三个文件生成条目。具体方式取决于项目采用集中式还是分布式配置。

检查是否采用分布式配置模式：如果区块目录包含 _<blockname>.json 文件（例如 blocks/hero/_hero.json），则创建分布式配置文件，而不是编辑集中式文件。

对于集中式配置（编辑三个根 JSON 文件）：

component-definition.json — 添加到 "Blocks" 组的 components 数组中：

{
  "title": "<Block Display Name>",
  "id": "<block-id>",
  "plugins": {
    "xwalk": {
      "page": {
        "resourceType": "core/franklin/components/block/v1/block",
        "template": {
          "name": "<Block Name>",
          "model": "<model-id>"
        }
      }
    }
  }
}

对于容器区块，同时添加容器和项目定义。容器使用 "filter" 而不是 "model"，项目则将 "core/franklin/components/block/v1/block/item" 用作 resourceType。

对于键值区块，在模板中添加 "key-value": true。

模板可以包含任意模型字段的默认值（例如，"titleType": "h3"、"classes": ["light"]）。

component-models.json — 添加一个新的模型条目：

{
  "id": "<model-id>",
  "fields": [
    {
      "component": "<field-type>",
      "name": "<property-name>",
      "label": "<Display Label>",
      "valueType": "string"
    }
  ]
}

component-filters.json — 将区块 ID 添加到 section 筛选器的 components 数组中。对于容器区块，还要添加一个定义允许子项的新筛选器条目。

对于分布式配置（创建 blocks/<name>/_<name>.json）：

创建一个包含全部三项配置的文件：

{
  "definitions": [ ... ],
  "models": [ ... ],
  "filters": [ ... ]
}

仍需将区块添加到集中式 component-filters.json 中的 section 筛选器。

步骤 5：验证

生成配置后，请验证以下内容：

1. ID 一致性：定义中的 id 与 component-filters.json 中使用的 ID 相符。template.model 值与 component-models.json 中的 id 相符。
2. 筛选器注册：区块的 ID 出现在 section 筛选器的 components 数组中（否则作者无法将其添加到页面）。
3. 字段名称与区块 JS 匹配：模型字段中的 name 属性应生成可供区块 decorate() 函数使用的 HTML。
4. 语义折叠：配对字段使用正确的后缀（例如，image/imageAlt，而不是 image/altText，除非这是有意为之）。
5. 有效 JSON：编辑后，三个文件仍为有效 JSON。
6. 无重复 ID：模型或筛选器 ID 不与现有条目冲突。

参考文件

如需详细信息，请按需阅读以下参考文件：

• references/architecture.md — 三个文件如何关联、完整的 AEM→Markdown→HTML 流程、资源类型、字段命名约定、语义折叠规则，以及 RTE 过滤器配置
• 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（内容片段）、Section 配置、Metadata（多行文本）、Feature Toggles（复选框组）和 RTE 过滤器配置

常见问题

• 忘记添加到 section 过滤器：如果未将区块添加到 section 过滤器的组件列表中，作者的添加菜单中就不会显示该区块。
• resourceType 错误：几乎所有自定义区块都使用 core/franklin/components/block/v1/block。不要自定义资源类型。
• 模型 ID 与过滤器 ID 不匹配：template.model 必须与模型的 id 完全一致，template.filter 必须与过滤器的 id 完全一致。
• 文本字段类型选择错误：单行字符串使用 text，多行纯文本使用 textarea，格式化内容使用 richtext。对于 URL 和页面链接，使用 aem-content，以便作者使用内容选择器。
• valueType 错误：大多数组件会强制要求特定的 valueType（例如，boolean 必须使用 "boolean"，number 必须使用 "number"，checkbox-group 必须使用 "string[]"）。请务必包含 valueType，并查阅字段类型参考以确认强制要求的值。
• 容器未配置过滤器：容器区块的模板中需要配置 filter（而非 model），并且 component-filters.json 中需要有对应的过滤器条目。