组件参考指南

组件是在AEM中构建体验的核心。 通过核心组件和AEM项目原型，可轻松开始使用一组现成的强大组件。 WKND Tutorial向开发人员介绍如何使用这些工具以及如何构建自定义组件以创建新的AEM站点。

由于WKND教程涵盖大多数用例，因此本文档仅作为这些资源的补充。 本指南详细介绍了组件在AEM中的结构和配置方式，不是入门指南。

概述

本节介绍一些关键概念和问题，并介绍开发您自己的组件时所需的详细信息。

规划

在开始实际配置或编码组件之前，您应该先询问：

• 您到底需要新组件执行哪些操作？
• 您是需要从头开始创建组件，还是可以从现有组件继承基础知识？
• 您的组件是否需要逻辑才能选择/操作内容？
  • 逻辑应与用户界面层分开。 HTL旨在帮助确保实现此目的。
• 您的组件是否需要CSS格式？
  • CSS格式应与组件定义分开。 定义命名HTML元素的约定，以便您能够通过外部CSS文件修改它们。
• 您的新组件可能会引入哪些安全影响？

重用现有组件

在花时间创建全新组件之前，请考虑自定义或扩展现有组件。 核心组 件提供了一套灵活、强大且经过良好测试的生产就绪型组件。

扩展核心组件

核心组件还提供清除自定义模式，您可以使用这些模式根据您自己项目的需求进行调整。

将组件覆盖

组件也可基于搜索路径逻辑通过覆盖重定义。 但是，在这种情况下，将不会触发Sling资源合并器，并且/apps必须定义整个叠加。

扩展组件对话框

还可以使用Sling资源合并器覆盖组件对话框，并定义属性sling:resourceSuperType。

这表示您只需重定义所需的差异，而不需要重定义整个对话框。

内容逻辑和渲染标记

组件将以HTML呈现。 您的组件需要定义获取所需内容所需的HTML，然后在创作和发布环境中根据需要渲染该内容。

建议将负责标记和渲染的代码与用于控制组件内容选择逻辑的代码分开。

HTL支持此理念，它是一种模板语言，经过刻意限制，可确保使用真正的编程语言来定义底层业务逻辑。 此机制会突出显示为给定视图调用的代码，并在必要时，允许对同一组件的不同视图使用特定逻辑。

此（可选）逻辑可以通过不同方式实现，并可通过特定命令从HTL中调用：

• 使用Java - HTL Java Use-API使HTL文件能够访问自定义Java类中的Helper方法。 这允许您使用Java代码实施用于选择和配置组件内容的逻辑。
• 使用JavaScript - HTL JavaScript Use-API使HTL文件能够访问使用JavaScript编写的帮助程序代码。 这允许您使用JavaScript代码实施用于选择和配置组件内容的逻辑。
• 使用客户端库 — 现代网站严重依赖由复杂JavaScript和CSS代码驱动的客户端处理。 有关更多信息，请参阅文档在AEM上使用客户端库作为Cloud Service。

组件结构

AEM组件的结构强大而灵活。 主要部分包括：

• 资源类型
• 组件定义
• 组件的属性和子节点
• 对话框
• 设计对话框

资源类型

结构的一个关键元素是资源类型。

• 内容结构声明意图。
• 资源类型将实施它们。

这是一个抽象，有助于确保即使外观随时间而改变，意图也会保持不变。

组件定义

组件的定义可按如下方式划分：

• AEM组件基于Sling.
• AEM组件位于/libs/core/wcm/components下。
• 项目/站点特定组件位于/apps/<myApp>/components下。
• AEM标准组件定义为cq:Component，且具有关键元素：
  • jcr属性 — jcr属性的列表。 这些是变量，有些是可选的，但组件节点、其属性和子节点的基本结构由cq:Component定义定义。
  • 资源 — 这些资源定义组件使用的静态元素。
  • 脚本 — 这些脚本用于实施组件生成实例的行为。

重要属性

• 根节点:
  • <mycomponent> (cq:Component) — 组件的层次结构节点。
• 重要属性:
  • jcr:title — 组件标题；例如，当组件在组件浏览器和组件控制台中列出时， 会 用作 标签
  • jcr:description — 组件说明；在组件浏览器和组件控制台中用作鼠标悬停提示
  • 有关详细信息，请参阅组件图标部分
• 重要子节点:
  • cq:editConfig (cq:EditConfig) — 定义组件的编辑属性，并使组件显示在组件浏览器中
    • 如果组件具有对话框，则它将自动显示在组件浏览器或Sidekick中，即使cq:editConfig不存在也是如此。
  • cq:childEditConfig (cq:EditConfig) — 控制未定义其自身的子组件的创作UI方 cq:editConfig面。
  • cq:dialog (nt:unstructured) — 此组件的对话框。定义允许用户配置组件和/或编辑内容的界面。
  • cq:design_dialog (nt:unstructured) — 编辑此组件的设计

组件图标

组件的图标或缩写是在开发人员创建组件时，通过组件的JCR属性来定义的。 这些属性将按以下顺序计算，并使用找到的第一个有效属性。

1. cq:icon — 字符串属性，指向要在组件浏览器中 显示 的Coral UI库中的标准图标
   • 使用Coral图标的HTML属性值。
2. abbreviation — 用于自定义组件浏览器中组件名称的缩写的字符串属性
   • 缩写应限制为两个字符。
   • 如果提供空字符串，则将从jcr:title属性的前两个字符生成缩写。
     • 例如，“Image”的“Im”
     • 将使用本地化的标题来构建缩写。
   • 仅当组件具有abbreviation_commentI18n属性时，缩写才会被翻译，该属性随后会用作翻译提示。
3. cq:icon.png 或 — cq:icon.svg 此组件的图标，该图标显示在组件浏览器中
   • 20 x 20像素是标准组件的图标大小。
     • 大图标的大小将会缩小（客户端）。
   • 推荐颜色为rgb(112, 112, 112)> #707070
   • 标准组件图标的背景是透明的。
   • 仅支持.png和.svg文件。
   • 如果通过Eclipse插件从文件系统导入，则文件名需要转义为_cq_icon.png或_cq_icon.svg。
   • .png 如果两者都 .svg 存在，就会先例。

如果在组件上找不到上述属性（cq:icon、abbreviation、cq:icon.png或cq:icon.svg）：

• 系统将在超级组件上搜索与sling:resourceSuperType属性后面的相同属性。
• 如果在超级组件级别中未找到任何缩写或空缩写，则系统将从当前组件jcr:title属性的前几个字母构建缩写。

要取消超级组件中图标的继承，在组件上设置空abbreviation属性将还原为默认行为。

组件控制台显示特定组件图标的定义方式。

SVG图标示例

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "https://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="https://www.w3.org/2000/svg" xmlns:xlink="https://www.w3.org/1999/xlink" x="0px" y="0px"
     width="20px" height="20px" viewBox="0 0 20 20" enable-background="new 0 0 20 20" xml:space="preserve">
    <ellipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/>
    <ellipse cx="15" cy="5" rx="4" ry="4" fill="#707070"/>
    <ellipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/>
    <ellipse cx="15" cy="15" rx="4" ry="4" fill="#707070"/>
</svg>

组件的属性和子节点

定义组件所需的许多节点/属性对于两个UI都是通用的，其中差异仍保持独立，因此您的组件可以在这两个环境中工作。

组件是cq:Component类型的节点，具有以下属性和子节点：

如果我们查看​Text​组件，可以看到以下许多元素：

特定权益的物业包括：

• jcr:title — 这是用于在组件浏览器中标识组件的组件标题。
• jcr:description — 此为组件的描述。
• sling:resourceSuperType — 这表示扩展组件（通过覆盖定义）时的继承路径。

特定感兴趣的子节点包括：

• cq:editConfig — 此操作可在编辑时控制组件的可视化方面。
• cq:dialog — 这定义用于编辑此组件内容的对话框。
• cq:design_dialog — 这可指定此组件的设计编辑选项。

对话框

对话框是组件的关键元素，因为它们为作者提供了一个界面，用于在内容页面上配置组件并提供该组件的输入。 有关内容作者如何与组件进行交互的详细信息，请参阅创作文档。

根据组件的复杂性，对话框可能需要一个或多个选项卡。

AEM组件的对话框：

• 是nt:unstructured类型的cq:dialog节点。
• 位于其cq:Component节点下，且位于其组件定义旁边。
• 定义用于编辑此组件内容的对话框。
• 使用Granite UI组件进行定义。
• 根据组件的内容结构和sling:resourceType属性，在服务器端呈现（作为Sling组件）。
• 包含描述对话框中字段的节点结构
  • 这些节点是nt:unstructured，且属性为必需的sling:resourceType。

在对话框中，定义了各个字段：

设计对话框

设计对话框与用于编辑和配置内容的对话框类似，但它们为模板作者提供了界面，用于在页面模板上预配置和提供该组件的设计详细信息。 然后，内容作者使用页面模板来创建内容页面。 有关如何创建模板的详细信息，请参阅模板文档。

编辑页面模板时会使用设计对话框，但并非所有组件都需要设计对话框。例如，标题​和​图像组件​都具有设计对话框，而​社交媒体共享组件​则没有。

Coral UI和Granite UI

Coral用户界面和Granite用户界面可定义AEM的外观。

• Coral UI为 所有云解决方案提供了一致的UI。
• Granite UI 提供了封装在Sling组件中的Coral UI标记，用于构建UI控制台和对话框。

Granite UI提供了在创作环境中创建对话框所需的一系列基本小组件。 必要时，您可以扩展此选择并创建自己的小组件。

有关更多详细信息，请参阅以下资源：

• AEM UI的结构

自定义对话框字段

要创建在组件对话框中使用的新小组件，需要创建新的Granite UI字段组件。

如果将对话框视为表单元素的简单容器，则还可以将对话框内容的主要内容视为表单字段。 创建新表单字段需要创建资源类型；这等同于创建新组件。 为了帮助您完成该任务，Granite UI提供了一个要从中继承的通用字段组件（使用sling:resourceSuperType）：

/libs/granite/ui/components/coral/foundation/form/field

更具体地说，Granite UI提供了一系列字段组件，这些组件适合在对话框中使用，或者通常在表单中使用。

创建资源类型后，您可以通过在对话框中添加新节点来实例化字段，该节点的属性sling:resourceType引用了您刚才引入的资源类型。

对对话框字段的访问权限

您还可以使用渲染条件(rendercondition)来控制谁有权访问对话框中的特定选项卡/字段；例如：

+ mybutton
  - sling:resourceType = granite/ui/components/coral/foundation/button
  + rendercondition
    - sling:resourceType = myapp/components/renderconditions/group
    - groups = ["administrators"]

使用组件

创建组件后，您需要启用该组件才能使用它。 使用它可显示组件结构与存储库中生成内容的结构有何关系。

将组件添加到模板

定义组件后，必须使其可供使用。 要使组件可在模板中使用，必须在模板布局容器的策略中启用该组件。

有关如何创建模板的详细信息，请参阅模板文档。

组件及其创建的内容

如果在页面上创建并配置​Title​组件的实例：/content/wknd/language-masters/en/adventures/extreme-ironing.html

然后，我们可以看到在存储库中创建的内容的结构：

特别是，如果您查看​标题组件​的实际文本：

• 内容包含jcr:title属性，该属性包含作者输入的标题的实际文本。
• 它还包含对组件定义的sling:resourceType引用。

定义的属性取决于各个定义。 尽管它们可能比上面更复杂，但它们仍遵循相同的基本原则。

组件层次结构和继承

AEM中的组件受​资源类型层次结构​的约束。 用于使用属性sling:resourceSuperType扩展组件。 这允许组件继承其他组件。

有关更多信息，请参阅重用组件一节。

编辑行为

本节介绍如何配置组件的编辑行为。 这包括一些属性，例如组件可用的操作、in.place编辑器的特性，以及与组件上的事件相关的侦听器。

组件的编辑行为通过以下方法进行配置：在组件节点（cq:Component类型）下添加cq:editConfig类型的节点，并添加特定属性和子节点。 cq:EditConfig以下属性和子节点可用：

• cq:editConfig 节点属性
• cq:editConfig 子节点:
  • cq:dropTargets (节点类 nt:unstructured型):定义可以接受内容查找器资产中删除的放置目标列表（允许单个放置目标）
  • cq:inplaceEditing (节点类 cq:InplaceEditingConfig型):为组件定义就地编辑配置
  • cq:listeners (节点类 cq:EditListenersConfig型):定义在组件上执行操作之前或之后发生的情况

AEM中现有的配置很多。 使用​CRXDE Lite​中的“查询”工具，可以轻松搜索特定属性或子节点。

组件占位符

组件必须始终呈现一些对作者可见的HTML，即使组件没有内容也是如此。 否则，它可能会从编辑器的界面中以可视方式消失，从而使其在技术上呈现，但在页面和编辑器中却不可见。 在这种情况下，作者将无法选择空组件并与之进行交互。

因此，只要组件在页面编辑器中呈现页面时（当WCM模式为edit或preview时）不呈现任何可见输出，组件就应呈现占位符。
占位符的典型HTML标记如下所示：

<div class="cq-placeholder" data-emptytext="Component Name"></div>

呈现上述占位符HTML的典型HTL脚本如下所示：

<div class="cq-placeholder" data-emptytext="${component.properties.jcr:title}"
     data-sly-test="${(wcmmode.edit || wcmmode.preview) && isEmpty}"></div>

在上一个示例中，isEmpty是一个变量，仅当组件没有内容且作者不可见时，该变量才为true。

为避免重复，Adobe建议组件实施者为这些占位符使用HTL模板， 类似于核心组件提供的模板。

然后，使用以下HTL行完成模板在上一个链接中的使用：

<sly data-sly-use.template="core/wcm/components/commons/v1/templates.html"
     data-sly-call="${template.placeholder @ isEmpty=!model.text}"></sly>

在上一个示例中，model.text是仅当内容包含且可见时才为true的变量。

此模板的用法示例可在核心组件中查看，如标题组件中。

使用cq:EditConfig子节点进行配置

将资产放入对话框 — cq:dropTargets

cq:dropTargets节点（节点类型nt:unstructured）定义了可接受从内容查找器中拖动的资产中拖放的放置目标。 它是cq:DropTargetConfig类型的节点。

类型cq:DropTargetConfig的子节点定义组件中的放置目标。

就地编辑 — cq:inplaceEditing

就地编辑器允许用户直接在内容流中编辑内容，而无需打开对话框。 例如，标准的​Text​和​Title​组件都具有嵌入式编辑器。

对于每种组件类型，并非都需要/有意义的就地编辑器。

cq:inplaceEditing节点（节点类型cq:InplaceEditingConfig）为组件定义就地编辑配置。 它可以具有以下属性：

以下配置允许对组件进行内置编辑，并将plaintext定义为编辑器类型：

    <cq:inplaceEditing
        jcr:primaryType="cq:InplaceEditingConfig"
        active="{Boolean}true"
        editorType="plaintext"/>

处理字段事件 — cq:listeners

在自定义客户端库中，对对话框字段中的事件进行处理的方法已通过侦听器完成。

要在字段中插入逻辑，您应：

• 使用给定的CSS类（挂接）标记字段。
• 在客户端库中定义一个挂接到该CSS类名称的JS侦听器（这可确保自定义逻辑的范围仅限您的字段，并且不会影响其他相同类型的字段）。

要实现此目的，您需要了解要与之交互的底层小组件库。 请参阅Coral用户 界面文档，以确定要对哪个事件做出响应。

cq:listeners节点（节点类型cq:EditListenersConfig）定义在对组件执行操作之前或之后所发生的情况。 下表定义了其可能的属性。

事件处理程序可以通过自定义实施来实施。 例如（其中project.customerAction是静态方法）：

afteredit = "project.customerAction"

以下示例等效于REFRESH_INSERTED配置：

afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"

通过以下配置，在删除、编辑、插入或移动组件后会刷新页面：

    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afterdelete="REFRESH_PAGE"
        afteredit="REFRESH_PAGE"
        afterinsert="REFRESH_PAGE"
        afterMove="REFRESH_PAGE"/>

字段验证

可使用foundation-validation API在Granite UI和Granite UI小组件中完成字段验证。 有关详细信息，请参阅foundation-valdiation Granite文档。

检测对话框的可用性

如果您有一个自定义JavaScript，该JavaScript需要仅在对话框可用且准备就绪时才执行，则应该侦听dialog-ready事件。

当对话框加载（或重新加载）并准备就绪以供使用时，将触发此事件，这意味着每当对话框的DOM中发生更改（创建/更新）时。

dialog-ready 可用于挂接JavaScript自定义代码，该代码可对对话框或类似任务中的字段执行自定义。

预览行为

切换到预览模式时，即使页面未刷新，也会设置WCM模式 Cookie。

对于呈现的对WCM模式敏感的组件，需要定义它们以专门刷新它们，然后依赖Cookie的值。

记录组件

作为开发人员，您希望轻松访问组件文档，以便快速了解组件的以下功能：

• 描述
• 预期用途
• 内容结构和属性
• 公开的API和扩展点
• 等等

因此，很容易就会在组件中使用您现有的任何文档标记。

您只需在组件结构中放置一个README.md文件即可。

然后，此标记将显示在组件控制台中。

支持的标记与内容片段的标记相同。