组件参考指南 components-reference-guide

组件是在AEM中构建体验的核心。 使用核心组件和AEM项目原型，可以轻松开始使用一组现成的可靠组件。 WKND教程将指导开发人员了解如何使用这些工具以及如何构建自定义组件来创建AEM站点。

由于WKND教程涵盖了大多数用例，因此，本文档仅用于补充这些资源。 它提供了有关如何在AEM中构建和配置组件的深入技术细节，并非旨在作为快速入门指南。

概述 overview

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

规划 planning

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

重用现有组件 reusing-components

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

扩展核心组件 extending-core-components

核心组件还提供了清晰的自定模式，您可以使用这些模式来调整它们以适应您自己的项目需求。

覆盖组件 overlying-components

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

扩展组件对话框 extending-component-dialogs

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

这意味着您只需要重新定义所需的差异，而不是重新定义整个对话框。

内容逻辑和渲染标记 content-logic-and-rendering-markup

您的组件已使用HTML呈现。 您的组件必须定义获取所需HTML所需的内容，然后根据需要在Author和Publish环境中呈现该内容。

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

HTL支持此理念，这是一种模板化语言，旨在确保使用真正的编程语言来定义基础业务逻辑。 此机制会突出显示为给定视图调用的代码，如有必要，还允许为同一组件的不同视图使用特定逻辑。

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

组件结构 structure

AEM组件的结构强大而灵活。 主要工作内容包括：

资源类型 resource-type

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

这是一个抽象，有助于确保即使当外观和感觉随时间变化时，意图仍会随时间而改变。

组件定义 component-definition

组件的定义可细分如下：

重要属性 vital-properties

组件图标 component-icon

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

如果在组件中未找到以上任何属性（cq:icon、abbreviation、cq:icon.png或cq:icon.svg）：

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

组件控制台显示如何定义特定组件的图标。

SVG图标示例 svg-icon-example

<?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>

组件的属性和子节点 properties-and-child-nodes-of-a-component

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

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

如果查看​ Text ​组件，您可以看到以下几个元素：

特别感兴趣的物业包括：

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

对话框 dialogs

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

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

AEM组件的对话框：

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

标题组件的对话框定义

设计对话框 design-dialogs

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

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

Coral用户界面和Granite用户界面 coral-and-granite

Coral UI和Granite UI定义了AEM的外观。

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

有关其他详细信息，请参阅以下资源：

自定义对话框字段 customizing-dialog-fields

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

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

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

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

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

对对话框字段的访问权限 access-to-dialog-fields

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

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

使用组件 using-components

创建组件后，必须启用它才能使用它。 使用它可显示组件的结构与存储库中生成内容的结构之间的关系。

将组件添加到模板 adding-your-component-to-the-template

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

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

组件及其创建的内容 components-and-the-content-they-create

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

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

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

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

组件层次结构和继承 component-hierarchy-and-inheritance

AEM中的组件遵循​ 资源类型层次结构。 用于使用属性sling:resourceSuperType扩展组件。 这将使组件继承自其他组件。

有关详细信息，请参阅重用组件部分。

编辑行为 edit-behavior

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

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

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

组件占位符 component-placeholders

组件必须始终呈现对作者可见的一些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是一个变量，仅当组件没有内容并且作者不可见时才会为真。

为避免重复，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是变量，仅当内容包含内容且可见时才会为真。

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

使用cq：EditConfig子节点进行配置 configuring-with-cq-editconfig-child-nodes

将Assets拖放到对话框中 — cq：dropTargets cq-droptargets

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

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

就地编辑 — cq：inplaceEditing cq-inplaceediting

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

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

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

以下配置启用就地编辑组件并将plaintext定义为编辑器类型：

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

处理字段事件 — cq：listeners cq-listeners

在自定义客户端库中使用侦听器处理对话框字段上的事件的方法。

要将逻辑注入到字段中，您应：

要实现此目的，您需要了解要与之交互的底层构件库。 请参阅Coral UI文档，以识别您要对哪个事件做出反应。

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"/>

字段验证 field-validation

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

检测对话框的可用性 dialog-ready

如果您有一个自定义JavaScript，只有在对话框可用并准备就绪时才必须运行，则您应该监听dialog-ready事件。

只要对话框加载（或重新加载）并准备就绪，即表示只要对话框的DOM中存在更改（创建/更新），就会触发此事件。

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

预览行为 preview-behavior

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

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

记录组件 documenting-components

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

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

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

组件结构中的

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

在组件控制台中显示

支持的Markdown与内容片段相同。