ue-component-model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Universal Editor Component Model Configuration

Universal Editor组件模型配置

This skill helps you create or edit the three JSON configuration files that control how AEM Edge Delivery Services (EDS) blocks appear and behave in the Universal Editor (UE):

component-definition.json — Registers blocks in the UE component palette
component-models.json — Defines property panel fields for each block
component-filters.json — Controls where blocks can be placed

此技能可帮助您创建或编辑三个JSON配置文件，这些文件用于控制AEM Edge Delivery Services（EDS）块在Universal Editor（UE）中的显示和行为：

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

When to Use

适用场景

Creating a new block that needs UE authoring support
Adding/modifying fields on an existing block's property panel
Registering a block so it appears in the author's component palette
Setting up container blocks with child items
Adding block variants/style options

创建需要UE编辑支持的新块
在现有块的属性面板中添加/修改字段
注册块使其显示在编辑器的组件面板中
设置包含子项的容器块
添加块变体/样式选项

Workflow

工作流程

Step 1: Understand the Block

步骤1：了解块

Before generating any configuration, read and analyze:

The block's JS file (
```
blocks/<name>/<name>.js
```
) — understand what content the
```
decorate(block)
```
function expects:
- What does it read from the block div? (images, links, text, classes)
- Does it expect a flat structure or rows of items?
- Does it use
```
block.querySelector('a')
```
  (links/URLs),
```
block.querySelector('picture')
```
  (images), etc.?
- Does it check for CSS classes/variants?
The block's CSS file (
```
blocks/<name>/<name>.css
```
) — look for variant-specific styles.
Existing config — check if entries already exist:
- Search
```
component-definition.json
```
  for the block ID
- Search
```
component-models.json
```
  for the model ID
- Search
```
component-filters.json
```
  for the block in the
```
section
```
  components list
- Check for a
```
blocks/<name>/_<name>.json
```
  distributed config file

在生成任何配置之前，请阅读并分析以下内容：

块的JS文件（
```
blocks/<name>/<name>.js
```
）——了解
```
decorate(block)
```
函数期望的内容：
- 它从块div中读取什么内容？（图片、链接、文本、类）
- 它期望扁平结构还是多行项目？
- 是否使用
```
block.querySelector('a')
```
  （链接/URL）、
```
block.querySelector('picture')
```
  （图片）等？
- 是否检查CSS类/变体？
块的CSS文件（
```
blocks/<name>/<name>.css
```
）——查找变体特定样式。
现有配置——检查是否已存在相关条目：
- 在
```
component-definition.json
```
  中搜索块ID
- 在
```
component-models.json
```
  中搜索模型ID
- 在
```
component-filters.json
```
  的
```
section
```
  组件列表中搜索该块
- 检查块目录中是否存在
```
blocks/<name>/_<name>.json
```
  分布式配置文件

Step 2: Determine the Block Type

步骤2：确定块类型

Based on the JS analysis:

Simple block: One component with its own fields. Most blocks are this type.
- Example: Hero, Embed — single model, no children
Container block: Has repeatable child items (cards, slides, tabs).
- Clue: JS iterates over
```
block.children
```
  or creates items from rows
- Needs: container definition + item definition + filter
Key-value block: Configuration-style block (2-column key-value pairs).
- Clue: Each property is independent, not a grid of content
- Needs:
```
"key-value": true
```
  in template

基于JS文件分析：

简单块：单个组件带有自身字段。大多数块属于此类型。
- 示例：Hero、Embed —— 单一模型，无子项
容器块：包含可重复的子项（卡片、幻灯片、标签页）。
- 线索：JS遍历
```
block.children
```
  或从行中创建项目
- 需求：容器定义 + 子项定义 + 过滤器
键值块：配置样式的块（两列键值对）。
- 线索：每个属性相互独立，并非内容网格
- 需求：在模板中添加
```
"key-value": true
```

Step 3: Design the Model Fields

步骤3：设计模型字段

Map the block's content expectations to component model fields. Read

references/field-types.md

for the full field type reference.

Common field mappings:

Block expects...	Use component type	Notes
An image	`reference` (name: `image` )	Pair with `text` field named `imageAlt`
A URL/link	`aem-content` (name: `link` or `url` )	For page links and external URLs
Rich text content	`richtext`	For formatted text with headings, lists, links
Plain text (single line)	`text`	For titles, labels, short strings
Plain text (multi-line)	`textarea`	For descriptions, notes, long text without formatting
Heading level choice	`select` with h1-h6 options	Name it `titleType` to auto-collapse with title
Style variants	`multiselect` (name: `classes` )	Values become CSS classes on block div
Multiple toggles	`checkbox-group`	For multiple independent boolean options
Boolean toggle	`boolean`	For show/hide options
Number value	`number`	For counts, limits
Content Fragment	`aem-content-fragment`	For CF-driven blocks
Experience Fragment	`aem-experience-fragment`	For reusable content+layout fragments
Content tags	`aem-tag`	For categorization via AEM tag picker

Field naming rules (semantic collapsing):

```
image
```
+
```
imageAlt
```
→ collapsed into
```
<picture><img alt="...">
```

link

linkText

linkTitle

linkType

→ collapsed into

<a href="..." title="...">text</a>

with optional class

```
title
```
+
```
titleType
```
→ collapsed into
```
<h2>title</h2>
```
(level from titleType)
Fields prefixed with
```
group_
```
(underscore separator) are grouped into a single cell

将块的内容需求映射到组件模型字段。如需完整的字段类型参考，请阅读

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_
```
（下划线分隔）的字段会被分组到单个单元格中

Step 4: Generate the Configuration

步骤4：生成配置

Generate entries for all three files. The approach depends on whether the project uses centralized or distributed config.

Check for distributed config pattern: If the block directory contains

_<blockname>.json

files (e.g.,

blocks/hero/_hero.json

), create a distributed config file instead of editing the central files.

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

检查分布式配置模式：如果块目录包含

_<blockname>.json

文件（例如

blocks/hero/_hero.json

），则创建分布式配置文件，而非编辑中央文件。

For Centralized Config (editing the three root JSON files):

集中式配置（编辑根目录下的三个JSON文件）：

component-definition.json — Add to the

"Blocks"

group's

components

array:

json

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

For container blocks, add both the container AND item definitions. The container gets

"filter"

instead of

"model"

, and the item uses

"core/franklin/components/block/v1/block/item"

as resourceType.

For key-value blocks, add

"key-value": true

to the template.

Template can include default values for any model field (e.g.,

"titleType": "h3"

"classes": ["light"]

component-models.json — Add a new model entry:

json

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

component-filters.json — Add the block ID to the

section

filter's

components

array. For container blocks, also add a new filter entry defining allowed children.

component-definition.json — 添加到

"Blocks"

组的

components

数组中：

json

{
  "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 — 添加新的模型条目：

json

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

component-filters.json — 将块ID添加到

section

过滤器的

components

数组中。对于容器块，还需添加定义允许子项的新过滤器条目。

For Distributed Config (creating

blocks/<name>/_<name>.json

分布式配置（创建

blocks/<name>/_<name>.json

）：

Create a single file with all three configs:

json

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

Still add the block to the

section

filter in the central

component-filters.json

创建一个包含所有三种配置的单个文件：

json

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

仍需将块添加到中央

component-filters.json

的

section

过滤器中。

Step 5: Validate

步骤5：验证

After generating the config, verify:

ID consistency: The
```
id
```
in the definition matches what's used in
```
component-filters.json
```
. The
```
template.model
```
value matches the
```
id
```
in
```
component-models.json
```
.
Filter registration: The block's ID appears in the
```
section
```
filter's
```
components
```
array (otherwise authors can't add it to pages).
Field names match block JS: The
```
name
```
properties in the model fields should produce HTML that the block's
```
decorate()
```
function can consume.
Semantic collapsing: Paired fields use correct suffixes (e.g.,
```
image
```
/
```
imageAlt
```
, not
```
image
```
/
```
altText
```
unless intentional).
Valid JSON: All three files remain valid JSON after edits.
No duplicate IDs: No model or filter ID conflicts with existing entries.

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

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

Reference Files

参考文件

For detailed information, read these reference files as needed:

references/architecture.md
— How the three files connect, the full AEM→Markdown→HTML pipeline, resource types, field naming conventions, semantic collapsing rules, and RTE filter configuration
references/field-types.md
— Complete reference for all 17 field component types (
```
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 constraints, required properties, field properties, validation types, conditional fields, and option formats
references/examples.md
— Real examples showing Hero (simple), Embed (simple with URL), Cards (container), Teaser (variants), Product Details (key-value), Article (content fragment), Section configuration, Metadata (textarea), Feature Toggles (checkbox-group), and RTE filter configuration

如需详细信息，可根据需要阅读以下参考文件：

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（内容片段）、区域配置、Metadata（多行文本）、Feature Toggles（复选框组）以及RTE过滤器配置

Common Pitfalls

常见陷阱

Forgetting to add to section filter: The block won't appear in the author's add menu unless it's in the
```
section
```
filter's components list.
Wrong resourceType: Almost all custom blocks use
```
core/franklin/components/block/v1/block
```
. Don't invent custom resource types.
Mismatched model/filter IDs: The
```
template.model
```
must exactly match the model
```
id
```
, and
```
template.filter
```
must exactly match the filter
```
id
```
.
Choosing the wrong text field type: Use
```
text
```
for single-line strings,
```
textarea
```
for multi-line plain text, and
```
richtext
```
for formatted content. For URLs and page links, use
```
aem-content
```
so authors get the content picker.
Wrong valueType: Most components enforce a specific
```
valueType
```
(e.g.,
```
boolean
```
must use
```
"boolean"
```
,
```
number
```
must use
```
"number"
```
,
```
checkbox-group
```
must use
```
"string[]"
```
). Always include
```
valueType
```
and check the field-types reference for the enforced value.
Container without filter: Container blocks need a
```
filter
```
(not a
```
model
```
) in their template, and a corresponding filter entry in component-filters.json.

忘记添加到区域过滤器：除非块在
```
section
```
过滤器的组件列表中，否则不会出现在编辑器的添加菜单中。
错误的resourceType：几乎所有自定义块都使用
```
core/franklin/components/block/v1/block
```
。不要自定义资源类型。
模型/过滤器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中添加对应的过滤器条目。

ue-component-model

Original

Translation

Universal Editor Component Model Configuration

Universal Editor组件模型配置

When to Use

适用场景

Workflow

工作流程

Step 1: Understand the Block

步骤1：了解块

Step 2: Determine the Block Type

步骤2：确定块类型

Step 3: Design the Model Fields

步骤3：设计模型字段

Step 4: Generate the Configuration

步骤4：生成配置

For Centralized Config (editing the three root JSON files):

集中式配置（编辑根目录下的三个JSON文件）：

For Distributed Config (creating
`blocks/<name>/_<name>.json`
):

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

Step 5: Validate

步骤5：验证

Reference Files

参考文件

Common Pitfalls

常见陷阱

ue-component-model

Original

Translation

Universal Editor Component Model Configuration

Universal Editor组件模型配置

When to Use

适用场景

Workflow

工作流程

Step 1: Understand the Block

步骤1：了解块

Step 2: Determine the Block Type

步骤2：确定块类型

Step 3: Design the Model Fields

步骤3：设计模型字段

Step 4: Generate the Configuration

步骤4：生成配置

For Centralized Config (editing the three root JSON files):

集中式配置（编辑根目录下的三个JSON文件）：

For Distributed Config (creating blocks/<name>/_<name>.json):

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

Step 5: Validate

步骤5：验证

Reference Files

参考文件

Common Pitfalls

常见陷阱

For Distributed Config (creating
`blocks/<name>/_<name>.json`
):

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