文件AEMAEM 教學課程AEM Sites WKND 教學課程

使用者端程式庫和前端工作流程 client-side-libraries

Last update: Mon Jul 15 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組織。

高階clientlibrary組織

高階圖表使用者端資料庫組織與頁面包含

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元素是由上一章頁面和範本中的原則所定義。

  5. 展開src/main/webpack下的components資料夾並檢查檔案。

    元件Sass檔案

    每個檔案都會對應至核心元件，例如摺疊式功能表元件。 每個核心元件是以區塊元素修飾元或BEM標籤法建置，以便更輕鬆地以樣式規則鎖定特定CSS類別。 /components底下的檔案已由AEM Project原型用每個元件的不同BEM規則進行除錯。

  6. 下載WKND基本樣式​ wknd-base-styles-src-v3.zip ​和​ 解壓縮 ​檔案。

    WKND基底樣式

    為了加速教學課程，我們提供多個Sass檔案，這些檔案會根據核心元件和文章頁面範本的結構來實施WKND品牌。

  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並在​ 指令碼 開始 ​命令中新增--env writeToDisk=true。

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

  3. 執行下列命令，以​ watch ​模式啟動webpack dev server：

    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
    此外還有npm run prod個人資料，可縮制JS和CSS。 這是透過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>標籤之前，將CSS納入HTML標題<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。 使用「範本」可提供彈性，讓您可以挑選並選擇每個範本要使用的clientlibs。 例如，如果您有一個只會在選取範本中使用的大型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正在使用Proxy /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
    發佈端很重要的一點是，使用者端程式庫​ 不是/應用程式​ 提供的，因為基於安全性理由，應使用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公開了幾個工具來幫助解決此問題。 最重要的工具之一是​ Rebuild Client Libraries，它會強制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