文档AEM 6.5用户指南

Adobe Experience Manager (AEM)组件 — 基础知识 aem-components-the-basics

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

创建对象：

  • 开发人员

开始开发新组件时，您需要了解其结构和配置的基础知识。

此过程包括阅读相关理论并查看标准AEM实例中的各种组件实现。 尽管AEM已转移到新的标准、现代、触屏优化UI，但它继续支持经典UI，这个事实使得后一种方法略微复杂化。

概述 overview

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

规划 planning

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

  • 您到底需要新组件做什么？

    • 明确的规范有助于开发、测试和移交的所有阶段。 详细信息可能会随着时间的推移而更改，但规范可以更新（尽管更改也应记录在案）。

  • 您是需要从头开始创建组件，还是可以从现有组件继承基础知识？

    • 不需要重新发明轮子。
    • AEM提供了几种机制，可让您从其他组件定义继承和扩展详细信息，包括覆盖、叠加和Sling资源合并器。

  • 您的组件是否需要逻辑才能选择或处理内容？

    • 逻辑应该与用户界面层分开。 HTL旨在帮助确保做到这一点。

  • 您的组件是否需要CSS格式？

    • CSS格式应与组件定义分开。 定义命名HTML元素的约定，以便您可以通过外部CSS文件修改这些约定。

  • 我应该考虑哪些安全方面？

触屏优化vs经典UI touch-enabled-vs-classic-ui

在有关开发组件的任何严肃讨论开始之前，您必须知道作者使用的是哪种UI：

  • 触屏优化UI
    标准用户界面基于Adobe Experience Cloud的统一用户体验，使用Coral UI和Granite UI的基础技术。
  • 经典UI
    基于ExtJS技术的用户界面，AEM 6.4已弃用该技术。

有关更多详细信息，请参阅面向客户的UI界面Recommendations。

可以实施组件来支持触屏UI和/或经典UI。 在查看标准实例时，您还会看到最初为经典UI或触屏UI或两者设计的现成组件。

本页介绍了这两个函数的基本知识以及如何识别它们。

NOTE
Adobe建议使用触屏优化UI以从最新技术中获益。 AEM现代化工具可以简化迁移。

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

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

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

HTL与JSP htl-vs-jsp

HTL是AEM 6.0中引入的一种HTML模板语言。

关于在开发您自己的组件时是使用HTL还是JSP (Java™ Server Pages)的讨论应该简单明了，因为HTL现在是推荐的AEM脚本语言。

HTL和JSP都可用于为经典用户界面和触屏优化UI开发组件。 尽管可能会倾向于认为HTL仅适用于经典UI的触屏UI和JSP，但这是一个误解，并且更多是由于时间的原因。 触屏优化UI和HTL大约在同一时期内合并到了AEM中。 由于HTL现在是推荐语言，因此它被用于新组件，这些组件倾向于用于触屏优化UI。

NOTE
Granite UI Foundation表单字段除外（在对话框中使用）。 这些仍需要使用JSP。

开发您自己的组件 developing-your-own-components

要为相应的UI创建自己的组件，请参阅（阅读本页后）：

快速入门方法是复制现有组件，然后进行所需的更改。 要了解如何创建自己的组件并将它们添加到段落系统，请参阅：

将组件移动到Publish实例 moving-components-to-the-publish-instance

呈现内容的组件必须部署在与内容相同的AEM实例上。 因此，必须在发布实例上部署所有用于在创作实例上创作和渲染页面的组件。 部署后，组件可用于呈现激活的页面。

使用以下工具将组件移至发布实例：

NOTE
这些机制还可用于在其他实例之间传输组件，例如，从开发实例传输到测试实例。

从开始起要识别的组件 components-to-be-aware-of-from-the-start

  • 页面:

    • AEM具有​ page ​组件(cq:Page)。
    • 这是对内容管理很重要的一种特定类型的资源。
      • 页面对应于包含您网站内容的网页。

  • 段落系统：

    • 段落系统是网站的一个关键部分，因为它管理着一系列段落。 用于保存和构建保存实际内容的各个组件。
    • 您可以在段落系统中创建、移动、复制和删除段落。
    • 您还可以选择可在特定段落系统中使用的组件。
    • 标准实例中有各种可用的段落系统（例如，parsys、 [responsivegrid](/docs/experience-manager-65/sites-authoring/responsive-layout.md)）。

结构 structure

AEM组件的结构强大而灵活，主要考虑因素包括：

  • 资源类型
  • 组件定义
  • 组件的属性和子节点
  • 对话框
  • 设计对话框
  • 组件可用性
  • 组件及其创建的内容

资源类型 resource-type

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

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

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

组件定义 component-definition

组件基础知识 component-basics

组件的定义可细分如下：

  • AEM组件基于Sling。

  • AEM组件（通常）位于以下位置：

    • HTL： /libs/wcm/foundation/components
    • JSP： /libs/foundation/components

  • 项目/站点特定的组件（通常）位于以下位置：

    • /apps/<myApp>/components

  • AEM标准组件定义为cq:Component并具有关键元素：

    • jcr属性：

      jcr属性的列表；这些是变量的，有些可能是可选的，但组件节点的基本结构、其属性和子节点由cq:Component定义定义

    • 资源：

      这些定义组件使用的静态元素。

    • 脚本：

    用于实施组件结果实例的行为。

  • 根节点：

    • <mycomponent> (cq:Component) — 组件的层次结构节点。

  • 重要属性：

    • jcr:title — 组件标题；例如，在组件浏览器或Sidekick中列出组件时用作标签。

    • jcr:description — 组件的描述；可用作组件浏览器或Sidekick中的鼠标悬停提示。

    • 经典UI：

      • icon.png — 此组件的图标。
      • thumbnail.png — 此组件在段落系统中列出时显示的图像。

    • 触屏 UI

      • 有关详细信息，请参阅触屏UI中的组件图标。

  • 重要子节点：

    • cq:editConfig (cq:EditConfig) — 定义组件的编辑属性，并使组件显示在组件浏览器或Sidekick中。

      注意：如果组件有对话框，它将自动显示在组件浏览器或Sidekick中，即使cq：editConfig不存在也是如此。

    • cq:childEditConfig (cq:EditConfig) — 控制未定义自身cq:editConfig的子组件的作者UI方面。

    • 触屏优化UI：

      • cq:dialog (nt:unstructured) — 此组件的对话框。 定义允许用户配置组件和/或编辑内容的界面。
      • cq:design_dialog (nt:unstructured) — 正在编辑此组件的设计

    • 经典UI：

      • dialog (cq:Dialog) — 此组件的对话框。 定义允许用户配置组件和/或编辑内容的界面。
      • design_dialog (cq:Dialog) — 正在编辑此组件的设计。

触屏UI中的组件图标 component-icon-in-touch-ui

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

  1. cq:icon — 字符串属性，指向要在组件浏览器中显示的Coral UI库中的标准图标

    • 使用Coral图标的HTML属性的值。

  2. abbreviation — 用于自定义组件浏览器中组件名称的缩写的字符串属性

    • 缩写应限制为两个字符。

    • 提供空字符串将生成jcr:title属性的前两个字符的缩写。

      • 例如，“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图标示例 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类型的节点，具有以下属性和子节点：

名称
类型
描述
.
cq:Component
当前组件。 组件为节点类型cq:Component.
componentGroup
String
在组件浏览器（触屏UI）或Sidekick（经典UI）中可选择组件的组。
值.hidden用于无法从UI选择的组件，例如实际的段落系统。
cq:isContainer
Boolean
指示组件是否为容器组件，因此可以包含其他组件，例如段落系统。
cq:dialog
nt:unstructured
触屏UI的“编辑”对话框定义。
dialog
cq:Dialog
经典UI的“编辑”对话框的定义。
cq:design_dialog
nt:unstructured
触屏UI的“设计”对话框定义。
design_dialog
cq:Dialog
经典UI的设计对话框定义。
dialogPath
String
在组件没有对话框节点时用于覆盖此情况的对话框的路径。
cq:cellName
String
如果设置，此属性将被视为单元格ID。 有关详细信息，请参阅知识库文章如何生成设计单元ID。
cq:childEditConfig
cq:EditConfig
当组件是容器（例如，段落系统）时，它会驱动子节点的编辑配置。
cq:editConfig
cq:EditConfig
编辑组件的配置。
cq:htmlTag
nt:unstructured
返回添加到周围html标记的其他标记属性。 允许向自动生成的div添加属性。
cq:noDecoration
Boolean
如果为true，则组件不会使用自动生成的div和css类渲染。
cq:template
nt:unstructured
如果找到，则在从组件浏览器或Sidekick添加组件时，此节点将用作内容模板。
cq:templatePath
String
从组件浏览器或Sidekick添加组件时要用作内容模板的节点的路径。 这必须是绝对路径，而不是相对于组件节点的路径。
除非您希望重复使用在其他位置已提供的内容，否则不是必需的，cq:template就足够了（请参阅下文）。
jcr:created
Date
创建组件的日期。
jcr:description
String
组件的说明。
jcr:title
String
组件的标题。
sling:resourceSuperType
String
设置后，该组件将继承该组件。
virtual
sling:Folder
允许创建虚拟组件。 要查看示例，请查看联系人组件：
/libs/foundation/components/profile/form/contact
<breadcrumb.jsp>
nt:file
脚本文件。
icon.png
nt:file
组件图标，显示在Sidekick中的标题旁边。
thumbnail.png
nt:file
将组件从Sidekick拖动到适当位置时显示的可选缩略图。

如果查看​ Text ​组件（任一版本），您可以看到以下元素：

  • HTL (/libs/wcm/foundation/components/text)

    chlimage_1-241

  • JSP (/libs/foundation/components/text)

    screen_shot_2012-02-13at60457pm

特别感兴趣的物业包括：

  • jcr:title — 组件的标题；这可用于识别组件，例如，它显示在组件浏览器或sidekick内的组件列表中
  • jcr:description — 组件的描述；可以用作sidekick中组件列表的鼠标悬停提示
  • sling:resourceSuperType：这表示扩展组件时的继承路径（通过覆盖定义）

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

  • cq:editConfig (cq:EditConfig) — 这控制视觉方面；例如，它可以定义条形图或小部件的外观，或者可以添加自定义控件

  • cq:childEditConfig (cq:EditConfig) — 这控制没有自己的定义的子组件的可视方面

  • 触屏优化UI：

    • cq:dialog (nt:unstructured) — 定义用于编辑此组件内容的对话框
    • cq:design_dialog (nt:unstructured) — 指定此组件的设计编辑选项

  • 经典UI：

    • dialog (cq:Dialog) — 定义用于编辑此组件内容的对话框（特定于经典UI）
    • design_dialog (cq:Dialog) — 指定此组件的设计编辑选项
    • icon.png — 要用作Sidekick中组件的图标的图形文件
    • thumbnail.png — 从Sidekick拖动组件时用作组件缩略图的图形文件

对话框 dialogs

对话框是组件的关键元素，因为它们为作者提供了一个界面来配置该组件并提供输入内容。

根据组件的复杂性，您的对话框可能需要一个或多个选项卡 — 缩短对话框并对输入字段进行排序。

对话框定义特定于UI：

NOTE
  • 为兼容起见，当没有为触控式UI定义对话框时，触控式UI可以使用经典UI对话框的定义。
  • 还提供了AEM现代化工具，以帮助您扩展/转换仅具有为经典UI定义的对话框的组件。

  • 触屏优化UI

    • cq:dialog (nt:unstructured)节点：

      • 定义用于编辑此组件内容的对话框

      • 特定于触屏UI

      • 是使用Granite UI组件定义的

      • 具有属性sling:resourceType，作为标准Sling内容结构

      • 可以具有属性helpPath来定义在选择“帮助”图标（?图标）时访问的上下文相关帮助资源（绝对路径或相对路径）。

        • 对于开箱即用的组件，这通常会引用文档中的页面。
        • 如果未指定helpPath，则会显示默认URL（文档概述页面）。

    chlimage_1-242

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

    screen_shot_2012-02-13at60937pm

  • 经典 UI

    • dialog (cq:Dialog)节点

      • 定义用于编辑此组件内容的对话框

      • 特定于经典UI

      • 使用ExtJS构件定义

      • 具有引用ExtJS的属性xtype

      • 可以具有属性helpPath来定义在选择​ 帮助 ​按钮时访问的上下文相关帮助资源（绝对或相对路径）。

        • 对于开箱即用的组件，这通常会引用文档中的页面。
        • 如果未指定helpPath，则会显示默认URL（文档概述页面）。

    chlimage_1-243

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

    chlimage_1-244

    在Classic对话框中：

    • 您可以将该对话框创建为cq:Dialog，这将提供单个选项卡 — 就像在文本组件中一样；或者，如果您需要多个选项卡（就像在文本时间组件中一样），则可以将该对话框定义为cq:TabPanel。
    • cq:WidgetCollection (items)用于为输入字段(cq:Widget)或其他选项卡(cq:Widget)提供基数。 此层次结构可以扩展。

设计对话框 design-dialogs

“设计”对话框与用于编辑和配置内容的对话框类似，但它们为作者提供了用于配置和提供该组件的设计详细信息的界面。

设计对话框在设计模式下可用，但并非所有组件都需要它们，例如，标题 ​和​ 图像 ​都具有设计对话框，而​ 文本 ​没有。

段落系统的“设计”对话框（例如，parsys）是一种特殊情况，因为它允许用户在页面上选择特定的其他组件（从组件浏览器或sidekick）。

将组件添加到段落系统 adding-your-component-to-the-paragraph-system

定义组件后，必须使其可用。 要使组件可在段落系统中使用，您可以：

  1. 为页面打开设计模式并启用所需的组件。

  2. 将所需的组件添加到模板定义的components属性中：

    /etc/designs/<*yourProject*>/jcr:content/<*yourTemplate*>/par

    例如，请参阅：

    /etc/designs/geometrixx/jcr:content/contentpage/par

    chlimage_1-245

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

如果您在页面上创建和配置​ 标题 ​组件的实例： <content-path>/Prototype.html

  • 触屏优化UI

    chlimage_1-246

  • 经典 UI

    screen_shot_2012-02-01at34257pm

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

screen_shot_2012-02-13at61405pm

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

  • 定义（适用于两个UI）具有属性name= ./jcr:title

    • /libs/foundation/components/title/cq:dialog/content/items/column/items/title
    • /libs/foundation/components/title/dialog/items/title

  • 在内容中，这将生成包含作者内容的属性jcr:title。

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

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

AEM中的组件遵循三个不同的层次结构：

  • 资源类型层次结构

    用于使用属性sling:resourceSuperType扩展组件。 这将使组件能够继承。 例如，文本组件继承标准组件的各种属性。

    • 脚本（由Sling解析）
    • 对话框
    • 描述（包括缩略图图像和图标）

  • 容器层次结构

    这用于向子组件填充配置设置，并且最常用于Parsys场景。

    例如，可以在父组件上定义编辑栏按钮、控件集布局（编辑栏、变换）和对话框布局（内联、浮动）的配置设置并传播到子组件。

    cq:editConfig和cq:childEditConfig中的配置设置（与编辑功能相关）已传播。

  • 包含层次结构

    这是在运行时由include序列强制实施的。

    Designer使用此层级，该层级反过来充当呈现的各个设计方面的基础；包括布局信息、css信息、parsys中的可用组件等。

编辑行为 edit-behavior

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

尽管存在某些特定差异，但配置对于触屏优化UI和经典UI都是通用的。

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

  • cq:editConfig节点属性：

    • cq:actions (String array)：定义可以对组件执行的操作。

    • cq:layout (String)：定义如何在经典UI中编辑组件。

    • cq:dialogMode (String)：定义如何在经典UI中打开组件对话框

      • 在触屏优化UI中，对话框在桌面模式下始终处于浮动状态，并在移动设备中自动作为全屏打开。

    • cq:emptyText (String)：定义不存在可视内容时显示的文本。

    • cq:inherit (Boolean)：定义缺少的值是否从它继承的组件继承。

    • dialogLayout （字符串）：定义对话框应如何打开。

  • cq:editConfig子节点：

    • cq:dropTargets （节点类型nt:unstructured）：定义可以从内容查找器的资源中接受放置的放置目标的列表

      • 多个放置目标仅在经典UI中可用。
      • 在触屏优化UI中，允许使用单个放置目标。

    • cq:actionConfigs （节点类型nt:unstructured）：定义附加到cq：actions列表的新操作列表。

    • cq:formParameters （节点类型nt:unstructured）：定义添加到对话框表单的其他参数。

    • cq:inplaceEditing （节点类型cq:InplaceEditingConfig）：为组件定义就地编辑配置。

    • cq:listeners （节点类型cq:EditListenersConfig）：定义在组件上发生操作之前或之后发生的情况。

NOTE
在此页中，节点（属性和子节点）表示为XML，如以下示例所示。
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afteredit="REFRESH_PAGE"/>
</jcr:root>

存储库中有许多现有配置。 您可以轻松搜索特定属性或子节点：

  • 要查找cq:editConfig节点的属性，例如cq:actions，您可以在​ CRXDE Lite ​中使用查询工具，并使用以下XPath查询字符串进行搜索：

    //element(cq:editConfig, cq:EditConfig)[@cq:actions]

  • 例如，要查找cq:editConfig的子节点，可以搜索类型为cq:DropTargetConfig的cq:dropTargets；可以在中使用查询工具​ CRXDE Lite ​并使用以下XPath查询字符串进行搜索：

    //element(cq:dropTargets, cq:DropTargetConfig)

组件占位符 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-properties

cq：actions cq-actions

cq:actions属性(String array)定义了一个或多个可对组件执行的操作。 以下值可用于配置：

属性值
描述
text:<some text>
显示仅在经典UI中可见的静态文本值<some text>
。 触屏优化UI不会在上下文菜单中显示操作，因此该操作不适用。
-
添加分隔条。
仅在经典UI中可见。 触屏优化UI不会在上下文菜单中显示操作，因此该操作不适用。
edit
添加按钮以编辑组件。
editannotate
添加按钮以编辑该组件并允许注释。
delete
添加按钮以删除组件。
insert
添加按钮以在当前组件之前插入新组件。
copymove
添加按钮以复制和剪切组件。

以下配置将编辑按钮、分隔符、删除和插入按钮添加到组件编辑栏：

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit,-,delete,insert]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

以下配置将文本“从基本框架继承的配置”添加到组件编辑栏：

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[text:Inherited Configurations from Base Framework]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

cq：layout（仅限经典UI） cq-layout-classic-ui-only

cq:layout属性(String)定义如何在经典UI中编辑该组件。 可以使用以下值：

属性值
描述
rollover
默认值。 组件版本可通过单击和/或上下文菜单“在鼠标悬停时”访问。
对于高级使用，相应的客户端对象为： CQ.wcm.EditRollover。
editbar
可通过工具栏访问组件版本。
对于高级使用，相应的客户端对象为： CQ.wcm.EditBar。
auto
选项将保留在客户端代码中。
NOTE
变换和编辑栏的概念不适用于触屏优化UI。

以下配置会将编辑按钮添加到组件编辑栏：

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq：dialogMode（仅限经典UI） cq-dialogmode-classic-ui-only

该组件可以链接到“编辑”对话框。 cq:dialogMode属性(String)定义如何在经典UI中打开组件对话框。 可以使用以下值：

属性值
描述
floating
对话框浮动。
inline
（默认值）。 该对话框锚定在该组件上。
auto
如果组件宽度小于客户端CQ.themes.wcm.EditBase.INLINE_MINIMUM_WIDTH值，则该对话框为浮点型，否则为内联型。
NOTE
在触屏优化UI中，对话框在桌面模式下始终处于浮动状态，并在移动设备中自动作为全屏打开。

以下配置定义了一个带有编辑按钮的编辑栏和一个浮动对话框：

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq：emptyText cq-emptytext

cq:emptyText属性(String)定义不存在可视内容时显示的文本。 默认为： Drag components or assets here。

cq：inherit cq-inherit

cq:inherit属性(boolean)定义缺少的值是否继承自它继承的组件。 默认为false。

对话框布局 dialoglayout

dialogLayout属性定义默认情况下应如何打开对话框。

  • 值为fullscreen会在全屏中打开对话框。
  • 如果属性为空值或缺失，则默认正常打开对话框。
  • 用户始终可以在对话框中切换全屏模式。
  • 不适用于经典UI

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

cq：dropTargets cq-droptargets

cq:dropTargets节点（节点类型nt:unstructured）定义了一个放置目标列表，该列表可以接受从内容查找器拖动的资产中的放置。 它用作cq:DropTargetConfig类型的节点的集合。

NOTE
多个放置目标仅在经典UI中可用。
在触屏优化UI中，仅使用第一个目标。

cq:DropTargetConfig类型的每个子节点在组件中定义一个放置目标。 节点名称非常重要，因为它必须在JSP中使用，才能生成分配给作为有效放置目标的DOM元素的CSS类名称，如下所示：

<drop target css class> = <drag and drop prefix> +
 <node name of the drop target in the edit configuration>

<drag and drop prefix>由Java™属性定义：

com.day.cq.wcm.api.components.DropTarget.CSS_CLASS_PREFIX。

例如，类名在下载组件的JSP中定义如下
( /libs/foundation/components/download/download.jsp)，其中file是下载组件的编辑配置中的放置目标的节点名称：

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";

cq:DropTargetConfig类型的节点必须具有以下属性：

属性名称
属性值
accept
对资源mime类型应用正则表达式，以验证是否允许删除。
groups
放置目标组的数组。 每个组都必须与内容查找器扩展中定义的组类型匹配，并且组类型应附加到资产。
propertyName
有效放置后将更新的属性的名称。

以下配置是从下载组件中获取的。 它允许将media组中的任何资产（mime类型可以是任何字符串）从内容查找器拖放到组件中。 放置后，正在更新组件属性fileReference：

    <cq:dropTargets jcr:primaryType="nt:unstructured">
        <file
            jcr:primaryType="cq:DropTargetConfig"
            accept="[.*]"
            groups="[media]"
            propertyName="./fileReference"/>
    </cq:dropTargets>

cq：actionConfigs（仅限经典UI） cq-actionconfigs-classic-ui-only

cq:actionConfigs节点（节点类型nt:unstructured）定义了一个新操作列表，这些操作将附加到cq:actions属性定义的列表。 cq:actionConfigs的每个子节点通过定义构件来定义新操作。

以下示例配置定义了一个新按钮（带有用于经典UI的分隔符）：

  • 分隔符，由xtype tbseparator定义；

    • 此变量仅供经典UI使用。
    • 触屏UI会忽略此定义，因为xtype会被忽略（并且不需要使用分隔符，因为操作工具栏在触屏UI中的构造方式有所不同）。

  • 名为​ 管理注释 ​的按钮，该按钮运行处理程序函数CQ_collab_forum_openCollabAdmin()。

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
    cq:actions="[EDIT,COPYMOVE,DELETE,INSERT]"
    jcr:primaryType="cq:EditConfig">
    <cq:actionConfigs jcr:primaryType="nt:unstructured">
        <separator0
            jcr:primaryType="nt:unstructured"
            xtype="tbseparator"/>
        <manage
            jcr:primaryType="nt:unstructured"
            handler="function(){CQ_collab_forum_openCollabAdmin();}"
            text="Manage comments"/>
    </cq:actionConfigs>
</jcr:root>
NOTE
请参阅组件工具栏添加新操作，作为支持触摸的UI的示例。

cq：formParameters cq-formparameters

cq:formParameters节点（节点类型nt:unstructured）定义了添加到对话框表单的其他参数。 每个属性都映射到一个表单参数。

以下配置将名为name的参数（用值photos/primary设置）添加到对话框表单：

    <cq:formParameters
        jcr:primaryType="nt:unstructured"
        name="photos/primary"/>

cq：inplaceEditing cq-inplaceediting

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

属性名称
属性值
active
(boolean) True表示启用组件的就地编辑。
configPath
(String)编辑器配置的路径。 配置可由配置节点指定。
editorType

(String)编辑器类型。 可用的类型包括：

  • 纯文本：用于非HTML内容。
  • 标题：是一种增强的纯文本编辑器，可在编辑开始之前将图形标题转换为纯文本。 由Geometrixx标题组件使用。
  • 文本：用于HTML内容（使用富文本编辑器）。

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

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

cq：listeners cq-listeners

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

属性名称
属性值

默认值

（仅限经典UI）

beforedelete
该处理程序在组件移除之前触发。
beforeedit
处理程序在编辑组件之前触发。
beforecopy
处理程序在复制组件之前触发。
beforemove
处理程序会在移动组件之前触发。
beforeinsert
处理程序会在插入组件之前触发。
仅针对触屏UI运行。
beforechildinsert
处理程序在组件插入另一个组件（仅限容器）之前触发。
afterdelete
在删除组件后，将触发该处理程序。
REFRESH_SELF
afteredit
处理程序在编辑组件后触发。
REFRESH_SELF
aftercopy
在复制组件后，将触发处理程序。
REFRESH_SELF
afterinsert
在插入组件后，将触发处理程序。
REFRESH_INSERTED
aftermove
处理程序在组件移动后触发。
REFRESH_SELFMOVED
afterchildinsert
将组件插入另一个组件（仅限容器）后，将触发处理程序。
NOTE
REFRESH_INSERTED和REFRESH_SELFMOVED处理程序仅在经典UI中可用。
NOTE
监听器的默认值仅在经典UI中设置。
NOTE
如果有嵌套组件，则对cq:listeners节点上定义为属性的操作存在某些限制：

  • 对于嵌套组件，以下属性​ 的值必须 ​为REFRESH_PAGE： >

    • aftermove
    • aftercopy

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

afteredit = "project.customerAction"

以下示例等效于REFRESH_INSERTED配置：

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

NOTE
对于经典UI，要查看哪些参数可以在处理程序中使用，请参阅CQ.wcm.EditBar和CQ.wcm.EditRollover构件文档的before<action>和after<action>事件部分。

使用下列配置，在删除、编辑、插入或移动组件后刷新页面：

    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afterdelete="REFRESH_PAGE"
        afteredit="REFRESH_PAGE"
        afterinsert="REFRESH_PAGE"
        afterMove="REFRESH_PAGE"/>
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2