使用用戶端資料庫 using-client-side-libraries

Last update: Wed Nov 15 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

現代網站非常依賴由複雜的JavaScript和CSS程式碼驅動的使用者端處理。組織和最佳化此程式碼的伺服可能是一個複雜的問題。

為協助處理此問題，AEM提供 使用者端資料庫資料夾，可讓您將使用者端程式碼儲存在存放庫中、將其組織成類別，並定義每個類別程式碼何時及如何提供給使用者端。然後，使用者端程式庫系統會負責在最終網頁中產生正確的連結，以載入正確的程式碼。

AEM中使用者端資料庫的運作方式 how-client-side-libraries-work-in-aem

在頁面HTML中包含使用者端資料庫（即JS或CSS檔案）的標準方式就是加入 <script> 或 <link> 標籤，包含相關檔案的路徑。例如，

...
<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，此屬性可讓您透過Proxy servlet存取它。另請參閱找到使用者端程式庫資料夾並使用Proxy使用者端程式庫Servlet 底下。

參考使用者端程式庫 referencing-client-side-libraries

由於HTL是開發AEM網站的慣用技術，因此HTL應該用來在AEM中包含使用者端程式庫。不過，您也可以使用JSP執行此操作。

使用HTL using-htl

在HTL中，使用者端程式庫是透過AEM提供的Helper範本載入，該範本可透過進行存取 data-sly-use. 此檔案中有三個範本可用，這些範本可透過來呼叫 data-sly-call：

css — 僅載入參照的使用者端程式庫的CSS檔案。
js — 僅載入參照的使用者端程式庫的JavaScript檔案。
全部 — 載入參照的使用者端程式庫的所有檔案（CSS和JavaScript）。

每個 helper 範本都需要 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 具有值的類別屬性 cq.jquery. JSP檔案中的下列程式碼會參考程式庫：

<ui:includeClientLib categories="cq.jquery"/>

產生的HTML頁面包含下列程式碼：

<script type="text/javascript" src="/etc/clientlibs/foundation/jquery.js"></script>

如需完整資訊，包括篩選JS、CSS或主題庫的屬性，請參閱 ui：includeClientLib.

CAUTION

<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檔案中要合併之來源檔案的檔案。

clientlibarch

如需有關Widget使用者端資料庫特定需求的資訊，請參閱使用和擴充Widget.

Web使用者端必須擁有許可權才能存取 cq:ClientLibraryFolder 節點。您也可以從存放庫的安全區域公開程式庫（請參閱下方的從其他程式庫內嵌程式碼）。

覆寫/lib中的程式庫 overriding-libraries-in-lib

位於下方的使用者端程式庫資料夾 /apps 優先於中的相同名稱資料夾 /libs. 例如， /apps/cq/ui/widgets 優先於 /libs/cq/ui/widgets. 當這些程式庫屬於相同類別時，底下的程式庫 /apps 已使用。

找到使用者端程式庫資料夾並使用Proxy使用者端程式庫Servlet locating-a-client-library-folder-and-using-the-proxy-client-libraries-servlet

在舊版中，使用者端程式庫資料夾位於下方 /etc/clientlibs 存放庫中的。我們仍支援此功能，但建議使用者端程式庫現在位於 /apps. 這是為了在其他指令碼附近找到使用者端程式庫，這些指令碼通常可在下方找到 /apps 和 /libs.

NOTE

使用者端程式庫資料夾下方的靜態資源必須位於名為的資料夾中資源. 如果您在資料夾底下沒有靜態資源，例如影像資源，無法在發佈執行個體上參照。範例如下：https://localhost:4503/etc.clientlibs/geometrixx/components/clientlibs/resources/example.gif

NOTE

若要更妥善地將程式碼與內容和設定隔離開，建議在下方找到使用者端程式庫 /apps 並透過以下方式公開 /etc.clientlibs 藉由使用 allowProxy 屬性。

為了以下使用者端程式庫： /apps 為了能夠存取，使用proxy servelt。 ACL仍強制在使用者端資料庫資料夾上，但servlet允許透過讀取內容 /etc.clientlibs/ 如果 allowProxy 屬性已設為 true.

如果靜態資源位於使用者端程式庫資料夾下方的資源之下，則只能透過Proxy存取。

例如：

您在中有clientlib /apps/myproject/clientlibs/foo
您有一個靜態影像，位於 /apps/myprojects/clientlibs/foo/resources/icon.png

然後設定 allowProxy 屬性： foo 為true。

您之後可以要求 /etc.clientlibs/myprojects/clientlibs/foo.js
接著，您可以透過參考影像 /etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png

CAUTION

使用代理的使用者端程式庫時，AEM Dispatcher設定可能需要更新，以確保允許具有擴充功能clientlibs的URI。

CAUTION

Adobe建議尋找位於以下位置的使用者端程式庫： /apps 以及透過Proxy servlet來使用。不過請記住，最佳實務仍要求公用網站絕對不要包含直接透過提供服務的任何內容。 /apps 或 /libs 路徑。

建立使用者端資源庫資料夾 create-a-client-library-folder

在網頁瀏覽器中開啟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，並使其可透過Proxy servlet存取，如下所述找到使用者端程式庫資料夾並使用Proxy使用者端程式庫Servlet.

使用categories屬性來識別要內嵌的使用者端資料庫資料夾。若要內嵌程式庫，請在內嵌中新增屬性 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 使用者端資源庫：

screen_shot_2012-05-29at20122pm

此 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可以定義要使用哪個處理器

NOTE

依預設，AEM使用YUI壓縮程式。請參閱 YUI壓縮程式GitHub檔案以取得已知問題的清單。切換至特定clientlibs的GCC壓縮程式可以解決使用YUI時觀察到的部分問題。

CAUTION

請勿將縮制的程式庫放入使用者端程式庫中。改為提供原始程式庫，如果需要縮制，請使用前置處理器的選項。

使用狀況 usage

您可以選擇為每個使用者端程式庫或系統範圍設定前置處理器組態。

新增多值屬性 cssProcessor 和 jsProcessor 在clientlibrary節點
或透過以下方式定義系統預設設定 HTML庫管理員 OSGi設定

clientlib節點上的前置處理器設定優先於OSGI設定。

格式與範例 format-and-examples

格式 format

config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;

CSS縮制的YUI壓縮程式和JS的GCC 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

YUI已設定為AEM中的預設縮制器。若要將此變更為GCC，請按照以下步驟操作。

前往Apache Felix設定管理員，網址為 https://localhost:4502/system/console/configMgr
尋找並編輯 AdobeGraniteHTML庫管理員.
啟用 最小化 選項（如果尚未啟用）。
設定值 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");

在網頁瀏覽器的位址方塊中，將下列文字附加至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 頁面上，按一下 按一下這裡進行輸出測試 文字。
- 在網頁瀏覽器中開啟下列URL （視需要使用不同的主機和連線埠）：
  - http://<host>:<port>/libs/granite/ui/content/dumplibs.html
預設頁面顯示沒有categories屬性值的標籤的輸出。
若要檢視類別的輸出，請輸入使用者端程式庫的 categories 屬性並按一下 提交查詢.

為開發和生產設定程式庫處理 configuring-library-handling-for-development-and-production

HTML程式庫管理員服務程式 cq:ClientLibraryFolder 標籤並在執行階段產生程式庫。環境、開發或生產的型別會決定您設定服務的方式：

提高安全性：停用偵錯
提升效能：移除空白並壓縮程式庫。
提高可讀性：包含空白字元且請勿壓縮。

如需有關設定服務的資訊，請參閱 AEMHTML庫管理員.

recommendation-more-help

19ffd973-7af2-44d0-84b5-d547b0dffee2