SPA Blueprint

要使作者能够使用AEM SPA编辑器编辑SPA的内容，SPA必须满足一些要求。

简介

本文档描述了为了在AEM中实施可编辑的SPA组件，任何AEM框架都应该履行的一般合同(即SPA支持层的类型)。

要使作者能够使用AEM页面编辑器编辑单页应用程序框架公开的数据，项目必须能够解释模型的结构，该模型表示为AEM存储库中的应用程序存储的数据的语义。为实现此目标，提供了两个与框架无关的库： PageModelManager 和 ComponentMapping.

注意

以下要求与框架无关。如果满足这些要求，则可以提供由模块、组件和服务组成的框架特定层。

AEM中的React和Angular框架已满足这些要求。 仅当您希望实施其他框架以与AEM一起使用时，此Blueprint中的要求才相关。

注意

尽管AEM的SPA功能与框架无关，但目前仅支持React和Angular框架。

PageModelManager

此 PageModelManager 库作为NPM包提供，将由SPA项目使用。它与SPA配合使用，用作数据模型管理器。

它代表SPA抽象出代表实际内容结构的JSON结构的检索和管理。它还负责与SPA同步，以告知何时必须重新渲染其组件。

请参阅NPM包 @adobe/aem-spa-model-manager

初始化时 PageModelManager时，库会首先加载提供的应用程序根模型（通过参数、元属性或当前URL）。如果库标识当前页面的模型不是它获取的根模型的一部分，并包含它作为子页面的模型。

页面模型合并

组件映射

此 ComponentMapping 模块作为NPM包提供给前端项目。它存储前端组件，并为SPA提供一种将前端组件映射到AEM资源类型的方法。这可以在分析应用程序的JSON模型时启用组件的动态分辨率。

模型中显示的每个项目都包含 :type 公开AEM资源类型的字段。安装后，前端组件可以使用从基础库收到的模型片段来渲染自身。

对组件映射进行动态建模

有关如何在Javascript SPA SDK for AEM中发生动态模型到组件映射的详细信息，请参阅文章 SPA的动态模型到组件映射.

特定于Framework的层

必须为每个前端框架实施第三层。第三个库负责与底层库交互，并提供一系列集成良好且易于使用的入口点以便与数据模型交互。

本文档的其余部分描述了此中间框架特定层的要求，并渴望独立于框架。通过满足以下要求，可以为项目组件提供特定于框架的层，以便与负责管理数据模型的底层库交互。

一般概念

页面模型

页面的内容结构存储在AEM中。页面模型用于映射和实例化SPA组件。 SPA开发人员创建SPA组件，并将其映射到AEM组件。为此，它们使用资源类型(或AEM组件的路径)作为唯一键。

SPA组件必须与页面模型同步，并根据对内容所做的任何更改进行更新。必须使用利用动态组件的模式来按照提供的页面模型结构即时实例化组件。

元字段

页面模型利用JSON模型导出器，它本身基于 Sling模型 API。可导出的sling模型显示以下字段列表，以便启用基础库解释数据模型：

:type：AEM资源的类型（默认为资源类型）
:children：当前资源的层级子级。子项不是当前资源的内部内容的一部分（可以在表示页面的项上找到）
:hierarchyType：资源的分层类型。此 PageModelManager 当前支持页面类型
:items：当前资源的子内容资源（嵌套结构，仅存在于容器上）
:itemsOrder：子项的有序列表。 JSON映射对象不保证其字段的顺序。通过同时具有映射和当前数组，API的使用者可以同时获得两种结构的好处
:path：项目的内容路径（显示在表示页面的项目上）

另请参阅 AEM Content Services入门。

特定于框架的模块

区分关注点有助于促进项目实施。因此，应提供特定于npm的软件包。此资源包负责聚合和公开基本模块、服务和组件。这些组件必须封装数据模型管理逻辑，并提供对项目组件所预期数据的访问。该模块还负责可传递地公开基础库的有用入口点。

为便于实现库的互操作性，Adobe建议框架特定模块捆绑以下库。如有必要，该层可以在将底层API公开给项目之前对其进行封装和调整。

实施

React

npm模块： @adobe/aem-react-editable-components

angular

npm模块： @adobe/aem-angular-editable-components

主要服务和组件

应根据每个框架的具体准则实施以下实体。基于框架架构，实现方式可能大不相同，但必须提供描述的功能。

模型提供程序

项目组件必须将模型片段的访问权限委派给模型提供程序。然后，模型提供程序负责侦听对模型的指定片段所做的更改，并将更新的模型返回到委托组件。

为此，模型提供程序必须注册到 PageModelManager. 然后，当发生更改时，它会接收更新后的数据，并将其传递到委托组件。按照惯例，提供给将承载模型片段的委托组件的属性被命名为 cqModel. 实施可以免费为组件提供此属性，但应考虑与框架架构集成、可发现性和易用性等方面。

组件HTML装饰器

组件修饰器负责使用页面编辑器所需的一系列数据属性和类名来修饰每个组件实例的元素的外部HTML。

组件声明

必须将以下元数据添加到项目组件生成的外部HTML元素中。它们使页面编辑器能够检索相应的编辑配置。

data-cq-data-path：相对于的资源的路径 jcr:content

编辑功能声明和占位符

必须将以下元数据和类名添加到项目组件生成的外部HTML元素中。它们使页面编辑器能够提供相关功能。

cq-placeholder：标识空组件的占位符的类名称
data-emptytext：组件实例为空时叠加显示的标签

空组件的占位符

每个组件都必须扩展，而且当组件被标识为空时，都必须使用特定于占位符和相关叠加的数据属性和类名来装饰外部HTML元素。

关于组件的空性

该组件在逻辑上是否为空？
组件为空时，叠加图应显示什么标签？

容器

容器是指用于包含和渲染子组件的组件。为此，容器在 :itemsOrder， :items 和 :children 模型的属性。

容器从的存储中动态获取子组件 ComponentMapping 库。然后，容器使用模型提供程序功能扩展子组件，最后实例化它。

页面

此 Page 组件扩展 Container 组件。容器是一个组件，旨在包含和渲染子组件，包括子页面。为此，容器在 :itemsOrder， :items、和 :children 模型的属性。此 Page 组件从的存储中动态获取子组件 ComponentMapping 库。此 Page 负责实例化子组件。

响应式网格

响应式网格组件是一个容器。它包含模型提供程序的特定变体，该变体表示其列。响应式网格及其列负责使用模型中包含的特定类名装饰项目组件的外部HTML元素。

响应式网格组件应该预先映射到其AEM对应组件，因为该组件比较复杂，很少进行自定义。

特定模型字段

gridClassNames: 为响应式网格提供的类名
columnClassNames: 为响应列提供了类名

另请参阅npm资源 @adobe/aem-react-editable-components

响应式网格的占位符

SPA组件将映射到图形容器（如响应式网格），并且必须在创作内容时添加虚拟子占位符。当页面编辑器创作SPA的内容时，该内容会使用iframe和 data-cq-editor 属性将添加到该内容的文档节点中。当 data-cq-editor 属性存在，则容器必须包含一个HTMLElement以表示在将新组件插入页面时作者与之交互的区域。

例如：

<div data-cq-data-path={"path/to/the/responsivegrid/*"} className="new section aem-Grid-newComponent"/>

注意

该示例中使用的类名当前是页面编辑器所必需的。

"new section"：指示当前元素是容器的占位符
"aem-Grid-newComponent"：标准化布局创作的组件

组件映射

基础 Component Mapping 库及其 MapTo 可以封装和扩展函数，以提供与当前组件类一起提供的编辑配置相关的功能。

const EditConfig = {

    emptyLabel: 'My Component',

    isEmpty: function() {
        return !this.props || !this.props.cqModel || this.props.cqModel.isEmpty;
    }
};

class MyComponent extends Component {

    render() {
        return <div className={'my-component'}></div>;
    }
}

MapTo('component/resource/path')(MyComponent, EditConfig);

在上述实施中，项目组件在中实际注册之前，通过空值功能进行了扩展组件映射商店。这是通过封装和扩展 ComponentMapping 库以介绍 EditConfig 配置对象：

/**
 * Configuration object in charge of providing the necessary data expected by the page editor to initiate the authoring. The provided data will be decorating the associated component
 *
 * @typedef {{}} EditConfig
 * @property {String} [dragDropName]       If defined, adds a specific class name enabling the drag and drop functionality
 * @property {String} emptyLabel           Label to be displayed by the placeholder when the component is empty. Optionally returns an empty text value
 * @property {function} isEmpty            Should the component be considered empty. The function is called using the context of the wrapper component giving you access to the component model
 */

/**
 * Map a React component with the given resource types. If an {@link EditConfig} is provided the <i>clazz</i> is wrapped to provide edition capabilities on the AEM Page Editor
 *
 * @param {string[]} resourceTypes                      - List of resource types for which to use the given <i>clazz</i>
 * @param {class} clazz                                 - Class to be instantiated for the given resource types
 * @param {EditConfig} [editConfig]                     - Configuration object for enabling the edition capabilities
 * @returns {class}                                     - The resulting decorated Class
 */
ComponentMapping.map = function map (resourceTypes, clazz, editConfig) {};

与页面编辑器签订合同

项目组件必须至少生成以下数据属性，才能让编辑器与它们交互。

data-cq-data-path：组件提供的相对路径 PageModel (例如， "root/responsivegrid/image")。不应将此属性添加到页面。

总之，要由页面编辑器解释为可编辑，项目组件必须遵循以下合同：

提供将前端组件实例与AEM资源关联的预期属性。
提供允许创建空占位符的预期属性和类名系列。
提供允许拖放资产的预期类名。

典型HTML元素结构

以下片段说明了页面HTML结构的典型内容表示形式。以下是一些要点：

响应式网格元素带有带有前缀的类名称 aem-Grid--
响应列元素具有前缀为的类名 aem-GridColumn--
响应式网格（也是父网格的列）被包住，例如前两个前缀未出现在同一元素上
与可编辑资源对应的元素带有 data-cq-data-path 属性。请参阅与页面编辑器签订合同章节。

<div data-cq-data-path="/content/page">
    <div class="aem-Grid aem-Grid--12 aem-Grid--default--12">
        <div class="aem-container aem-GridColumn aem-GridColumn--default--12" data-cq-data-path="/content/page/jcr:content/root/responsivegrid">
            <div class="aem-Grid aem-Grid--12 aem-Grid--default--12">
                <div class="cmp-image cq-dd-image aem-GridColumn aem-GridColumn--default--12" data-cq-data-path="/root/responsivegrid/image">
                    <img src="/content/we-retail-spa-sample/react/jcr%3acontent/root/responsivegrid/image.img.jpeg/1512113734019.jpeg">
                </div>
            </div>
        </div>
    </div>
</div>

应用程序拥有路由。前端开发人员首先需要实施导航组件(映射到AEM导航组件)。此组件将渲染要与一系列显示或隐藏内容片段的路由一起使用的URL链接。

基础 PageModelManager 库及其 ModelRouter 模块（默认启用）负责预获取并提供对与给定资源路径关联的模型的访问。

这两个图元与路由的概念有关，但 ModelRouter 仅负责加载 PageModelManager 数据模型的结构与当前应用程序状态同步。

请参阅文章 SPA模型路由了解更多信息。

SPA的实际操作

通过继续阅读以下文档，了解简单的SPA如何工作并自行试验SPA：

深入阅读

有关AEM中SPA的更多信息，请参阅以下文档：

SPA编辑器概述有关AEM中的SPA和通信模型的概述

SPA Blueprint

简介

PageModelManager

组件映射

对组件映射进行动态建模

特定于Framework的层

一般概念

页面模型

元字段

特定于框架的模块

实施

React

angular

主要服务和组件

模型提供程序

组件HTML装饰器

组件声明

编辑功能声明和占位符

容器

页面

响应式网格

特定模型字段

响应式网格的占位符

组件映射

与页面编辑器签订合同

典型HTML元素结构

导航和路由

SPA的实际操作

深入阅读

Business.Adobe.com 资源

在此页面上

查看下一个：

学习

文档

社区

技术支持

资源

Adobe 帐户

Adobe