文档AEM用户指南

[AEM Sites]{class="badge positive" title="适用于AEM Sites)。"}

定义内容片段模型 defining-content-fragment-models

最近更新： 2026年11月2日
  • 适用对象：
  • Experience Manager as a Cloud Service

创建对象：

  • 用户
  • 开发人员

Adobe Experience Manager (AEM) as a Cloud Service 中的内容片段模型定义内容片段的内容结构。 随后可使用这些片段创作页面或作为 Headless 内容的基础。

本页介绍如何使用专用编辑器定义内容片段模型。 查看管理您的内容片段模型，了解创建片段后可用的进一步任务和选项，包括从内容片段控制台中可用的操作、在文件夹中允许模型和发布模型。

NOTE
使用内容片段模型和内容片段时，请了解最佳实践。
CAUTION
如果要查询多个引用的片段，则建议不要让各种片段模型具有名称相同，但类型不同的字段名称。
有关详细信息，请参阅用于内容片段的AEM GraphQL API — 限制
NOTE
如果使用此新编辑器创建模型，则应当始终将此编辑器用于该模型。
如果您随后使用原始模型编辑器打开模型，您将看到以下消息：
  • “该模型已配置自定义UI架构。 此UI中显示的字段顺序可能与UI架构不匹配。 要查看与UI架构对齐的字段，您需要切换到新的内容片段编辑器。”

定义内容片段模型 defining-your-content-fragment-model

内容片段模型使用一批​ 数据类型 ​有效地定义所得内容片段的结构。 可使用模型编辑器添加数据类型的实例，然后配置它们以创建必填字段：

CAUTION
编辑现有内容片段已使用的模型可能会影响那些从属的片段。

  1. 在内容片段控制台中，选择内容片段模型的面板，然后导航到包含您的内容片段模型的文件夹。

    note
    NOTE
    在创建模型后，您也可以直接打开模型。

  2. 打开​ 编辑 ​所需的模型；使用其中一个快速操作链接，或者选择模型，然后从工具栏中选择操作。

    属性

    打开模型编辑器后，会显示：

    • 上：

      • 主页​图标
      • 用于在原始编辑器和新编辑器之间进行切换的选项
      • 取消
      • 保存

    • 左侧：可用于创建字段的​数据类型

    • 中间：字段已与​ 添加 ​选项一起定义

    • 右侧：使用最右侧的图标，您可以在以下各项之间进行选择：

      • 属性：定义和查看选定字段的属性
      • 模型详细信息：显示​ 已启用 ​状态、模型标题、标记、描述​和​预览URL

  3. 添加字段

    • 可以任选其一：

      • 将数据类型从左侧面板拖到中间面板中字段的所需位置。
      • 按数据类型选择​ + ​图标以将其添加到字段列表的底部。
      • 在中间面板中选择​添加，然后从结果下拉列表中选择所需的数据类型，以在列表底部添加字段。
      note
      NOTE
      制表符占位符​字段必须始终显示在现有字段上方。

    • 您可以使用字段框左侧的圆点形式重新定位字段：

      移动字段

    • 将字段添加到模型（并选择该字段）后，右侧面板会显示可为该特定数据类型定义的​属性。 您可以在此定义特定的
      字段。

      • 许多属性的含义一目了然，有关更多详细信息，请参阅属性（数据类型）。

      • 键入​ 字段标签 ​将自动补全​属性名称 - 如果为空，则以后可手动更新它。

        note caution
        CAUTION
        在手动更新数据类型的​ 属性名称 ​属性时，名称必须​ 仅 ​包含 A-Z、a-z、0-9 和作为特殊字符的下划线“_”。
        如果在 AEM 早期版本中创建的模型包含非法字符，请移除或更新这些字符。

      例如：

      字段属性

      note
      NOTE
      当字段定义为​ 必填 ​时，中间窗格中指示的​ 标签 ​将标有星号(*)。

  4. 移除字段

    选择中间面板中相应字段的垃圾桶图标。

    移除

  5. 添加所有必填字段，并根据需要定义相关属性。

  6. 选择​ “保存” ​来保留定义。

数据类型 data-types

有一批数据类型可用于定义您的模型：

  • 单行文本

    • 为单行文本添加字段；可以定义最大长度
    • 字段可以配置为允许片段作者创建新字段实例

  • 多行文本

    • 一个文本区域，可设为富文本、纯文本或 Markdown
    • 字段可以配置为允许片段作者创建新字段实例
    note
    NOTE
    在模型中由​ 默认类型 ​属性定义该文本区域是富文本、纯文本还是 Markdown。
    无法从内容片段编辑器更改此格式，而只能从模型更改。

  • 数字

    • 添加数字字段
    • 字段可以配置为允许片段作者创建新字段实例

  • 布尔型

    • 添加布尔复选框

  • 日期和时间

    • 添加日期和/或时间字段

  • 枚举

    • 添加一组复选框、单选按钮或下拉字段
      • 您可以指定对片段作者可用的选项

  • 标记

    • 允许片段作者访问和选择标记区域

  • 片段引用

    • 引用其他内容片段；可用于创建嵌套内容

    • 数据类型可配置为允许片段作者执行以下操作：

      • 直接编辑引用的片段。
      • 根据相应的模型创建新内容片段
      • 创建字段的新实例

    • 引用指定了引用资源的路径；例如/content/dam/path/to/resource

  • 内容引用

    • 引用任何类型的其他内容；可用于创建嵌套内容
    • 如果图像被引用，您可以选择显示缩略图
    • 字段可以配置为允许片段作者创建新字段实例
    • 引用指定了引用资源的路径；例如/content/dam/path/to/resource

  • 复合

    • 组合​数据类型可用于创建嵌套内容

    • 复合​数据类型允许内容片段存储分层结构化的数据

      • 这是通过允许字段包含嵌套子字段来实现的
      • 子字段的结构化
      • 子字段根据内容片段模型构建
      • 子字段仅限于您在定义子字段时指定的内容片段模型

    • 此功能提供了一种在单个片段中建模复杂数据结构的方法，类似于JSON中的嵌套对象或NoSQL数据库中的嵌入文档

    note warning
    WARNING
    可以使用“复合”数据类型：
    • 在触屏UI（原始）内容片段模型编辑器中
    • 在新的内容片段编辑器中
    新的内容片段模型编辑器和触屏UI（原始）内容片段编辑器将阻止对复合数据类型和任何依赖字段的访问。
    对于新内容片段模型编辑器中的复合字段，您将看到消息：请为“复合”类型注册渲染器。

  • JSON 对象

    • 使内容片段作者可将 JSON 语法输入到片段的相应元素中。

      • 使 AEM 可存储您从另一服务复制/粘贴的原始 JSON。
      • JSON 将被传递，并在 GraphQL 中作为 JSON 输出。
      • 在内容片段编辑器中包括 JSON 语法高亮显示、自动补全和错误高亮显示。

  • 制表符占位符

    • 允许引入选项卡，以供在编辑内容片段内容时使用。

      • 这些选项卡在模型编辑器中显示为分隔条，用于分隔内容数据类型的列表的各个部分。 每个实例表示一个新选项卡的开始。
      • 在片段编辑器中，每个实例都显示为一个选项卡。
      note
      NOTE
      此数据类型仅用于格式设置，因此 AEM GraphQL 架构会忽略此数据类型。
      制表符占位符​字段必须始终显示在现有字段上方。

属性（数据类型） properties

许多属性含义一目了然，对于某些属性，其他详细信息如下：

  • 属性名称

    在手动更新数据类型的此属性时，名称​必须仅​包含 A-Z、a-z、0-9 和作为特殊字符的下划线“_”。

    note caution
    CAUTION
    如果在 AEM 早期版本中创建的模型包含非法字符，请移除或更新这些字符。

  • 呈现为

    用于在片段中实现/呈现字段的各种选项。 通常，这允许您定义作者将看到字段的单个实例，还是允许作者创建多个实例。 当使用​ 多个字段 ​时，您可以定义项目的最小和最大数量 — 有关详细信息，请参阅验证。

  • 字段标签
    输入​ 字段标签 ​将自动生成​属性名称，如有必要，可以手动更新该名称。

  • 验证
    基本验证可由以下机制提供： Required​属性。 某些数据类型具有附加的验证字段。 请参阅验证，了解更多详细信息。

  • 对于数据类型​多行文本，可将​ 默认类型 ​定义为以下任一类型：

    • 富文本
    • Markdown
    • 纯文本

    如果未指定，则默认值​ 富文本 ​用于此字段。

    在编辑器中打开并保存现有相关的内容片段后，更改内容片段模型中的​ 默认类型 ​才对该片段生效。

  • 唯一
    对于从当前模型创建的所有内容片段，内容（适用于特定字段）必须是唯一的。

    用于确保内容作者不能重复已添加到同一模型的另一个片段中的内容。

    例如，内容片段模型中名为 Country 的​ 单行文本 ​字段在两个相关内容片段中不能具有值Japan。 尝试第二个实例时会发出警告。

    note
    NOTE
    确保每个语言根的唯一性。
    note
    NOTE
    变体可以具有与同一片段变体相同的​ 唯一 ​值，但与其他片段变体中使用的值不同。

  • 有关特定数据类型及其属性的更多详细信息，请参阅​内容参考。

  • 有关特定数据类型及其属性的更多详细信息，请参阅​片段引用。

  • 可翻译

    选中内容片段模型编辑器中字段上的​ 可翻译 ​复选框将：

    • 如果属性名称尚不存在，请确保字段的属性名称已添加到翻译配置上下文/content/dam/<sites-configuration>。
    • 对于 GraphQL：请将 <translatable>Content Fragment 字段上的属性设置为 yes，以允许 GraphQL 查询过滤仅包含可翻译内容的 JSON 输出。

验证 validation

现在，各种数据类型都可以定义在结果片段中输入内容时的验证要求：

  • 单行文本

    • 与预定义正则表达式进行比较。

  • 数字

    • 检查特定值。

  • 内容引用

    • 测试特定类型的内容。
    • 只能引用指定文件大小或更小的资源。
    • 只能引用预定义的宽度和/或高度范围（以像素为单位）内的图像。

  • 片段引用

    • 为特定的内容片段模型测试。

  • 最小项数 / 最大项数

    已定义为​多个字段（使用​ 渲染为 ​设置）的字段具有以下选项：

    • 最小项目数
    • 最大项数

    已在内容片段编辑器中验证这些内容。

嵌套内容 nested-content

内容片段可以使用以下任何数据类型形成嵌套内容：

  • 内容引用

    • 提供对其他任何类型内容的简单引用。
    • 由​ 内容引用 ​数据类型提供
    • 可将其配置为一个或多个引用（在生成的片段中）。

  • 片段引用

    • 引用其他片段，具体取决于指定的模型。

    • 引用的片段与引用片段不同并相互分离。

    • 由​ 片段引用 ​数据类型提供。

    • 允许您包含/检索结构化数据。

      note
      NOTE
      当您使用通过 GraphQL 使用内容片段投放 Headless 内容时，此方法尤其值得关注。

    • 可将其配置为一个或多个引用（在生成的片段中）。

    • 当需要模块化、可重复使用的内容时适用。

  • 复合数据类型：

    • 引用其他片段，具体取决于指定的模型。
    • 引用的片段完全嵌入引用片段并成为引用片段的组成部分。 他们有真正的父子关系。
      • 复合数据类型允许您定义一组字段作为父片段中的内联、可重复结构，而不是指向单独的片段引用。
    • 复合字段在与父片段相同的编辑器会话中进行编辑。
    • 允许您包含/检索结构化数据。
    • 适合以模块化重用为主要目标的多值复合字段。
    • 支持使用更扁平且更易于管理的内容结构，还可以帮助提高系统和API性能。
NOTE
AEM 对于以下各项具有重复保护：

  • 内容引用
    此项阻止用户添加对当前片段的引用，可能导致片段引用选取器对话框为空。

  • GraphQL 中的片段引用
    如果创建一个深层查询，该查询返回多个互相引用的内容片段，则该查询在第一次出现时返回 null。

CAUTION
如果要查询多个引用的片段，则建议不要让各种片段模型具有具有相同名称但类型不同的字段名称。
有关详细信息，请参阅用于内容片段的AEM GraphQL API — 限制

内容引用 content-reference

内容引用​数据类型允许您呈现来自其他源的内容；例如，图像、页面或体验片段。

除了标准属性之外，您还可以指定：

  • 根路径，它指定或表示存储任何引用内容的位置

    note
    NOTE
    如果您在使用内容片段编辑器时要在此字段中直接上传并引用图像，则必须指定此属性。
    有关进一步详细信息，请参阅引用图像。

  • 可引用的内容类型

    note
    NOTE
    如果您在使用内容片段编辑器时要直接在此字段中上传并引用图像，则其中必须包括​图像。
    有关进一步详细信息，请参阅引用图像。

  • 文件大小限制

  • 如果引用了图像：

    • 显示缩略图
    • 图像高度和宽度的限制

内容引用

片段引用 fragment-reference

片段引用​数据类型可以引用一个或多个内容片段。 在检索内容以供用于您的应用程序时，此功能尤其值得关注，因为通过此功能可检索有多层的结构化数据。

例如：

  • 定义员工详细信息的模型；包括：
    • 对定义雇主（公司）的模型的引用
type EmployeeModel {
    name: String
    firstName: String
    company: CompanyModel
}

type CompanyModel {
    name: String
    street: String
    city: String
}
NOTE
片段引用对于通过 GraphQL 使用内容片段投放 Headless 内容尤其值得关注。

除了标准属性之外，您还可以定义：

  • 呈现为:

    • 多个字段 — 片段作者可以创建多个单个引用

    • 片段引用 — 允许片段作者选择对片段的单个引用

  • 模型类型
    可以选择多个模型。 在添加对内容片段的引用时，必须使用这些模型创建任何引用的片段。

  • 根路径
    这会指定或表示引用的任何片段的根路径。

  • 允许创建片段

    这将允许片段作者根据相应的模型创建片段。

    片段引用

NOTE
已建立重复保护机制。 它禁止用户在片段引用中选择当前内容片段，可能导致片段引用选取器对话框为空。
GraphQL 中也有针对片段引用的重复保护。 如果在两个互相引用的内容片段之间创建深层查询，则它返回 null。

复合数据 composite-data

复合​数据类型允许字段包含嵌套的子字段，从而允许内容片段存储分层的结构化数据。 子项 （子字段）本身是结构化内容，由用户指定的内容片段模型定义，并完全嵌入到​ 父项 ​片段中。

复合数据类型提供了一种方法，用于为单个片段中的复杂数据结构建模，这与JSON中的嵌套对象或NoSQL数据库中的嵌入文档类似。

复合字段具有以下属性和特性：

  • 指定一个或多个内容片段模型

    • 在内容片段模型中定义复合字段时，必须定义哪些模型可用于复合项目。
    • 可以选择多个模型，以便作者可以选择在实际添加项目时要使用的模型。

  • 创作

    • 复合项目与其父片段在同一编辑器会话中进行编辑，而不打开单独的内容片段。

  • 作为多字段分步重复

    • 多值复合支持添加、删除和重新排序项。

  • 多模型复合

    • 单个复合字段可以接受来自多个允许模型的项目。
    • 作者在添加新项目时选取要使用的模型。

  • 变体

    • 顶级变体适用于复合树：变体可能与主视图的复合项目数不同，或者每个项目的内容不同。
    • 选择仅在顶级；嵌套内容反映所选变体。

  • 搜索

    • 复合项目中的文本可搜索。 匹配内容会在搜索结果中返回父内容片段。

  • 本机投放

    • GraphQL和OpenAPI将复合内容作为嵌套数据返回父有效负载中，而无需解析单独的内容片段资源。

  • 干净的引用语义

    • 您可以对属于其父项的内容进行建模，而不会重用该内容。

      note
      NOTE
      为真正可重用的内容保留片段引用。 两者是互补的，而不是替代品。

除了标准属性之外，您还可以定义：

  • 呈现为

    指定以下任一项：

    • 多个字段​支持使用最小/最大约束进行添加/删除/重新排序
    • 复合字段​最多保留一个项

  • 最小/最大项数

    对于多值组合，设置项目数的最小和最大界限

  • 类型

    指定一个或多个内容片段模型。 这些模型中的字段将显示为复合项。 可以选择多个模型，然后作者在添加项目时选择哪个模型。

NOTE
尽管复合字段的内容是根据内容片段模型构建的，但由于缺少特定元数据，它们实际上并不构成内容片段。
WARNING
可以使用“复合”数据类型：
新的内容片段模型编辑器和触屏UI（原始）内容片段编辑器将阻止对复合数据类型和任何依赖字段的访问。
对于新内容片段模型编辑器中的复合字段，您将看到消息：请为“复合”类型注册渲染器。

复合的优势 benefits-of-composite

在建模数据时，复合数据类型可提供多种好处：

  • 更轻松地管理内容结构。

    • 由于复合数据类型直接嵌入在内容片段中，因此无需像引用的片段那样管理复合内容的单独文件夹或存储结构。
    • 这导致更扁平且更少混乱的内容结构，从而简化治理并使复合内容更易于发现。

  • 简化创作，对多值复合字段提供本机支持。

    • 多值组合中的项目可以在与父片段相同的编辑器会话中创建和编辑。
    • 合成可减少引用和片段元数据开销。

  • 改进了内容管理和投放性能。

    • 使用更少的片段引用的更简单的内容结构减少了在创作、发布和投放操作期间的引用解析开销。
    • 更简单的内容结构还可减少JSON有效负载的大小和复杂性，帮助提高API效率和整体客户端性能。

何时使用复合 when-to-use-composite

应仔细考虑使用复合数据类型，因为用例可以确定哪种类型的嵌套内容最适合您。

  • 建议您在以下情况下使用：

    • 生成​ 类似页面的内容 ​或​类似卡片列表的内容，子项不会在其他位置重复使用。
    • 在交付或发布时遇到了参考图性能问题。
    • 让作者抱怨嵌套内容的选项卡切换工作流。
    • 需要多字段重复步骤组，这些组当前需要自定义数据类型或外部工具。

  • 出现以下情况时请务必谨慎：

    • 您的内容可跨片段真正重用。 片段引用仍然是共享内容的正确答案；复合适用于内联内容。
    • 您仅使用（原始）触屏UI编辑器。 新内容片段编辑器支持复合，但原始触屏UI编辑器将阻止编辑复合字段。

复合的限制 limitations-of-composite

下表汇总了“复合”数据类型的当前限制：

  • 创作表面

    • 触屏UI片段编辑器（原始编辑器）
      • 不支持复合字段。
    • 新的(Headless)内容片段模型编辑器
      • 尚不支持复合类型。 模型创作使用原始触屏UI模型编辑器。
        对于复合字段，您将看到以下消息：请注册“复合”类型的渲染器。

  • 跨功能支持

    • MSM（多站点管理器）

      • 只能中断顶级字段的继承。

        • 可以中断整个复合字段的继承。
        • 不支持中断复合项中单个字段的继承。

    • 发布项

      • 不论是直接选择还是通过片段引用包含，启动项均不支持包含复合字段的内容片段。 此类行动不被接受，并将失败。

    • 核心组件和Sling模型导出程序

      • 通过核心组件和Sling模型导出程序(.model.json)进行的页面渲染尚不支持复合字段。

    • 可视化内容片段（包含HTML模板的内容片段）

      • 可视内容片段（包含HTML模板的内容片段）当前不支持复合字段。
recommendation-more-help
experience-manager-cloud-service-help-main-toc