AEM專案原型的ui.frontend模組

上次更新: 2023-05-26
  • 建立對象:
  • Developer
    Admin

AEM專案原型包括可選的專用前端建置機制(以Webpack為基礎)。 因此,ui.frontend模組成為專案所有前端資源(包括JavaScript和CSS檔案)的中心位置。 若要充分利用這項實用且靈活的功能,請務必瞭解前端開發如何融入AEM專案。

AEM專案與前端開發

簡而言之,AEM專案可視為由兩個獨立但相關的部分組成:

  • 後端開發,用於驅動AEM邏輯並產生Java程式庫、OSGi服務等。
  • 前端開發,可驅動結果網站的呈現和行為,並產生JavaScript和CSS程式庫

由於這兩個開發流程專注於專案的不同部分,因此後端和前端開發可以同時進行。

前端工作流程圖表

但是,任何產生的專案都需要使用這兩種開發工作(即後端和前端)的輸出。

執行中 npm run dev 開始前端建置流程,此流程會收集儲存在ui.frontend模組中的JavaScript和CSS檔案,並產生兩個縮制的使用者端程式庫或ClientLibs,稱為 clientlib-siteclientlib-dependencies 並將它們儲存在ui.apps模組中。 ClientLibs可部署至AEM,並允許您將使用者端程式碼儲存在存放庫中。

使用執行整個AEM專案原型時 mvn clean install -PautoInstallPackage 然後會將所有專案人工因素(包括ClientLibs)推送至AEM例項。

秘訣

進一步瞭解AEM如何處理 AEM開發檔案,操作說明 包含它們,或參閱下文 ui.frontend模組如何使用它們。

ClientLibs概述

前端模組可使用 AEM ClientLib. 執行NPM建置指令碼時,會建置應用程式,而aem-clientlib-generator套件會擷取產生的建置輸出,並將其轉換為這類ClientLib。

ClientLib將包含下列檔案和目錄:

  • css/:可在HTML中請求的CSS檔案
  • css.txt:告知AEM中檔案的順序和名稱 css/ 以便合併
  • js/:可在HTML中請求的JavaScript檔案
  • js.txt 告知AEM中檔案的順序和名稱 js/ 以便合併
  • resources/:來源對應、非入口點程式碼區塊(由程式碼分割產生)、靜態資產(例如圖示)等。

可能的前端開發工作流程

前端建置模組是實用且非常彈性的工具,但並未提供其使用方式的特別意見。 以下是兩個範例 可能 使用情況,但您的個別專案需求可能會指示其他使用模式。

使用Webpack靜態開發伺服器

使用Webpack,您可以根據ui.frontend模組內AEM網頁的靜態輸出來進行樣式設定和開發。

  1. 使用頁面預覽模式或傳入在AEM中預覽頁面 wcmmode=disabled 在URL中
  2. 檢視頁面來源,並在ui.frontend模組中儲存為靜態HTML
  3. 啟動webpack 並開始樣式化和產生必要的JavaScript和CSS
  4. 執行 npm run dev 產生ClientLibs

在此流程中,AEM開發人員可執行第一步和第二步,並將靜態HTML傳遞給根據AEMHTML輸出進行開發的前端開發人員。

秘訣

您也可以運用 元件資料庫 擷取每個元件的標籤輸出範例,以便在元件層級(而非頁面層級)運作。

使用Storybook

使用 Storybook 您可以執行更多原子前端開發。 雖然Storybook未包含在AEM專案原型中,但您可以安裝它並將您的Storybook成品儲存在ui.frontend模組中。 準備好在AEM中進行測試時,可以透過執行將它們部署為ClientLibs npm run dev.

注意

Storybook 未包含在AEM專案原型中。 如果您選擇使用它,則必須另外安裝。

決定標籤

無論您決定為專案實施哪個前端開發工作流程,後端開發人員和前端開發人員都必須先同意標籤。 AEM通常會定義核心元件所提供的標籤。 不過,如有需要,可自訂此專案.

ui.frontend模組

AEM專案原型包含選用的專用前端建置機制,該機制以Webpack為基礎,並具有下列功能。

  • 完整TypeScript、ES6和ES5支援(搭配適用的Webpack包裝函式)
  • 使用TSLint規則集的TypeScript和JavaScript Linting
  • ES5輸出,支援舊版瀏覽器
  • 萬用字元
    • 無需在任何地方新增匯入
    • 所有JS和CSS檔案現在都可以新增至每個元件。
      • 最佳實務低於 /clientlib/js/clientlib/css,或 /clientlib/scss
    • .content.xmljs.txt/css.txt 檔案是必要的,因為一切都是透過Webpack執行。
    • globber會將所有JS檔案提取到 /component/ 資料夾。
      • Webpack可透過JS檔案鏈結CSS/SCSS檔案。
      • 它們會透過兩個入口點被拉入, sites.jsvendors.js.
    • AEM使用的唯一檔案是輸出檔案 site.jssite.css/clientlib-site 以及 dependencies.jsdependencies.css/clientlib-dependencies
  • 區塊
    • 主要(網站js/css)
    • 廠商(相依性js/css)
  • 完整Sass/Scss支援(Sass會透過Webpack編譯為CSS)
  • 內建Proxy至AEM本機執行個體的靜態Webpack開發伺服器
注意

如需ui.frontend模組的詳細技術資訊,請參閱 有關GitHub的檔案.

安裝

  1. 安裝 NodeJS (v10+),全球。 這也會安裝npm。
  2. 導覽至專案中的ui.frontend並執行 npm install.
注意

您必須擁有 執行原型 包含選項 -DoptionIncludeFrontendModule=y 填入ui.frontend資料夾。

使用狀況

以下npm指令碼會驅動前端工作流程:

  • npm run dev — 完整建置,其中停用JS最佳化(tree shaking等)、啟用來源對應並停用CSS最佳化。
  • npm run prod — 完整建置,啟用JS最佳化(tree shaking等)、停用來源地圖並啟用CSS最佳化。
  • npm run start — 啟動靜態Webpack開發伺服器以進行本機開發,並且對AEM的依賴性最小。

輸出

ui.frontend模組會編譯 ui.frontend/src 資料夾並輸出編譯的CSS和JS,以及名為的資料夾下的任何資源 ui.frontend/dist.

  • 網站 - site.jssite.cssresources/ 與版面相關的影像和字型的資料夾建立於 dist/clientlib-site資料夾。
  • 相依性 - dependencies.jsdependencies.css 在中建立 dist/clientlib-dependencies 資料夾。

JavaScript

  • 最佳化 — 對於生產組建,所有未使用或呼叫的JS都會被移除。

CSS

  • 自動加上前置詞 — 所有CSS都是透過前置詞執行,而任何需要加上前置詞的屬性都會自動加入CSS中。
  • 最佳化 — 在發佈時,所有CSS都會透過最佳化工具(cssnano)執行,該工具會根據以下預設規則將其標準化:
    • 儘可能減少CSS計算運算式,確保瀏覽器相容性和壓縮在相等的長度、時間和角度值之間轉換。 請注意,依預設,不會轉換長度值。
    • 移除規則、選取器和宣告中及其周圍的註解
    • 移除重複的規則、at規則和宣告
      • 請注意,這僅適用於完全相同的重複專案。
    • 移除空白規則、媒體查詢和具有空白選取器的規則,因為它們不會影響輸出
    • 透過選取器和重疊的屬性/值配對合併相鄰規則
    • 確保CSS檔案中只有單一@charset案,並將它移動到檔案頂端
    • 當產生的輸出較小時,將CSS初始關鍵字替換為實際值
    • 使用SVGO壓縮內嵌SVG定義
  • 清除 — 包含明確清除工作,以便視需要清除產生的CSS、JS和Map檔案。
  • 來源對應 — 僅開發組建
注意

前端建置選項利用dev-only和prod-only webpack組態檔案,這些檔案共用一個通用組態檔案。 如此一來,即可獨立修改開發及生產設定。

使用者端程式庫產生

ui.frontend模組建置程式會利用 aem-clientlib-generator 外掛程式,以將編譯後的CSS、JS及任何資源移入ui.apps模組。 aem-clientlib-generator設定定義於 clientlib.config.js. 會產生下列使用者端程式庫:

  • clientlib-site - ui.apps/src/main/content/jcr_root/apps/<app>/clientlibs/clientlib-site
  • clientlib-dependencies - ui.apps/src/main/content/jcr_root/apps/<app>/clientlibs/clientlib-dependencies

在頁面上包含使用者端資料庫

clientlib-siteclientlib-dependencies 類別可透過以下方式包含在頁面上: 頁面原則設定 做為預設範本的一部分。 若要檢視原則,請編輯 內容頁面範本>頁面資訊>頁面原則.

網站頁面上最終包含的使用者端程式庫如下:

<HTML>
    <head>
        <link rel="stylesheet" href="clientlib-base.css" type="text/css">
        <script type="text/javascript" src="clientlib-dependencies.js"></script>
        <link rel="stylesheet" href="clientlib-dependencies.css" type="text/css">
        <link rel="stylesheet" href="clientlib-site.css" type="text/css">
    </head>
    <body>
        ....
        <script type="text/javascript" src="clientlib-site.js"></script>
        <script type="text/javascript" src="clientlib-base.js"></script>
    </body>
</HTML>

當然,您可以更新頁面原則及/或修改個別使用者端程式庫的類別和內嵌屬性,以修改上述包含。

靜態Webpack開發伺服器

ui.frontend模組中包含一個webpack-dev-server,可為AEM外部的快速前端開發提供即時重新載入。 安裝程式會利用html-webpack-plugin,自動將從ui.frontend模組編譯的CSS和JS插入靜態HTML範本中。

重要檔案

  • ui.frontend/webpack.dev.js
    • 這包含webpack-dev-serve的設定,並指向要使用的html範本。
    • 它也包含在localhost:4502上執行之AEM執行個體的Proxy設定。
  • ui.frontend/src/main/webpack/static/index.html
    • 這是伺服器將針對的靜態HTML。
    • 如此一來,開發人員就能進行CSS/JS變更,並立即在標籤中反映出來。
    • 假設放置在此檔案中的標籤準確地反映了AEM元件產生的標籤。
    • 此檔案中的標籤不會自動與AEM元件標籤同步。
    • 此檔案也包含儲存在AEM中的使用者端資料庫參考,例如核心元件CSS和回應式格線CSS。
    • webpack開發伺服器已設定為根據中的設定,從本機執行的AEM執行個體代理這些CSS/JS includes ui.frontend/webpack.dev.js.

使用

  1. 從專案的根目錄中執行命令 mvn -PautoInstallSinglePackage clean install 將整個專案安裝至執行位置的AEM執行個體 localhost:4502.
  2. ui.frontend 資料夾。
  3. 執行以下命令 npm run start 以啟動webpack開發伺服器。 開始後,應該會開啟瀏覽器(localhost:8080 或下一個可用的連線埠)。

您現在可以修改CSS、JS、SCSS和TS檔案,且變更會立即反映在webpack開發伺服器中。

此頁面上的