内容片段模型 content-fragment-models

Last update: Wed Nov 13 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：
内容片段

创建对象：

用户
开发人员

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

要使用内容片段模型，您可以：

为您的实例启用内容片段模型功能
创建和配置，内容片段模型
启用您的内容片段模型，以便在创建内容片段时使用
通过配置策略，允许在所需的 Assets 文件夹上创建内容片段模型。

创建内容片段模型 creating-a-content-fragment-model

导航到 “工具”、“常规”，然后打开 “内容片段模型”。
导航到适合您的配置或子配置的文件夹。

使用创建打开向导。

note caution
CAUTION
如果尚未允许使用内容片段模型，则将没有创建选项可用。

指定 模型标题。还可定义多种属性；例如，添加标记、描述，如果需要，请选择 启用模型 以启用模型，并定义
默认预览 URL 模式。

note note
NOTE
有关完整详细信息，请参阅内容片段模型 - 属性。

标题和描述

使用创建保存空模型。随后将显示一条消息，指示操作成功，您可选择打开以立即编辑模型或选择完成以返回控制台。

CAUTION

如果要查询多个引用的片段，则建议不要让各种片段模型具有具有相同名称但类型不同的字段名称。

有关详细信息，请参阅用于内容片段的AEM GraphQL API — 限制

内容片段模型 – 属性 content-fragment-model-properties

在您创建模型时定义这些属性，随后可用内容片段模型的属性选项编辑这些属性：

基本
- 模型标题
- 标记
- 描述
- 启用模型
- 默认预览 URL 模式
  通过内容片段编辑器，作者可在外部前端应用程序中预览其内容。在配置 预览服务 后，添加该前端应用程序的 URL。
  
  预览 URL 应遵循此模式：
  https://<preview_url>?param=${expression}
  
  可用的表达式为：
  - ${contentFragment.path}
  - ${contentFragment.model.path}
  - ${contentFragment.model.name}
  - ${contentFragment.variation}
  - ${contentFragment.id}
- 上传图像

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

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

CAUTION

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

导航到工具、常规，然后打开 内容片段模型。
导航到容纳您的内容片段模型的文件夹。

打开所需的模型进行 “编辑”；使用快速操作或选择模型，然后从工具栏中选择操作。

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

左：字段已定义
右侧：可用于创建字段的 数据类型（可在创建字段后使用的属性）

note note
NOTE
将字段定义为必填时，将为左侧窗格中所示的标签标星号 (*)。

添加字段

将字段的必需数据类型拖到所需位置：

将字段添加到模型后，右侧面板将显示可以为该特定数据类型定义的属性。您可以在此定义该字段的必需内容。

许多属性的含义一目了然，有关更多详细信息，请参阅属性。

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

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

例如：

字段属性

移除字段

选择必填字段，然后选择垃圾桶图标。系统会要求您确认该操作。
添加所有必填字段，并根据需要定义相关属性。例如：
选择 “保存” 来保留定义。

数据类型 data-types

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

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

多行文本

一个文本区域，它可为富文本、纯文本或 Markdown
字段可以配置为允许片段作者创建新字段实例

note note
NOTE
在模型中由默认类型属性定义该文本区域是富文本、纯文本还是 Markdown。
无法从内容片段编辑器更改此格式，而只能从模型更改。

数字
- 添加数字字段
- 字段可以配置为允许片段作者创建新字段实例
布尔型
- 添加布尔复选框
日期和时间
- 添加日期和/或时间字段
枚举
- 添加一组复选框、单选按钮或下拉字段
  - 您可以指定对片段作者可用的选项
标记
- 允许片段作者访问和选择标记区域
内容引用
- 引用任何类型的其他内容；可用于创建嵌套内容
- 如果图像被引用，您可以选择显示缩略图
- 字段可以配置为允许片段作者创建新字段实例
片段引用
- 引用其他内容片段；可用于创建嵌套内容
- 字段可以配置为允许片段作者：
  - 直接编辑引用的片段
  - 根据相应的模型创建新内容片段
  - 创建字段的新实例
JSON 对象
- 使内容片段作者可将 JSON 语法输入到片段的相应元素中。
  - 使 AEM 可存储您从另一服务复制/粘贴的直接 JSON。
  - JSON 将被传递，并在 GraphQL 中作为 JSON 输出。
  - 在内容片段编辑器中包括 JSON 语法高亮显示、自动补全和错误高亮显示。

选项卡占位符

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

这些选项卡在模型编辑器中显示为分隔条，用于分隔内容数据类型的列表的各个部分。每个实例表示一个新选项卡的开始。
在片段编辑器中，每个实例都显示为一个选项卡。

note note
NOTE
此数据类型仅用于格式设置，因此 AEM GraphQL 架构会忽略此数据类型。

属性 properties

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

属性名称

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

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

呈现为

用于在片段中实现/呈现字段的各种选项。通常，这允许您定义作者将看到字段的单个实例，还是允许作者创建多个实例。当使用 多个字段 时，您可以定义项目的最小和最大数量 — 有关详细信息，请参阅验证。
字段标签
输入 字段标签 将自动生成 属性名称，如有必要，可以手动更新该名称。
验证
基本验证可由以下机制提供：必需属性。某些数据类型具有附加的验证字段。请参阅验证，了解更多详细信息。
对于数据类型 多行文本，可将 默认类型 定义为以下任一类型：
- 富文本
- Markdown
- 纯文本
如果未指定，则默认值 富文本 用于此字段。

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

唯一
（特定字段的）内容必须在从当前模型创建的所有内容片段上都唯一。

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

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

note note
NOTE
确保每个语言根的唯一性。

note note
NOTE
变体可以具有与同一片段变体相同的唯一值，但与其他片段变体中使用的值不同。

有关特定数据类型及其属性的更多详细信息，请参阅 内容参考。
有关特定数据类型及其属性的更多详细信息，请参阅 片段引用（嵌套片段）。
可翻译

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

验证 validation

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

单行文本
- 与预定义正则表达式进行比较。
数字
- 检查特定值。
内容引用
- 测试特定类型的内容。
- 只能引用指定文件大小或更小的资源。
- 只能引用预定义的宽度和/或高度范围（以像素为单位）内的图像。
片段引用
- 为特定的内容片段模型测试。
最小项数 / 最大项数

已定义为 多个字段（使用 渲染为 设置）的字段具有以下选项：
- 最小项目数
- 最大项数
已在内容片段编辑器中验证这些内容。

使用引用表单嵌套内容 using-references-to-form-nested-content

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

内容引用
- 提供对其他内容的简单引用；任何类型的。
- 可以为一个或多个引用（在生成的片段中）配置。

片段引用（嵌套片段）

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

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

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

* 可为（所得片段中的）一个或多个引用配置它。

NOTE

AEM 对于以下各项具有重复保护：

内容引用
这会阻止用户添加对当前片段的引用，并可能导致出现空的片段引用选取器对话框。
GraphQL中的片段引用
如果创建一个深层查询，且该查询返回多个相互引用的内容片段，则该查询在第一次出现时返回null。

CAUTION

如果要查询多个引用的片段，则建议不要让各种片段模型具有具有相同名称但类型不同的字段名称。

有关详细信息，请参阅用于内容片段的AEM GraphQL API — 限制

内容引用 content-reference

通过内容引用，可从图像、页面或体验片段等另一来源呈现内容。

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

根路径，它指定要将任何引用的内容存储在何处

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

可引用的内容类型

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

文件大小限制
如果引用了图像：
- 显示缩略图
- 图像高度和宽度的限制

内容引用

片段引用（嵌套片段） fragment-reference-nested-fragments

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

例如：

定义员工详细信息的模型；包括：
- 对定义雇主（公司）的模型的引用

type EmployeeModel {
    name: String
    firstName: String
    company: CompanyModel
}

type CompanyModel {
    name: String
    street: String
    city: String
}

NOTE

片段引用对于通过 GraphQL 使用内容片段投放 Headless 内容尤其值得关注。

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

呈现为:
- 多字段 – 片段作者可以创建多个单个引用
- 片段 – 允许片段作者选择对片段的单个引用
模型类型
可以选择多个模型。在添加对内容片段的引用时，必须使用这些模型创建任何引用的片段。
根路径
这会为引用的任何片段指定根路径。
允许创建片段

这将允许片段作者根据相应的模型创建片段。
- 片段引用组合 – 允许片段作者通过选择多个片段来构建复合

NOTE

已建立重复保护机制。它禁止用户在片段引用中选择当前内容片段，可能导致片段引用选取器对话框为空。

GraphQL 中也有针对片段引用的重复保护。如果在两个互相引用的内容片段之间创建深层查询，则它返回 null。

启用或禁用内容片段模型 enabling-disabling-a-content-fragment-model

可启用或禁用内容片段模型，从而全面控制其使用。

启用内容片段模型 enabling-a-content-fragment-model

创建模型后必须启用它，以使其：

可在创建内容片段时进行选择。
可以在内容片段模型中引用。
可用于 GraphQL；这样就会生成架构。

要启用标记为以下任一类型的模型：

草稿：新（从未启用）。
已禁用：已被特别禁用。

您可以从以下任一位置使用 “启用” 选项：

选择所需的“模型”时，顶部工具栏。
相应的快速操作（将鼠标悬停在所需模型上）。

启用草稿或禁用的模型

禁用内容片段模型 disabling-a-content-fragment-model

也可以禁用模型，这样：

该模型将无法再用来创建新内容片段。
但是:
- GraphQL 架构一直在生成，并且仍可查询（以避免影响 JSON API）。
- 仍可以从 GraphQL 端点查询和返回任何基于模型的内容片段。
该模型无法再次引用，但现有引用将保持不变，并且仍可以从 GraphQL 端点查询和返回。

要禁用标为 已启用 的模型，可从以下任意一处使用禁用选项：

选择所需的“模型”时，顶部工具栏。
相应的快速操作（将鼠标悬停在所需模型上）。

禁用启用的模型

允许在 Assets 文件夹中使用内容片段模型 allowing-content-fragment-models-assets-folder

要实施内容管理，您可以在 Assets 文件夹中配置策略，以控制允许在该文件夹中创建片段的内容片段模型。

NOTE

该机制类似于允许在页面的高级属性中为页面及其子页面设置页面模板。

要为 允许的内容片段模型 配置策略：

导航并打开属性，以访问所需的 Assets 文件夹。
打开策略选项卡，您可以在其中配置：
- 继承自<folder>
  
  在创建新的子文件夹时自动继承策略；如果子文件夹需要允许模型与父文件夹不同，则可重新配置策略（并中断继承）。
- 按照路径允许的内容片段模型
  
  可以允许使用多个模型。
- 按标记允许的内容片段模型
  
  可以允许使用多个模型。
保存任何更改。

文件夹允许的内容片段模型解析如下：

针对 允许的内容片段模型 的策略。
如果为空，请尝试使用继承规则确定策略。
如果继承链未投放结果，请查看 Cloud Services 文件夹的配置（也请先直接配置，然后通过继承配置）。
如果以上所有内容均未提供任何结果，则该文件夹不允许使用模型。

删除内容片段模型 deleting-a-content-fragment-model

CAUTION

删除内容片段模型可能会影响从属片段。

要删除内容片段模型，请执行以下操作：

导航到工具、常规，然后打开 内容片段模型。
导航到容纳您的内容片段模型的文件夹。

选择您的模型，然后从工具栏中选择删除。

note note
NOTE
如果引用该模型，则显示一条警告，以使您可执行适当的操作。

发布内容片段模型 publishing-a-content-fragment-model

需要在发布任何从属的内容片段时/之前发布内容片段模型。

要发布内容片段模型，请执行以下操作：

导航到工具、常规，然后打开 内容片段模型。
导航到容纳您的内容片段模型的文件夹。

选择您的模型，然后从工具栏中选择发布。随后将在控制台中显示已发布状态。

note note
NOTE
如果发布尚未发布其模型的内容片段，则将有一个选择列表指出这一点，并将与该片段一起发布模型。

取消发布内容片段模型 unpublishing-a-content-fragment-model

如果没有任何片段引用内容片段模型，则可取消发布这些模型。

要取消发布内容片段模型，请执行以下操作：

导航到工具、常规，然后打开 内容片段模型。
导航到容纳您的内容片段模型的文件夹。
选择您的模型，然后从工具栏中选择 取消发布。控制台中会指示已发布状态。

如果尝试取消发布当前由一个或多个片段使用的模型，则显示一条错误警告。例如：

取消发布正在使用的模型时的内容片段模型错误消息

该消息建议您检查引用面板以进一步调查：

引用中的内容片段模型

锁定（已发布）内容片段模型 locked-published-content-fragment-models

此功能为已发布的内容片段模型提供管理服务。

挑战 the-challenge

内容片段模型确定 AEM 中 GraphQL 查询的架构。
- AEM GraphQL 架构在创建内容片段模型后即会创建，并且它们可以同时存在于创作和发布环境中。
- 发布架构是最为关键，因为它们为 JSON 格式的内容片段的实时投放奠定了基础。
修改内容片段模型或进行其他编辑时，可能会出现问题。这意味着架构发生更改，进而可能影响现有 GraphQL 查询。
向内容片段模型添加新字段通常不应产生任何有害影响。但是，修改现有数据字段（例如，其名称）或删除字段定义时，将在请求这些字段时中断现有 GraphQL 查询。