在AEM as a Cloud Service上使用客户端库 using-client-side-libraries

数字体验在很大程度上依赖于由复杂的JavaScript和CSS代码驱动的客户端处理。 AEM客户端库(clientlibs)允许您在存储库中组织和集中存储这些客户端库。 结合AEM项目原型中的前端构建过程，可以轻松管理AEM项目的前端代码。

在AEM中使用clientlibs的优点包括：

Clientlibs是内置解决方案，用于从AEM提供CSS和JavaScript。

什么是客户端库 what-are-clientlibs

站点需要在客户端处理JavaScript和CSS以及静态资源，例如图标和Web字体。 clientlib是AEM的机制，用于引用（如有必要，按类别分类）并为此类资源提供服务。

AEM将站点的CSS和JavaScript收集到一个位于中心位置的文件中，以确保HTML输出中仅包含任何资源的一个副本。 这样可以最大限度地提高交付效率，并通过代理在存储库中集中维护此类资源，从而确保访问安全。

AEM as a Cloud Service的前端开发 fed-for-aemaacs

所有JavaScript、CSS和其他前端资源都应在AEM项目原型的ui.frontend模块中进行维护。原型的灵活性允许您使用所选择的现代Web工具来创建和管理这些资源。

然后，原型可以将资源编译为单个CSS和JS文件，并将它们自动嵌入存储库中的cq:clientLibraryFolder中。

客户端库文件夹结构 clientlib-folders

客户端库文件夹是cq:ClientLibraryFolder类型的存储库节点。 CND表示法中的定义为

[cq:ClientLibraryFolder] > sling:Folder
  - dependencies (string) multiple
  - categories (string) multiple
  - embed (string) multiple
  - channels (string) multiple

每个cq:ClientLibraryFolder都填充了一组JS和/或CSS文件以及几个支持文件（见下文）。 cq:ClientLibraryFolder的重要属性配置如下：

如果client library文件夹包含一个或多个源文件，则在运行时这些文件将合并到单个JS和/或CSS文件中。 生成的文件的名称是具有.js或.css文件扩展名的节点名称。 例如，名为cq.jquery的库节点会生成名为cq.jquery.js或cq.jquery.css的文件。

客户端库文件夹包含以下项目：

创建客户端库文件夹 creating-clientlib-folders

客户端库必须位于/apps下。 此规则是更好地将代码与内容和配置隔离所必需的。

为了能够访问/apps下的客户端库，使用了代理servelt。 仍在客户端库文件夹上强制执行ACL，但如果allowProxy属性设置为true，则servlet允许通过/etc.clientlibs/读取内容。

为客户端库提供服务 serving-clientlibs

在根据需要配置您的客户端库文件夹后，可以通过代理请求您的clientlibs。 例如：

allowProxy属性允许您请求：

通过HTL加载客户端库 loading-via-htl

成功将clientlibs存储和管理在其客户端库文件夹中后，可以通过HTL访问它们。

客户端库是通过AEM提供的帮助程序模板加载的，可通过data-sly-use访问该模板。 帮助程序模板在此文件中可用，可通过data-sly-call调用这些模板。

每个帮助程序模板都需要一个 categories 选项来引用所需的客户端库。该选项可以是字符串值的数组，也可以是包含逗号分隔值列表的字符串。

有关通过HTL加载clientlibs的更多详细信息，请参阅HTL文档。

创作实例与Publish上的客户端库 clientlibs-author-publish

AEM发布实例上需要大多数clientlibs。 也就是说，大多数clientlibs的目的是生成内容的最终用户体验。 对于发布实例上的clientlibs，前端生成工具可以通过客户端库文件夹使用和部署，如上所述。

但是，有时可能需要使用客户端库来自定义创作体验。 例如，自定义对话框可能需要将少量CSS或JS部署到AEM创作实例。

管理有关作者的客户端库 clientlibs-on-author

如果您需要在创作中使用客户端库，则可以使用与发布相同的方法在/apps下创建客户端库，但直接在/apps/.../clientlibs/foo下写入客户端库，而不是创建整个项目来管理它。

然后，您可以通过将客户端库添加到现成的客户端库类别来“挂接”到创作JS中。

调试工具 debugging-tools

AEM提供了几种用于调试和测试客户端库文件夹的工具。

发现客户端库 discover-client-libraries

/libs/cq/granite/components/dumplibs/dumplibs组件生成系统上所有客户端库文件夹的信息页面。 /libs/granite/ui/content/dumplibs节点将组件作为资源类型。 要打开该页面，请使用以下URL（根据需要更改主机和端口）：

https://<host>:<port>/libs/granite/ui/content/dumplibs.test.html

该信息包括库路径和类型（CSS或JS）以及库属性的值（如类别和依赖项）。 页面上的后续表将显示每个类别和渠道中的库。

查看生成的输出 see-generated-output

dumplibs组件包括一个测试选择器，该选择器显示为ui:includeClientLib标记生成的源代码。 该页面包含用于不同js、css和主题属性组合的代码。

其他客户端库文件夹功能 additional-features

AEM中的客户端库文件夹支持其他一些功能。 但是，AEM as a Cloud Service上不需要这些变量，因此建议不要使用这些变量。 为了完整起见，此处列出了它们。

AdobeGraniteHTML库管理器 html-library-manager

其他客户端库设置可以通过位于https://<host>:<port>/system/console/configMgr的系统控制台的​ AdobeGraniteHTML库管理器 ​面板进行控制。

其他文件夹属性 additional-folder-properties

其他文件夹属性包括允许控制依赖项和嵌入，但通常不再需要这些属性，因此建议不要使用这些属性：

链接到依赖项 linking-to-dependencies

当客户端库文件夹中的代码引用其他库时，将其他库标识为依赖项。 引用您的客户端库文件夹的ui:includeClientLib标记会导致HTML代码包含指向生成的库文件和依赖项的链接。

依赖项必须是另一个cq:ClientLibraryFolder。 要识别依赖关系，请使用以下属性向您的cq:ClientLibraryFolder节点添加属性：

例如，/etc/clientlibs/myclientlibs/publicmain依赖于cq.jquery库。 引用主客户端库的页面会生成包含以下代码的HTML：

<script src="/etc/clientlibs/foundation/cq.jquery.js" type="text/javascript">
<script src="/etc/clientlibs/mylibs/publicmain.js" type="text/javascript">

嵌入来自其他库的代码 embedding-code-from-other-libraries

您可以将来自客户端库的代码嵌入到另一个客户端库中。 在运行时，生成的嵌入库的JS和CSS文件包含嵌入库的代码。

嵌入代码可用于提供对存储在存储库安全区域中的库的访问权限。

特定于应用程序的客户端库文件夹 app-specific-client-library-folders

最佳做法是将应用程序文件夹中所有与应用程序相关的文件保留在/apps以下。 拒绝网站访客访问/apps文件夹也是最佳实践。 为满足这两个最佳实践，请在/etc文件夹下创建一个客户端库文件夹，该文件夹嵌入了/apps下的客户端库。

使用类别属性可标识要嵌入的客户端库文件夹。 要嵌入库，请使用以下属性将属性添加到嵌入cq:ClientLibraryFolder节点：

使用嵌入以最大限度地减少请求 using-embedding-to-minimize-requests

在某些情况下，您可能会发现发布实例为典型页面生成的最终HTML包含相对大量的<script>元素。

在这种情况下，有必要将所有所需的客户端库代码合并到单个文件中，以便减少页面加载上的来回请求数量。 为此，您可以使用cq:ClientLibraryFolder节点的嵌入属性，将所需的库embed到特定于应用程序的客户端库中。

CSS文件中的路径 paths-in-css-files

嵌入CSS文件时，生成的CSS代码使用相对于嵌入库的资源路径。 例如，可公开访问的库/etc/client/libraries/myclientlibs/publicmain嵌入了/apps/myapp/clientlib客户端库：

main.css文件包含以下样式：

body {
  padding: 0;
  margin: 0;
  background: url(images/bg-full.jpg) no-repeat center top;
  width: 100%;
}

publicmain节点生成的CSS文件包含以下样式（使用原始图像的URL）：

body {
  padding: 0;
  margin: 0;
  background: url(../../../apps/myapp/clientlib/styles/images/bg-full.jpg) no-repeat center top;
  width: 100%;
}

请参阅HTML输出中的嵌入式文件 see-embedded-files

要跟踪嵌入代码的来源，或确保嵌入的客户端库产生预期的结果，您可以查看运行时嵌入的文件的名称。 要查看文件名，请将debugClientLibs=true参数附加到网页的URL。 生成的库包含@import语句，而不是嵌入的代码。

在上一个嵌入来自其他库的代码部分的示例中，/etc/client/libraries/myclientlibs/publicmain客户端库文件夹嵌入了/apps/myapp/clientlib客户端库文件夹。 将参数附加到网页会在网页的源代码中生成以下链接：

<link rel="stylesheet" href="/etc/clientlibs/mycientlibs/publicmain.css">

打开publicmain.css文件将显示以下代码：

@import url("/apps/myapp/clientlib/styles/main.css");

使用预处理器 using-preprocessors

AEM允许可插拔预处理器，并且为CSS和JavaScript提供了YUI Compressor支持，为JavaScript提供了Google Closure Compiler (GCC)支持，并将YUI设置为AEM的默认预处理器。

可插拔预处理器允许灵活使用，包括：

用途 usage

您可以选择为每个客户端库或系统范围配置预处理器配置。

clientlib节点上的预处理器配置优先于OSGI配置。

格式和示例 format-and-examples

格式 format

config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;

用于CSS缩小和GCC用于JS的YUI压缩器 yui-compressor-for-css-minification-and-gcc-for-js

cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]

使用Typescript进行预处理，然后使用GCC进行缩小和模糊处理 typescript-to-preprocess-and-then-gcc-to-minify-and-obfuscate

jsProcessor: [
   "default:typescript",
   "min:typescript",
   "min:gcc;obfuscate=true"
]

其他GCC选项 additional-gcc-options

failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")

有关GCC选项的更多详细信息，请参阅GCC文档。

设置系统默认缩小器 set-system-default-minifier

在AEM中，YUI被设置为默认小型化器。 要将其更改为GCC，请执行以下步骤。