使用客户端库 using-client-side-libraries
现代网站在很大程度上依赖于由复杂的JavaScript和CSS代码驱动的客户端处理。 组织和优化此代码的服务可能是一个复杂的问题。
为了帮助解决此问题,AEM提供了 客户端库文件夹,可将客户端代码存储在存储库中,按类别组织代码,并定义何时以及如何向客户端提供每种类别的代码。 然后,客户端库系统负责在最终网页中产生正确的链接,以加载正确的代码。
客户端库在AEM中的工作原理 how-client-side-libraries-work-in-aem
在页面的HTML中包含客户端库(即JS或CSS文件)的标准方法只是包含 <script>
或 <link>
页面的JSP中的标记,其中包含相关文件的路径。 例如,
...
<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
存储库的子树(这些默认设置和其他设置可通过 AdobeGraniteHTML库管理器 面板 系统控制台)。
每个 cq:ClientLibraryFolder
使用一组JS和/或CSS文件以及几个支持文件(见下文)填充。 的属性 cq:ClientLibraryFolder
配置如下:
-
categories
:标识此JS和/或CSS文件集所属的类别cq:ClientLibraryFolder
摔倒。 此categories
属性是多值属性,允许库文件夹属于多个类别(请参阅下方以了解其用处)。 -
dependencies
:这是此库文件夹所依赖的其他客户端库类别的列表。 例如,给定两个cq:ClientLibraryFolder
节点F
和G
,如果文件位于F
需要另一个文件G
以正常运行,则categories
之G
应该属于dependencies
之F
. -
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文件。
- 所有 — 加载引用的客户端库的所有文件(CSS和JavaScript)。
每个帮助程序模板都需要一个 categories
选项来引用所需的客户端库。该选项可以是字符串值的数组,也可以是包含逗号分隔值列表的字符串。
有关更多详细信息和使用示例,请参阅文档 HTML模板语言快速入门.
使用JSP using-jsp
添加 ui:includeClientLib
标记到JSP代码,以在生成的HTML页面中添加指向客户端库的链接。 要引用库,请使用 categories
的属性 ui:includeClientLib
节点。
<%@taglib prefix="ui" uri="https://www.adobe.com/taglibs/granite/ui/1.0" %>
<ui:includeClientLib categories="<%= categories %>" />
例如, /etc/clientlibs/foundation/jquery
节点属于类型 cq:ClientLibraryFolder
具有value的categories属性 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
并通过以下方式揭发他们 /etc.clientlibs
通过使用 allowProxy
属性。对于下的客户端库 /apps
要访问,将使用代理servelt。 仍会在客户端库文件夹上强制执行ACL,但Servlet允许通过读取内容 /etc.clientlibs/
如果 allowProxy
属性设置为 true
.
如果静态资源位于客户端库文件夹下的资源下,则只能通过代理访问。
例如:
- 您在中有一个clientlib
/apps/myproject/clientlibs/foo
- 您有一个静态图像
/apps/myprojects/clientlibs/foo/resources/icon.png
然后设置 allowProxy
属性 foo
为真。
- 然后,您可以请求
/etc.clientlibs/myprojects/clientlibs/foo.js
- 然后,您可以通过引用图像
/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png
/apps
并使用代理servlet使它们可用。 但是,请记住,最佳做法仍然要求公共站点绝不包括任何直接通过 /apps
或 /libs
路径。创建客户端库文件夹 create-a-client-library-folder
-
在Web浏览器中打开CRXDE Lite(https://localhost:4502/crx/de)。
-
选择要在其中找到客户端库文件夹的文件夹,然后单击 创建>创建节点.
-
输入库文件的名称,然后在“类型”列表中选择
cq:ClientLibraryFolder
. 单击 确定 然后单击 全部保存. -
要指定库所属的类别,请选择
cq:ClientLibraryFolder
节点,添加以下属性,然后单击 全部保存:- 名称:类别
- 类型:字符串
- 值:类别名称
- 多:选择
-
以任何方式将源文件添加到库文件夹中。 例如,使用WebDav客户端复制文件,或创建文件并手动创作内容。
注意: 如果需要,可以在子文件夹中组织源文件。
-
选择客户端库文件夹,然后单击 “创建”>“创建文件”.
-
在“文件名”框中,键入以下文件名之一,然后单击“确定”:
js.txt
: 使用此文件名可生成JavaScript文件。css.txt
: 使用此文件名可生成层叠样式表。
-
打开文件并键入以下文本以标识源文件路径的根:
#base=*[root]*
替换*
[root]
*以及包含源文件的文件夹的路径(相对于TXT文件)。 例如,当源文件与TXT文件位于同一文件夹时,请使用以下文本:#base=.
以下代码将根设置为下面名为mobile的文件夹
cq:ClientLibraryFolder
节点:#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
节点,使用以下属性属性:
- 名称: 嵌入
- 类型: 字符串[]
- 值: 的categories属性值
cq:ClientLibraryFolder
要嵌入的节点。
使用嵌入以最大限度地减少请求 using-embedding-to-minimize-requests
在某些情况下,您可能会发现发布实例为典型页面生成的最终HTML包含相对大量的 <script>
元素,特别是当站点正在使用客户端上下文信息进行分析或定位时。 例如,在非优化项目中,您可能会找到以下系列 <script>
页面HTML中的元素:
<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>
在这种情况下,有必要将所有所需的客户端库代码合并到单个文件中,以便减少页面加载上的来回请求数量。 要执行此操作,您可以 embed
将所需的库插入到您应用程序特定的客户端库中,使用的嵌入属性 cq:ClientLibraryFolder
节点。
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%;
}
的CSS文件 publicmain
节点使用原始图像的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
节点具有以下属性:
- 名称: 渠道
- 类型: 字符串[]
- 值: 移动组的名称。 要从组中排除库文件夹,请在名称前面添加感叹号(“!”)。
例如,下表列出了 channels
属性的每个客户端库文件夹 cq.widgets
类别:
/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支持可插拔的预处理器,并且随附支持 YUI压缩机 适用于CSS和JavaScript和 Google Closure Compiler (GCC) 将YUI设置为AEM默认预处理器的JavaScript。
可插拔预处理器允许灵活使用,包括:
- 定义可以处理脚本源的ScriptProcessors
- 处理器可通过选项进行配置
- 处理器可用于缩小,也可用于非缩小情况
- clientlib可以定义要使用的处理器
用途 usage
您可以选择为每个客户端库或系统范围配置预处理器配置。
-
添加多值属性
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,请执行以下步骤。
-
转到Apache Felix配置管理器,网址为 https://localhost:4502/system/console/configMgr
-
查找并编辑 AdobeGraniteHTML库管理器.
-
启用 Minify 选项(如果尚未启用)。
-
设置值 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库管理器.