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

瞭解如何使用使用者端資料庫或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-siteclientlib-dependencies。 這是特意設計,因為這些是由ui.frontend模組在建置時產生。

更新基本樣式 base-styles

接著,更新​ ui.frontend ​模組中定義的基本樣式。 ui.frontend模組中的檔案會產生包含網站主題及任何第三方相依性的clientlib-siteclientlib-dependecies資料庫。

使用者端資料庫不支援更進階的語言,例如SassTypeScript。 有幾個開放原始碼工具,例如NPMwebpack,可加速並最佳化前端開發。 ui.frontend ​模組的目標是能夠使用這些工具來管理大多數前端來源檔案。

  1. 開啟​ ui.frontend ​模組並導覽至src/main/webpack/site

  2. 開啟檔案main.scss

    main.scss - entrypoint

    main.scssui.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元素headermainfooter為目標。 這些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.dependencieswknd.site的類別已在此列出。 依預設,透過頁面原則設定的clientlibs會進行分割,在頁面標頭中包含CSS,並在內文結尾包含JavaScript。 您可以明確列出要載入頁面標題的clientlib JavaScript。 這是wknd.dependencies的情況。

    文章頁面範本功能表頁面原則

    note note
    NOTE
    也可以使用customheaderlibs.htmlcustomfooterlibs.html指令碼,直接從頁面元件參考wknd.sitewknd.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 ​是開放原始碼命令列工具,可用來加速前端開發。 它由aemsyncBrowsersyncSling記錄追蹤器提供支援。

從高層面來看,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