开发AEM组件

AEM组件用于保存、格式化和渲染网页上提供的内容。

• 创作页面时，组件允许作者编辑和配置内容。

  • 例如，在构建Commerce站点时，组件可以从目录中收集和呈现信息。

    有关详细信息，请参阅开发电子商务。

  • 在构建Communities站点时，组件可以向访客提供信息并从其中收集信息。

    有关详细信息，请参阅开发社区。

• 在发布实例中，组件会呈现您的内容，并根据您的需要将其呈现给网站访客。

代码样本

本页提供为AEM开发新组件所需的参考文档（或参考文档的链接）。 有关一些实际示例，请参阅开发AEM组件 — 代码示例。

结构

AEM组件 — 基础知识页上介绍了组件的基本结构。 该文档涵盖触屏优化UI和经典UI。 即使您不需要在新组件中使用经典设置，在从现有组件继承时也可以了解这些设置。

扩展现有组件和对话框

根据要实现的组件，可能可以扩展或自定义现有实例，而不是从头定义和开发整个结构。

在扩展或自定义现有组件或对话框时，您可以复制或复制对话框所需的整个结构或结构，然后再进行更改。

扩展现有组件

可以使用资源类型层次结构和相关继承机制扩展现有组件。

自定义现有组件对话框

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

这意味着您只需重定义所需的差异，而不是重定义整个对话框（使用sling:resourceSuperType）。 现在建议使用此方法来扩展组件对话框

有关更多详细信息，请参阅Sling Resource Merabure。

定义标记

组件将使用HTML进行呈现。 您的组件需要定义需要的HTML，以便获取所需的内容，然后根据需要在创作和发布环境上呈现它。

使用HTML模板语言

随AEM 6.0引入的HTML模板语言(HTL)代替JSP(JavaServer Pages)作为HTML的首选和推荐的服务器端模板系统。 对于需要构建强大企业网站的Web开发人员，HTL有助于提高安全性和开发效率。

开发内容逻辑

此可选逻辑选择和/或计算要呈现的内容。 它从具有相应Use-API模式的HTL表达式中调用。

将逻辑与外观分离的机制有助于阐明对给定视图所调用的内容。 它还允许同一资源的不同视图有不同的逻辑。

使用Java

HTL Java Use-API使HTL文件能够访问自定义Java类中的帮助程序方法。这允许您使用Java代码实现用于选择和配置组件内容的逻辑。

使用JavaScript

HTL JavaScript Use-API使HTL文件能够访问用JavaScript编写的帮助代码。这允许您使用JavaScript代码实现用于选择和配置组件内容的逻辑。

使用客户端HTML库

现代网站严重依赖由复杂的JavaScript和CSS代码驱动的客户端处理。 组织和优化此代码的服务可能是一个复杂的问题。

为了帮助解决此问题，AEM提供​客户端库文件夹，允许您将客户端代码存储在存储库中，将其组织到类别中，并定义将每个代码类别提供给客户端的时间和方式。 然后，客户端库系统将负责在最终网页中生成正确的链接，以加载正确的代码。

有关详细信息，请阅读使用客户端HTML库。

配置编辑行为

您可以配置组件的编辑行为，这些属性包括可用于组件的操作、就地编辑器的特性以及与组件上的事件相关的侦听器等。 该配置对触屏优化UI和经典UI都是通用的，尽管有某些特定的差异。

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

配置预览行为

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

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

创建和配置对话框

对话框用于允许作者与组件进行交互。 使用对话框允许作者和/或管理员编辑内容、配置组件或定义设计参数（使用设计对话框）

Coral UI和Granite UI

Coral UI和 Granite UI定义AEM的现代外观。

Granite UI提供了在创作环境上创建对 话框所需的大量基本组件（构件）。必要时，您可以扩展此选择并创建您自己的Widget。

有关使用Coral和Granite资源类型开发组件的更多信息，请参阅：使用Coral/Granite资源类型构建Experience Manager组件。

有关完整的详细信息，请参阅：

• Coral UI

  • 在所有云解决方案中提供一致的UI
  • AEM触屏优化UI的概念 — Coral UI
  • Coral UI 指南

• Granite UI

  • 提供打包到Sling组件中的Coral UI标记，用于构建UI控制台和对话框
  • AEM触屏优化UI的概念 — Granite UI
  • Granite UI文档

创建新对话框

触屏优化UI的对话框：

• 名为cq:dialog。

• 定义为sling:resourceType属性集的nt:unstructured节点。

• 位于其cq:Component节点下，并位于其组件定义旁。

• 基于其内容结构和sling:resourceType属性在服务器端呈现（作为Sling组件）。

• 使用Granite UI框架。

• 包含描述对话框中字段的节点结构。

  • 这些节点是nt:unstructured，具有所需的sling:resourceType属性。

节点结构的示例可以是：

newComponent (cq:Component)
  cq:dialog (nt:unstructured)
    content 
      layout 
      items 
        column 
          items 
            file 
            description  

自定义对话框与开发组件类似，因为对话框本身是组件（即组件脚本呈现的标记以及客户端库提供的行为/样式）。

有关示例，请参阅：

• /libs/foundation/components/text/cq:dialog
• /libs/foundation/components/download/cq:dialog

自定义对话框字段

创建新字段

触屏优化UI的构件作为Granite UI组件实现。

要为触屏优化UI创建新Widget以在组件对话框中使用，需要创建新的Granite UI字段组件。

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

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

更具体地说，Granite UI提供了一系列适用于对话框（或更一般地，以形式）的字段组件。

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

为样式和行为创建客户端库

如果要为组件定义样式和行为，可创建专用的客户端库，用于定义自定义CSS/LESS和JS。

要仅为您的组件对话框加载您的客户端库（即不为其他组件加载它），您需要将对话框的属性extraClientlibs设置为刚刚创建的客户端库的类别名。 如果您的客户端库很大，并且/或您的字段特定于该对话框，而在其他对话中不需要您，则建议这样做。

要加载所有对话框的客户端库，请将客户端库的类别属性设置为cq.authoring.dialog。 这是显示所有对话框时默认包含的客户端库的类别名称。 如果客户端库很小，且/或字段是通用的，并且可能在其他对话框中重用，则您希望这样做。

有关示例，请参阅：

• cqgems/customizingfield/components/colorpicker/clientlibs

  • 由代码示例提供

扩展（继承自）字段

根据您的要求，您可以：

• 通过组件继承扩展给定的Granite UI字段(sling:resourceSuperType)
• 通过遵循构件库API（JS/CSS继承），从基础构件库扩展给定构件（对于Granite UI，这是Coral UI）

访问对话框字段

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

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

处理字段事件

现在，对对话框字段的事件处理方法在自定义客户端库](#listeners-in-a-custom-client-library)中的侦听器中完成。 这与在内容结构中具有[侦听器的旧方法相比有所变化。

自定义客户端库中的侦听器

要将逻辑插入字段，您应：

1. 将您的字段标记为给定的CSS类(hook)。
2. 在客户端库中定义一个挂接到该CSS类名的JS侦听器（这可确保您的自定义逻辑仅作用于您的字段，且不影响同一类型的其他字段）。

要实现此目的，您需要了解要与之交互的基础Widget库。 请参阅Coral UI文档以确定要对哪个事件做出响应。 这与您过去使用ExtJS执行的过程非常相似：查找给定构件的文档页面，然后检查其事件 API的详细信息。

有关示例，请参阅：

• cqgems/customizingfield/components/clientlibs/customizingfield

  • 由代码示例提供

内容结构中的侦听器

在具有ExtJS的经典UI中，通常在内容结构中具有给定Widget的侦听器。 在触屏优化UI中实现相同功能是不同的，因为JS侦听器代码（或任何代码）在内容中已不再定义。

内容结构描述了语义结构；它不应（必须）暗示基础构件的性质。 如果内容结构中没有JS代码，则无需更改内容结构即可更改实施详细信息。 换句话说，您无需触摸内容结构即可更改构件库。

检测对话框的可用性

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

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

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

字段验证

必填字段

要将给定字段标记为必填，请在字段的内容节点上设置以下属性：

• 名称: required
• 类型: Boolean

有关示例，请参阅：

/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title

字段验证(Granite UI)

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

有关示例，请参阅：

• cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js

  • 由代码示例提供

• /libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js

创建和配置设计对话框

当组件具有可在设计模式中编辑的设计详细信息时，将提供“设计”对话框。

该定义与用于编辑内容](#creating-a-new-dialog)的[对话框的定义非常相似，其区别在于它被定义为节点：

• 节点名称：cq:design_dialog
• 类型: nt:unstructured

创建和配置就地编辑器

就地编辑器允许用户直接编辑段落流中的内容，无需打开对话框。 例如，标准文本组件和标题组件都具有就地编辑器。

对于每个组件类型，就地编辑器并非必需/有意义。

有关详细信息，请参阅扩展页面创作 — 添加新就地编辑器。

自定义组件工具栏

组件工具栏允许用户访问组件的一系列操作，如编辑、配置、复制和删除。

有关详细信息，请参阅扩展页面创作 — 向组件工具栏添加新操作。

为引用边栏配置组件（借入/借出）

如果您的新组件引用了其他页面的内容，则您可以考虑是否希望它影响​引用​边栏的​借入内容​和​借出内容​部分。

现成的AEM只检查引用组件。 要添加组件，您需要配置OSGi bundle WCM创作内容引用配置。

在定义中创建新条目，指定您的组件以及要检查的属性。 例如：

/apps/<your-Project>/components/reference@parentPath

启用组件并将其添加到段落系统

开发组件后，需要启用该组件以在相应的段落系统中使用，以便在所需的页面上使用。

可通过以下任一方式执行此操作：

• 编辑特定页面时使用设计模式。
• 在模板](/docs/experience-manager-64/developing/components/components-basics.html?lang=zh-Hans#adding-your-component-to-the-paragraph-system)的段落系统上定义组件[属性。

配置段落系统以便拖动资产可创建组件实例

AEM优惠在您的页面上配置段落系统，以便当用户将（适当）资产拖动到该页面](/docs/experience-manager-64/sites-authoring/editing-content.html?lang=zh-Hans)的实例时，会自动创建新组件的[实例（而不是总是将空组件拖动到页面）。

可以配置此行为以及所需的资产与组件关系：

1. 在页面设计的段落定义下。 例如：

   • /etc/designs/<myApp>/page/par

   创建新节点：

   • 名称: cq:authoring
   • 类型: nt:unstructured

2. 在此下，创建一个新节点以保存所有资产到组件映射：

   • 名称: assetToComponentMapping
   • 类型: nt:unstructured

3. 对于每个资产到组件映射，请创建一个节点：

   • 名称：文本；建议名称指示资产及相关组件类型；例如，图像
   • 类型: nt:unstructured

   每个都具有以下属性：

   • assetGroup:

     • 类型: String
     • 值：相关资产所属的组；例如，media

   • assetMimetype:

     • 类型: String
     • 值：相关资产的mime类型；例如image/*

   • droptarget:

     • 类型: String
     • 值：投掷目标;例如，image

   • resourceType:

     • 类型: String
     • 值：相关组件资源；例如，foundation/components/image

   • type:

     • 类型: String
     • 值：类型，例如Images

有关示例，请参阅：

• /etc/designs/geometrixx/jcr:content/page/par/cq:authoring
• /etc/designs/geometrixx-outdoors/jcr:content/page/par/cq:authoring
• /etc/designs/geometrixx-media/jcr:content/article/article-content-par/cq:authoring

GITHUB上的代码

您可以在GitHub上找到此页面的代码

• 在GitHub上打开aem-project-archetype项目
• 将项目下载为ZIP文件

使用AEM Brackets扩展

AEM Brackets Extension提供了编辑AEM组件和客户端库的流畅工作流。 它基于Brackets代码编辑器。

扩展：

• 简化同步（不需要Maven或File Vault），以帮助提高开发人员效率，并帮助具有有限AEM知识的前端开发人员参与项目。
• 提供某些HTL支持，该模板语言旨在简化组件开发并提高安全性。

从经典组件迁移

将设计用于经典UI的组件迁移到可与触屏优化UI一起使用的组件（单独或联合使用）时，应考虑以下问题：

• HTL

  • 使用HTL并非强制性的，但如果您的组件需要更新，则最好考虑从JSP迁移到HTL](/docs/experience-manager-64/developing/components/components-basics.html?lang=zh-Hans#htl-vs-jsp)。[

• 组件

  • 迁移使用经典UI特定函数的 cq:listener代码
  • RTE插件，有关详细信息，请参阅配置富文本编辑器。
  • 迁 cq:listener 移使用经典UI特定函数的代码

• 对话框

  • 您需要创建新对话框才能在触屏优化UI中使用。 但是，出于兼容性考虑，当未为触屏优化UI定义对话框时，触屏优化UI可以使用经典UI对话框的定义。
  • 提供AEM现代化工具以帮助您扩展现有组件。
  • 将ExtJS映射到Granite UI组 件可方便地概述ExtJS xtypes和节点类型及其等效的Granite UI资源类型。
  • 自定义字段，有关详细信息，请参阅自定义对话框字段上的AEM Gems会话。
  • 从vtypes迁移到Granite UI验证
  • 使用JS监听器，有关详细信息，请参阅处理字段事件和自定义对话框字段上的AEM Gems会话。

迁移cq：监听器代码

如果您迁移的项目是为经典UI设计的，则cq:listener代码（和与组件相关的clientlibs）可能使用特定于经典UI的函数（如CQ.wcm.*）。 对于迁移，必须使用触屏优化UI中的对等对象/函数更新此类代码。

如果您的项目正在完全迁移到触屏优化UI，您需要替换此类代码以使用与触屏优化UI相关的对象和功能。

但是，如果您的项目在迁移期间（通常情况）必须同时满足经典UI和触屏优化UI的需求，则您需要实现一个切换以区分引用相应对象的单独代码。

此切换机制可实现为：

if (Granite.author) {
    // touch UI
} else {
    // classic UI
}

正在记录您的组件

作为开发人员，您需要轻松访问组件文档，以便快速了解：

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

因此，很容易将组件本身中可用的任何现有文档标记设置为可用。

您只需将README.md文件放入组件结构中。 此标记随后将显示在组件控制台中。

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