使用客户端库 using-client-side-libraries

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

主题：

创建对象：

开发人员

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

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

客户端库在AEM中的工作原理 how-client-side-libraries-work-in-aem

在页面HTML中包含客户端库（即JS或CSS文件）的标准方法是，在该页面的JSP中包含<script>或<link>标记，并包含相关文件的路径。例如，

...
<head>
   ...
   <script type="text/javascript" src="/etc/clientlibs/granite/jquery/source/1.8.1/jquery-1.8.1.js"></script>
   ...
</head>
...

虽然这种方法在AEM中起作用，但当页面及其组成组件变得复杂时，它可能会导致问题。在这种情况下，最终HTML输出中可能会包含同一JS库的多个副本。为避免这种情况并允许对客户端库进行逻辑组织，AEM使用 客户端库文件夹。

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

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

默认情况下，cq:ClientLibraryFolder节点可以放置在存储库的/apps、/libs和/etc子树中的任意位置(这些默认值和其他设置可通过Adobe控制台的 GraniteHTML库管理器 面板进行控制)。

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

categories：标识此cq:ClientLibraryFolder内的JS和/或CSS文件集所属的类别。 categories属性是多值属性，它允许库文件夹成为多个类别的一部分（请参阅下面的内容，了解其用处）。
dependencies：这是此库文件夹所依赖的其他客户端库类别的列表。例如，在给定两个cq:ClientLibraryFolder节点F和G的情况下，如果F中的某个文件需要G中的另一个文件才能正常工作，则G的categories中至少有一个应属于F的dependencies中。
embed：用于嵌入来自其他库的代码。如果节点F嵌入了节点G和H，则得到的HTML将是来自节点G和H的内容集。
allowProxy：如果客户端库位于/apps下，则此属性允许通过代理servlet访问它。请参阅下面的查找客户端库文件夹并使用代理客户端库Servlet。

引用客户端库 referencing-client-side-libraries

由于HTL是开发AEM站点的首选技术，因此应使用HTL在AEM中包含客户端库。但是，也可以使用JSP执行此操作。

使用HTL using-htl

在HTL中，通过AEM提供的帮助程序模板来加载客户端库，可通过data-sly-use访问该模板。此文件中有三个可用的模板，可以通过data-sly-call来调用它们：

css — 仅加载引用的客户端库的CSS文件。
js — 仅加载引用的客户端库的JavaScript文件。
all — 加载引用的客户端库的所有文件(CSS和JavaScript)。

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

有关详细信息和使用示例，请参阅文档HTML模板语言快速入门。

使用JSP using-jsp

将ui:includeClientLib标记添加到您的JSP代码中，以在生成的HTML页面中添加指向客户端库的链接。要引用库，请使用ui:includeClientLib节点的categories属性的值。

<%@taglib prefix="ui" uri="https://www.adobe.com/taglibs/granite/ui/1.0" %>
<ui:includeClientLib categories="<%= categories %>" />

例如，/etc/clientlibs/foundation/jquery节点的类型为cq:ClientLibraryFolder，类别属性的值为cq.jquery。 JSP文件中的以下代码引用了库：

<ui:includeClientLib categories="cq.jquery"/>

生成的HTML页包含以下代码：

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

有关完整信息，包括筛选JS、CSS或主题库的属性，请参阅ui：includeClientLib。

CAUTION

<cq:includeClientLib>过去通常用于包含客户端库，但自AEM 5.6之后已弃用。应改用<ui:includeClientLib>，如上所述。

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

创建一个cq:ClientLibraryFolder节点以定义JavaScript和层叠样式表库并将它们用于HTML页。使用节点的categories属性标识它所属的库类别。

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

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

要合并的JS和/或CSS源文件。
支持CSS样式的资源，如图像文件。

注意： 您可以使用子文件夹来组织源文件。
一个js.txt文件和/或一个css.txt文件，用于标识要合并到生成的JS和/或CSS文件中的源文件。

clientlibarch

有关特定于小组件的客户端库要求的信息，请参阅使用和扩展小组件。

Web客户端必须具有访问cq:ClientLibraryFolder节点的权限。您还可以从存储库的安全区域公开库（请参阅下面的嵌入其他库的代码）。

覆盖/lib中的库 overriding-libraries-in-lib

位于/apps下方的客户端库文件夹优先于/libs中类似的同名文件夹。例如，/apps/cq/ui/widgets优先于/libs/cq/ui/widgets。当这些库属于同一类别时，将使用/apps以下的库。

查找客户端库文件夹并使用代理客户端库Servlet locating-a-client-library-folder-and-using-the-proxy-client-libraries-servlet

在以前的版本中，客户端库文件夹位于存储库中的/etc/clientlibs下方。这仍受支持，但建议客户端库现在位于/apps下。这是为了在其他脚本附近找到客户端库，这些脚本通常位于/apps和/libs下方。

NOTE

客户端库文件夹下的静态资源必须位于名为 resources 的文件夹中。如果文件夹资源下没有静态资源（如图像），则无法在发布实例上引用该资源。示例如下： https://localhost:4503/etc.clientlibs/geometrixx/components/clientlibs/resources/example.gif

NOTE

为了更好地将代码与内容和配置隔离，建议在/apps下找到客户端库，并使用allowProxy属性通过/etc.clientlibs公开它们。

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

如果静态资源位于客户端库文件夹下的资源下，则只能通过代理访问。

例如：

您在/apps/myproject/clientlibs/foo中有一个clientlib
您在/apps/myprojects/clientlibs/foo/resources/icon.png中有一个静态图像

然后，将foo上的allowProxy属性设置为true。

然后，您可以请求/etc.clientlibs/myprojects/clientlibs/foo.js
然后，您可以通过/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png引用图像

CAUTION

使用代理的客户端库时，AEM Dispatcher配置可能需要更新，以确保允许使用扩展客户端库的URI。

CAUTION

Adobe建议查找/apps下的客户端库，并使用代理servlet使其可用。但是，请记住，最佳做法仍然要求公共站点从不包含直接通过/apps或/libs路径提供的任何内容。

创建客户端库文件夹 create-a-client-library-folder

在Web浏览器(https://localhost:4502/crx/de)中打开CRXDE Lite。
选择要在其中找到客户端库文件夹的文件夹，然后单击 创建>创建节点。
输入库文件的名称，然后在类型列表中选择cq:ClientLibraryFolder。单击确定，然后单击 全部保存。
要指定库所属的类别，请选择cq:ClientLibraryFolder节点，添加以下属性，然后单击 全部保存：
- 名称：类别
- 类型：字符串
- 值：类别名称
- 多：选择
以任何方式将源文件添加到库文件夹中。例如，使用WebDav客户端复制文件，或创建文件并手动创作内容。

注意： 如果需要，您可以在子文件夹中组织源文件。
选择客户端库文件夹，然后单击 创建>创建文件。
在“文件名”框中，键入以下文件名之一，然后单击“确定”：
- js.txt： 使用此文件名生成JavaScript文件。
- css.txt： 使用此文件名生成层叠样式表。
打开文件并键入以下文本以标识源文件路径的根：

#base=*[root]*

将* [root]*替换为包含源文件的文件夹相对于TXT文件的路径。例如，当源文件与TXT文件位于同一文件夹时，请使用以下文本：

#base=.

以下代码将根设置为cq:ClientLibraryFolder节点下名为mobile的文件夹：

#base=mobile
在#base=[root]下面的行中，键入源文件相对于根的路径。将每个文件名放在单独的一行中。
单击 全部保存。

链接到依赖项 linking-to-dependencies

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

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

名称： 依赖项
类型： 字符串[]
值：当前库文件夹所依赖的cq：ClientLibraryFolder节点的categories属性值。

例如，/ etc/clientlibs/myclientlibs/publicmain依赖于cq.jquery库。引用主客户端库的JSP会生成包含以下代码的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文件夹也是最佳实践。为满足这两个最佳实践，请在/apps下创建一个客户端库文件夹，并使其可通过查找客户端库文件夹和使用代理客户端库Servlet中所述的代理servlet访问。

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

名称： 已嵌入
类型： 字符串[]
值：要嵌入的cq:ClientLibraryFolder节点的categories属性值。

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

在某些情况下，您可能会发现发布实例为典型页面生成的最终HTML包含相对大量的<script>元素，特别是当您的网站正在使用客户端上下文信息进行分析或定位时。例如，在非优化项目中，您可能会在页面的HTML中找到以下一系列<script>元素：

<script type="text/javascript" src="/etc/clientlibs/granite/jquery.js"></script>
<script type="text/javascript" src="/etc/clientlibs/granite/utils.js"></script>
<script type="text/javascript" src="/etc/clientlibs/granite/jquery/granite.js"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/jquery.js"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/shared.js"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/personalization/kernel.js"></script>

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

AEM中包含以下客户端库类别。您应该仅嵌入运行特定站点所需的那些项目。但是，您应该保持此处列出的顺序：

browsermap.standard
browsermap
jquery-ui
cq.jquery.ui
personalization
personalization.core
personalization.core.kernel
personalization.clientcontext.kernel
personalization.stores.kernel
personalization.kernel
personalization.clientcontext
personalization.stores
cq.collab.comments
cq.collab.feedlink
cq.collab.ratings
cq.collab.toggle
cq.collab.forum
cq.cleditor

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

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

screen_shot_2012-05-29at20122pm

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%;
}

将库用于特定移动组 using-a-library-for-specific-mobile-groups

使用客户端库文件夹的channels属性来标识使用该库的移动组。当针对不同的设备功能设计相同类别的库时，channels属性非常有用。

要将客户端库文件夹与设备组关联，请将具有以下属性的属性添加到您的cq:ClientLibraryFolder节点：

名称： 个频道
类型： 字符串[]
值：移动组的名称。要从组中排除库文件夹，请在名称前面添加感叹号(“！”)。

例如，下表列出了cq.widgets类别中每个客户端库文件夹的channels属性的值：

客户端库文件夹

渠道属性的值

/libs/cq/analytics/widgets

!touch

/libs/cq/analytics/widgets/themes/default

!touch

/libs/cq/cloudserviceconfigs/widgets

!touch

/libs/cq/touch/widgets

touch

/libs/cq/touch/widgets/themes/default

touch

/libs/cq/ui/widgets

!touch

/libs/cq/ui/widgets/themes/default

!touch

使用预处理器 using-preprocessors

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

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

定义可以处理脚本源的ScriptProcessors
处理器可通过选项进行配置
处理器可用于缩小，也可用于非缩小情况
clientlib可以定义要使用的处理器

NOTE

默认情况下，AEM使用YUI压缩程序。有关已知问题的列表，请参阅YUI压缩程序GitHub文档。为特定clientlibs切换到GCC压缩程序可以解决使用YUI时观察到的一些问题。

CAUTION

请勿将缩小的库放置在客户端库中。而是提供原始库，如果需要缩小，请使用预处理器的选项。

用途 usage

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

在clientlibrary节点上添加多值属性cssProcessor和jsProcessor
或通过 HTML库管理器 OSGi配置定义系统默认配置

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，请执行以下步骤。

转到https://localhost:4502/system/console/configMgr上的Apache Felix配置管理器
查找并编辑 AdobeGraniteHTML库管理器。
启用 最小化 选项（如果尚未启用）。
将 JS处理器默认配置 的值设置为min:gcc。

如果用分号分隔，例如min:gcc;obfuscate=true，则可以传递选项。
单击保存以保存更改。

调试工具 debugging-tools

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

请参阅嵌入的文件 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");

在Web浏览器的地址框中，将以下文本附加到HTML的URL：

?debugClientLibs=true
加载页面时，查看页面源。
单击提供为链接元素的href链接，以打开文件并查看源代码。

发现客户端库 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和主题属性组合的代码。

使用以下方法之一打开“测试输出”页：
- 从dumplibs.html页面，单击 单击此处进行输出测试 文本中的链接。
- 在Web浏览器中打开以下URL（根据需要使用不同的主机和端口）：
  - http://<host>:<port>/libs/granite/ui/content/dumplibs.html
默认页面显示没有categories属性值的标记的输出。
要查看类别的输出，请键入客户端库的categories属性的值，然后单击 提交查询。

配置用于开发和生产的库处理 configuring-library-handling-for-development-and-production

HTML库管理器服务在运行时处理cq:ClientLibraryFolder标记并生成库。环境、开发或生产的类型决定了应如何配置服务：

提高安全性：禁用调试
提高性能：删除空白并压缩库。
提高可读性：包含空格而不压缩。

有关配置服务的信息，请参阅AEMHTML库管理器。

recommendation-more-help

19ffd973-7af2-44d0-84b5-d547b0dffee2