文档AEMAEM 教程AEM Sites WKND 教程

客户端库和前端工作流 client-side-libraries

Last update: Sun Jul 14 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

创建对象：

  • 初学者
  • 开发人员

了解如何使用客户端库或clientlibs为Adobe Experience Manager (AEM) Sites实施部署和管理CSS和JavaScript。 本教程还介绍了如何将ui.frontend模块（一个分离的webpack项目）集成到端到端构建过程中。

先决条件 prerequisites

查看设置本地开发环境所需的工具和说明。

还建议查看组件基础知识教程，以了解客户端库和AEM的基础知识。

入门项目

NOTE
如果成功完成了上一章，则可以重用该项目并跳过签出入门项目的步骤。

查看本教程所基于的基本行代码：

  1. 从GitHub中签出tutorial/client-side-libraries-start分支

    code language-shell 
    $ cd aem-guides-wknd
$ git checkout tutorial/client-side-libraries-start

  2. 使用您的Maven技能将代码库部署到本地AEM实例：

    code language-shell 
    $ mvn clean install -PautoInstallSinglePackage
    note note
    NOTE
    如果使用AEM 6.5或6.4，请将classic配置文件附加到任何Maven命令。
    code language-shell 
    $ mvn clean install -PautoInstallSinglePackage -Pclassic

您始终可以在GitHub上查看完成的代码，或通过切换到分支tutorial/client-side-libraries-solution在本地签出代码。

目标

  1. 了解如何通过可编辑的模板将客户端库包含在页面中。
  2. 了解如何使用ui.frontend模块和Webpack开发服务器进行专用前端开发。
  3. 了解将编译后的CSS和JavaScript交付到Sites实施的端到端工作流程。

您即将构建的内容 what-build

在本章中，您为WKND站点和文章页面模板添加了一些基线样式，以使实施更接近UI设计模型。 您可以使用高级前端工作流将webpack项目集成到AEM客户端库中。

已完成样式

应用了基线样式的​ 文章页面

背景 background

客户端库提供了一种机制，用于整理和管理AEM Sites实施所需的CSS和JavaScript文件。 客户端库或clientlibs的基本目标是：

  1. 将CSS/JS存储在小型离散文件中，以方便开发和维护
  2. 以有条理的方式管理对第三方框架的依赖项
  3. 通过将CSS/JS关联到一个或两个请求中，最大程度地减少客户端请求的数量。

有关使用客户端库的详细信息可在此处找到。

客户端库确实存在一些限制。 最值得注意的是，对常用前端语言（如Sass、LESS和TypeScript）的支持有限。 在本教程中，让我们看看​ ui.frontend ​模块如何帮助解决此问题。

将入门级代码库部署到本地AEM实例，并导航到http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html。 此页面未设置样式。 让我们实施适用于WKND品牌的客户端库以将CSS和JavaScript添加到页面。

客户端库组织 organization

接下来，让我们浏览由AEM项目原型生成的clientlibs的组织。

高级客户端库组织

高级关系图客户端库组织和页面包含

NOTE
以下客户端库组织由AEM Project Archetype生成，但仅代表起点。 项目最终如何向Sites实施管理和提供CSS和JavaScript可能会因资源、技能集和要求而存在显着差异。

  1. 使用VSCode或其他IDE打开​ ui.apps ​模块。

  2. 展开路径/apps/wknd/clientlibs以查看原型生成的clientlibs。

    ui.apps中的 Clientlibs

    在以下部分中，将详细审查这些clientlibs。

  3. 下表汇总了客户端库。 有关的更多详细信息（包括客户端库）可在此处找到。

    table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3
    名称 描述 注释
    clientlib-base WKND站点正常运行所需的CSS和JavaScript的基本级别 嵌入核心组件客户端库
    clientlib-grid 生成布局模式工作所需的CSS。 可在此处配置移动设备/平板电脑断点
    clientlib-site 包含WKND站点的站点特定主题 由ui.frontend模块生成
    clientlib-dependencies 嵌入任何第三方依赖项 由ui.frontend模块生成

  4. 请注意，从源代码管理中忽略clientlib-site和clientlib-dependencies。 这是特意设计的，因为这些是由ui.frontend模块在构建时生成的。

更新基本样式 base-styles

接下来，更新​ ui.frontend ​模块中定义的基本样式。 ui.frontend模块中的文件将生成包含站点主题和任何第三方依赖项的clientlib-site和clientlib-dependecies库。

客户端库不支持更高级的语言，如Sass或TypeScript。 有多种开源工具（如NPM和webpack）可以加速和优化前端开发。 ui.frontend ​模块的目标是能够使用这些工具管理大多数前端源文件。

  1. 打开​ ui.frontend ​模块并导航到src/main/webpack/site。

  2. 打开文件main.scss

    main.scss - entrypoint

    main.scss是ui.frontend模块中Sass文件的入口点。 它包括_variables.scss文件，该文件包含一系列要在项目中的不同Sass文件中使用的品牌变量。 _base.scss文件也包含在内，它为HTML元素定义了某些基本样式。 正则表达式包含src/main/webpack/components下各个组件样式的样式。 另一个正则表达式包含src/main/webpack/site/styles下的文件。

  3. Inspect文件main.ts。 它包含main.scss和一个正则表达式，用于收集项目中的任何.js或.ts文件。 此入口点被Webpack配置文件用作整个ui.frontend模块的入口点。

  4. Inspect src/main/webpack/site/styles下的文件：

    样式文件

    这些文件用于模板中的全局元素，如页眉、页脚和主内容容器。 这些文件中的CSS规则以不同的HTML元素header、main和footer为目标。 这些HTML元素由上一章Pages and Templates中的策略定义。

  5. 展开src/main/webpack下的components文件夹并检查文件。

    组件Sass文件

    每个文件都映射到核心组件，如折叠组件。 每个核心组件都使用块元素修饰符或BEM表示法构建，以便更轻松地使用样式规则定位特定的CSS类。 /components下的文件已被AEM项目原型用每个组件的不同BEM规则清除。

  6. 下载WKND基本样式​ wknd-base-styles-src-v3.zip ​和​ unzip ​文件。

    WKND基本样式

    为了加速教程，提供了多个基于核心组件和文章页面模板的结构实施WKND品牌的Sass文件。

  7. 使用上一步骤的文件覆盖ui.frontend/src的内容。 zip文件的内容应覆盖以下文件夹：

    code language-plain 
    /src/main/webpack
         /components
         /resources
         /site
         /static

    更改的文件

    Inspect更改的文件，以查看WKND样式实施的详细信息。

Inspect与ui.frontend集成 ui-frontend-integration

内置到​ ui.frontend ​模块aem-clientlib-generator中的关键集成块从webpack/npm项目中获取编译的CSS和JS工件，并将其转换为AEM客户端库。

ui.frontend架构集成

AEM项目原型会自动设置此集成。 接下来，探索它的工作方式。

  1. 打开命令行终端并使用npm install命令安装​ ui.frontend ​模块：

    code language-shell 
    $ cd ~/code/aem-guides-wknd/ui.frontend
$ npm install
    note note
    NOTE
    npm install只运行一次，例如在克隆或生成项目之后。

  2. 打开ui.frontend/package.json并在​ 脚本 start ​命令中添加--env writeToDisk=true。

    code language-json 
    {
  "scripts": {
    "start": "webpack-dev-server --open --config ./webpack.dev.js --env writeToDisk=true",
  }
}

  3. 运行以下命令以在​ watch ​模式下启动webpack开发服务器：

    code language-shell 
    $ npm run watch

  4. 这将编译来自ui.frontend模块的源文件，并在http://localhost:4502与AEM同步更改

    code language-shell 
    + jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js
+ jcr_root/apps/wknd/clientlibs/clientlib-site/js
+ jcr_root/apps/wknd/clientlibs/clientlib-site
+ jcr_root/apps/wknd/clientlibs/clientlib-dependencies/css.txt
+ jcr_root/apps/wknd/clientlibs/clientlib-dependencies/js.txt
+ jcr_root/apps/wknd/clientlibs/clientlib-dependencies
http://admin:admin@localhost:4502 > OK
+ jcr_root/apps/wknd/clientlibs/clientlib-site/css
+ jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js
http://admin:admin@localhost:4502 > OK

  5. 命令npm run watch最终会填充​ ui.apps ​模块中的​ clientlib-site ​和​ clientlib-dependencies，然后该模块会自动与AEM同步。

    note note
    NOTE
    还有一个可缩小JS和CSS的npm run prod配置文件。 这是通过Maven触发Webpack构建时的标准编译。 有关ui.frontend模块的更多详细信息见此处。

  6. 在ui.frontend/dist/clientlib-site/site.css下Inspect文件site.css。 这是基于Sass源文件的编译的CSS。

    分布式站点CSS

  7. Inspect文件ui.frontend/clientlib.config.js。 这是npm插件aem-clientlib-generator的配置文件，该文件将/dist的内容转换为客户端库并将其移动到ui.apps模块。

  8. 在ui.apps/src/main/content/jcr_root/apps/wknd/clientlibs/clientlib-site/css/site.css的​ ui.apps ​模块中Inspect文件site.css。 这应该是​ ui.frontend ​模块中site.css文件的相同副本。 现在它位于​ ui.apps ​模块中，可以将其部署到AEM中。

    ui.apps clientlib-site

    note note
    NOTE
    由于​ clientlib-site ​是在构建期间使用​ npm ​或​ maven ​编译的，因此可以安全地从​ ui.apps ​模块中的源代码管理中忽略它。 Inspect ui.apps ​下的.gitignore文件。

  9. 在AEM中打开LA Skatepark文章： http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html。

    已更新文章的基本样式

    此时，您应该会看到该文章的更新样式。 您可能需要进行硬刷新以清除浏览器缓存的任何CSS文件。

    它看起来越来越接近模型了！

    note note
    NOTE
    当从项目mvn clean install -PautoInstallSinglePackage的根触发Maven生成时，会自动执行以上执行的将ui.frontend代码构建和部署到AEM的步骤。

更改样式

接下来，在ui.frontend模块中进行小幅更改，以查看npm run watch自动将样式部署到本地AEM实例。

  1. 从，ui.frontend模块打开文件： ui.frontend/src/main/webpack/site/_variables.scss。

  2. 更新$brand-primary颜色变量：

    code language-scsss 
    //== variables.css

//== Brand Colors
$brand-primary:          $pink;

    保存更改。

  3. 返回浏览器并刷新AEM页面以查看更新：

    客户端库

  4. 将更改还原为$brand-primary颜色并使用命令CTRL+C停止Webpack生成。

CAUTION
并非所有项目都有必要使用​ ui.frontend ​模块。 ui.frontend ​模块增加了额外的复杂性，如果不需要或希望使用某些高级前端工具(Sass、webpack、npm…)，则可能不需要它。

页面和模板包含 page-inclusion

接下来，让我们查看如何在AEM页面中引用clientlibs。 Web开发的常见最佳实践是在关闭</body>HTML之前将CSS包含到标题<head>和JavaScript中。

  1. 浏览到http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page/structure.html上的文章页面模板

  2. 单击​ 页面信息 ​图标，然后在菜单中选择​ 页面策略 ​以打开​ 页面策略 ​对话框。

    文章页面模板菜单页面策略

    页面信息>页面策略

  3. 请注意，此处列出了wknd.dependencies和wknd.site的类别。 默认情况下，通过页面策略配置的clientlibs会被拆分，以便在页面头中包含CSS，并在正文末尾包含JavaScript。 您可以明确列出要在页头中加载的clientlib JavaScript。 这是wknd.dependencies的情况。

    文章页面模板菜单页面策略

    note note
    NOTE
    也可以使用customheaderlibs.html或customfooterlibs.html脚本直接从页面组件引用wknd.site或wknd.dependencies。 使用模板提供了灵活性，您可以在中选择每个模板使用的clientlib。 例如，如果您有一个重型JavaScript库，该库将仅用于选定模板。

  4. 导航到使用​ 文章页面模板 ​创建的​ LA滑板场 ​页面： http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html。

  5. 单击​ 页面信息 ​图标，然后在菜单中选择​ 以发布的形式查看 ​以在AEM编辑器外部打开文章页面。

    查看已发布的项目

  6. 查看http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled的页面源，您应该能够在<head>中看到以下clientlib引用：

    code language-html 
    <head>
...
<script src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.js"></script>
<link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.css" type="text/css">
<link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-78fb9cea4c3a2cc17edce2c2b32631e2-lc.min.css" type="text/css">
...
</head>

    请注意，clientlibs正在使用代理/etc.clientlibs终结点。 您还应该看到以下clientlib包含在页面底部：

    code language-html 
    ...
<script src="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-7157cf8cb32ed66d50e4e49cdc50780a-lc.min.js"></script>
<script src="/etc.clientlibs/wknd/clientlibs/clientlib-base.lc-53e6f96eb92561a1bdcc1cb196e9d9ca-lc.min.js"></script>
...
</body>
    note note
    NOTE
    对于AEM 6.5/6.4，客户端库不会自动缩小。 请参阅有关HTML库管理器的文档以启用缩小（推荐）。
    note warning
    WARNING
    在发布端，客户端库​ 不从/apps 提供 ​这一点至关重要，因为出于安全原因，应使用Dispatcher筛选器部分限制此路径。 客户端库的allowProxy属性确保从​**/etc.clientlibs**​提供CSS和JS。

后续步骤 next-steps

了解如何使用Experience Manager的样式系统实施单个样式并重用核心组件。 使用样式系统进行开发涵盖了使用样式系统扩展核心组件以及模板编辑器的品牌特定CSS和高级策略配置。

在GitHub上查看完成的代码，或在Git分支tutorial/client-side-libraries-solution上本地查看和部署代码。

  1. 克隆github.com/adobe/aem-wknd-guides存储库。
  2. 查看tutorial/client-side-libraries-solution分支。

其他工具和资源 additional-resources

Webpack DevServer — 静态标记 webpack-dev-static

在前几个练习中，ui.frontend ​模块中的多个Sass文件已更新，通过构建过程，最终可以看到这些更改反映在AEM中。 接下来，让我们看一下使用webpack-dev-server快速开发针对​ static HTML的前端样式的技术。

如果大多数样式和前端代码由专用的前端开发人员执行，而这些开发人员可能无法轻松访问AEM环境，则这项技术将会非常实用。 这种技术还允许FED直接对HTML进行修改，然后可以将其移交给AEM开发人员作为组件实施。

  1. 复制位于http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled的LA滑板公园文章页面的页面源。

  2. 重新打开IDE。 将来自AEM的复制标记粘贴到src/main/webpack/static下​ ui.frontend ​模块中的index.html。

  3. 编辑复制的标记并删除对​ clientlib-site ​和​ clientlib-dependencies ​的任何引用：

    code language-html 
    <!-- remove -->
<script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.js"></script>
<link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.css" type="text/css">
<link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.css" type="text/css">
...
<script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site.js"></script>

    删除这些引用，因为webpack开发服务器会自动生成这些工件。

  4. 通过从​ ui.frontend ​模块中运行以下命令，从新终端启动webpack开发服务器：

    code language-shell 
    $ cd ~/code/aem-guides-wknd/ui.frontend/
$ npm start

> aem-maven-archetype@1.0.0 start code/aem-guides-wknd/ui.frontend
> webpack-dev-server --open --config ./webpack.dev.js

  5. 这应该会在http://localhost:8080/处打开一个新的带有静态标记的浏览器窗口。

  6. 编辑文件src/main/webpack/site/_variables.scss文件。 将$text-color规则替换为以下内容：

    code language-diff 
    - $text-color:              $black;
+ $text-color:              $pink;

    保存更改。

  7. 您应该会在http://localhost:8080上自动看到更改自动反映在浏览器中。

    本地Webpack开发服务器更改

  8. 查看/aem-guides-wknd.ui.frontend/webpack.dev.js文件。 这包含用于启动webpack-dev-server的webpack配置。 它从本地运行的AEM实例代理路径/content和/etc.clientlibs。 这就是图像及其他clientlibs（不由​ ui.frontend ​代码管理）的可用方式。

    note caution
    CAUTION
    静态标记的图像src指向本地AEM实例上的活动图像组件。 如果图像的路径发生更改、AEM未启动或浏览器未登录到本地AEM实例，则图像会显示为已损坏。 如果移交给外部资源，也可以使用静态引用替换图像。

  9. 您可以通过键入CTRL+C从命令行​ 停止 webpack服务器。

已弃用 develop-aemfed

aemfed ​是一个开源命令行工具，可用于加快前端开发。 它由aemsync、Browsersync和Sling日志跟踪程序提供支持。

从较高层面来看，aemfed设计用于侦听​ ui.apps ​模块中的文件更改，并自动将它们直接同步到正在运行的AEM实例。 本地浏览器会根据更改自动刷新，从而加快前端开发。 它还能够与Sling日志跟踪器配合使用，以在终端中直接自动显示任何服务器端错误。

如果您在​ ui.apps ​模块中执行了多项工作，修改了HTL脚本并创建了自定义组件，那么​ aemfed ​可以是一个功能强大的工具。 可在此处找到完整文档。

调试客户端库 debugging-clientlibs

使用​ 类别 ​和​ 嵌入 ​的不同方法以包含多个客户端库时，其疑难解答可能会比较麻烦。 AEM公开了多种工具来帮助解决此问题。 最重要的工具之一是​ 重建客户端库，它强制AEM重新编译任何LESS文件并生成CSS。

  • 转储库 — 列出在AEM实例中注册的客户端库。<host>/libs/granite/ui/content/dumplibs.html

  • 测试输出 — 允许用户根据类别查看clientlib include的预期HTML输出。<host>/libs/granite/ui/content/dumplibs.test.html

  • 库依赖项验证 — 突出显示任何无法找到的依赖项或嵌入类别。<host>/libs/granite/ui/content/dumplibs.validate.html

  • 重建客户端库 — 允许用户强制AEM重建客户端库或使客户端库的缓存失效。 在使用LESS进行开发时，此工具有效，因为这会强制AEM重新编译生成的CSS。 通常，使缓存失效然后执行页面刷新比重建库更有效。<host>/libs/granite/ui/content/dumplibs.rebuild.html

重新生成客户端库

recommendation-more-help
b2a561c1-47c0-4182-b8c1-757a197484f9