使用客户端库 using-client-side-libraries
现代网站在很大程度上依赖于由复杂的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。
<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文件中的源文件。
有关特定于小组件的客户端库要求的信息,请参阅使用和扩展小组件。
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
下方。
/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
引用图像
/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
客户端库:
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可以定义要使用的处理器
用途 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库管理器。