开发AEM组件

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

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

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

    See Developing eCommerce for more information.

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

    See Developing Communities for more information.

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

代码样本

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

结构

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

扩展现有组件和对话框

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

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

扩展现有组件

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

自定义现有组件对话框

也可以使用Sling Resource Merabile 来覆盖​组件对话框 , sling:resourceSuperType并定义属性。

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

有关更多 详细信息，请参 阅Sling资源合并。

定义标记

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

使用HTML模板语言

The HTML Templating Language (HTL), introduced with AEM 6.0, takes the place of JSP (JavaServer Pages) as the preferred and recommended server-side template system for HTML. 对于需要构建强大企业网站的Web开发人员，HTL有助于提高安全性和开发效率。

开发内容逻辑

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

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

使用Java

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

使用JavaScript

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

使用客户端HTML库

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

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

阅 读使用客户端HTML库 ，了解更多信息。

配置编辑行为

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

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

配置预览行为

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

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

创建和配置对话框

对话框用于允许作者与组件进行交互。 使用对话框，作者和／或管理员可以编辑内容、配置组件或定义设计参数(使用“设 计”对话框)

Coral UI和Granite UI

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

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

有关使用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文档

Creating a New Dialog

触屏优化UI的对话框：

• 名称 cq:dialog。

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

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

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

• 使用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

自定义对话框字段

Creating a New Field

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

要在触屏优化UI的组件对话框中创建新的构件，您需 要创建新的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"]

处理字段事件

现在，在自定义客户端库中对监听器进行对 话字段事件的处理。 这与在内容结构中设置监听器 的旧方法有所不同。

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

要将逻辑注入您的领域，您应：

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

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

有关示例，请参阅：

• cqgems/customizingfield/components/clientlibs/customizingfield

  • 由代码示 例提供

内容结构中的监听器

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

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

字段验证

必填字段

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

• 名称: 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组件（等效于构件）中的字段验证是使用API完 foundation-validation 成的。 有关详细信息， foundation-valdiation 请参阅Granite文档。

有关示例，请参阅：

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

  • 由代码示 例提供

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

创建和配置设计对话框

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

该定义与用于编辑内容的 对话框的定义非常相似，区别在于它被定义为节点：

• Node name: cq:design_dialog
• 类型: nt:unstructured

创建和配置就地编辑器

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

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

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

自定义组件工具栏

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

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

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

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

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

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

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

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

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

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

• 编辑 特定页面 时使用“设计”模式。
• 在模板的 段落系统中定义组件属性。

Configuring a Paragraph System so that Dragging an Asset Creates a Component Instance

AEM优惠在页面上配置段落系统 的可能性，当用户将（适当）资产拖动到该页面的实例时，系统会自动创建新组件的实例 （而不是始终将空组件拖动到页面）。

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

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。

• 组件

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

• 对话框

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

迁移cq：监听器代码

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

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

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

此切换机制可实现为：

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

对组件进行文档化

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

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

因此，很容易将您在组件本身中提供的任何现有文档标记公开。

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

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