使用用戶端程式庫

現代網站嚴重依賴由複雜JavaScript和CSS程式碼驅動的用戶端處理。組織並最佳化此程式碼的服務可能是個複雜的問題。

為協助處理此問題，AEM提供用戶端程式庫資料夾，讓您將用戶端程式碼儲存在儲存庫中，將它組織為類別，並定義將每類程式碼提供給用戶端的時間和方式。然後用戶端程式庫系統會負責在您的最終網頁中產生正確的連結，以載入正確的程式碼。

用戶端程式庫在AEM中的運作方式

在頁面的HTML中包含用戶端程式庫（即JS或CSS檔案）的標準方式，就是在該頁面的JSP中包含<script>或<link>標籤，其中包含該檔案的路徑。例如，

...
<head>
   ...
   <script type="text/javascript" src="/etc/clientlibs/granite/jquery/source/1.8.1/jquery-1.8.1.js?lang=zh-Hant"></script>
   ...
</head>
...

雖然此方法適用於AEM，但當頁面及其組成元件變得複雜時，可能會導致問題。在這種情況下，相同JS程式庫的多份副本可能會納入最終HTML輸出。為避免此情況，並允許用戶端程式庫的邏輯組織，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子樹中的任意位置（這些預設值和其他設定可以通過系統控制台的Adobe Granite HTML Library Manager面板進行控制）。

每個cq:ClientLibraryFolder都會填入一組JS和／或CSS檔案，以及一些支援檔案（請參閱下面）。 cq:ClientLibraryFolder的屬性配置如下：

categories:識別今秋JS和／或CSS檔案集所屬的 cq:ClientLibraryFolder 類別。categories屬性是多值的，允許庫資料夾屬於多個類別的一部分（請參閱下面以瞭解其可能有何用處）。
dependencies:這是此庫資料夾所依賴的其他客戶端庫類別的清單。例如，給定兩個cq:ClientLibraryFolder節點F和G，如果F中的檔案需要G中的另一個檔案才能正常工作，則G的categories中至少一個應位於F的dependencies中。
embed:用於從其他程式庫內嵌程式碼。如果節點F嵌入節點G和H，則產生的HTML將是節點G和H的內容集中。
allowProxy:如果客戶端庫位於下 /apps面，則此屬性允許通過代理Servlet訪問它。請參閱下面的查找客戶端庫資料夾和使用代理客戶端庫Servlet。

參考客戶端庫

由於HTL是開發AEM網站的偏好技術，因此應使用HTL在AEM中包含用戶端程式庫。但是，也可以使用JSP來執行此操作。

使用HTL

在HTL中，用戶端程式庫會透過AEM提供的輔助範本載入，可透過 data-sly-use存取。此檔案中提供3個範本，可透過 data-sly-call呼叫：

css -僅載入參考用戶端程式庫的CSS檔案。
js —— 僅載入參考用戶端程式庫的JavaScript檔案。
all —— 載入參考用戶端程式庫（包括CSS和JavaScript）的所有檔案。

每個幫助模板都需要categories選項來引用所需的客戶端庫。該選項可以是字串值陣列或包含逗號分隔值清單的字串。

如需詳細資訊和使用範例，請參閱檔案HTML範本語言快速入門。

使用JSP

將ui:includeClientLib標籤新增至JSP程式碼，以新增連結至產生之HTML頁面中的用戶端程式庫。要引用庫，請使用ui:includeClientLib節點的categories屬性的值。

<%@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?lang=zh-Hant"></script>

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

注意

<cq:includeClientLib>，過去常用來包含用戶端程式庫的AEM 5.6版已過時。 <ui:includeClientLib> 應改為如上所述。

建立客戶端庫資料夾

建立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中的庫

位於/apps下方的客戶端庫資料夾優先於位於/libs中的同名資料夾。例如，/apps/cq/ui/widgets優先於/libs/cq/ui/widgets。當這些庫屬於相同類別時，會使用/apps下方的庫。

查找客戶端庫資料夾並使用代理客戶端庫Servlet

在舊版中，客戶端庫資料夾位於儲存庫的/etc/clientlibs下方。這仍受支援，但建議用戶端程式庫現在位於/apps下方。這是為了在其他指令碼附近找到客戶端庫，這些指令碼通常位於/apps和/libs下面。

注意

客戶端庫資料夾下的靜態資源必須位於名為resources的資料夾中。如果您在資料夾resources下沒有靜態資源（例如影像），則無法在發佈例項上參考它。以下是範例：https://localhost:4503/etc.clientlibs/geometrixx/components/clientlibs/resources/example.gif

注意

為了更好地將程式碼與內容和設定隔離，建議您在/apps下找到用戶端程式庫，並運用allowProxy屬性透過/etc.clientlibs公開它們。

為了讓/apps下的客戶機庫可以訪問，使用代理伺服器。 ACL仍在客戶端庫資料夾上強制執行，但是，如果allowProxy屬性設定為true，則servlet允許通過/etc.clientlibs/讀取內容。

如果靜態資源位於客戶端庫資料夾下的資源下，則只能通過代理訪問該資源。

例如：

您在/apps/myproject/clientlibs/foo中有clientlib
您的/apps/myprojects/clientlibs/foo/resources/icon.png中有靜態影像

然後，將foo上的allowProxy屬性設為true。

然後，您可以請求/etc.clientlibs/myprojects/clientlibs/foo.js
然後，您可以透過/etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png參考影像

注意

當使用proxied用戶端程式庫時，AEM Dispatcher組態可能需要更新，以確保允許具有擴充用戶端libs的URI。

注意

Adobe建議在/apps下找到用戶端程式庫，並使用proxy servlet提供這些程式庫。但請記住，最佳實務仍要求公共網站不要包含直接透過/apps或/libs路徑提供的任何內容。

建立客戶端庫資料夾

在網頁瀏覽器(https://localhost:4502/crx/de)中開啟CRXDE Lite。
選擇要找到客戶端庫資料夾的資料夾，然後按一下建立>建立節點。
輸入庫檔案的名稱，並在「類型」(Type)清單中選擇cq:ClientLibraryFolder。按一下確定，然後按一下保存全部。
要指定庫所屬的類別或類別，請選擇cq:ClientLibraryFolder節點，添加以下屬性，然後按一下保存所有:
- 名稱：類別
- 類型：字串
- 值：類別名稱
- 多重：選擇
以任何方式將來源檔案新增至程式庫資料夾。例如，使用WebDav用戶端來複製檔案，或建立檔案並手動編寫內容。

注意： 您可視需要在子檔案夾中組織來源檔案。
選擇客戶端庫資料夾，然後按一下「建立」>「建立檔案」。
在檔案名框中，鍵入以下檔案名之一，然後按一下確定：
- js.txt: 使用此檔案名稱產生JavaScript檔案。
- css.txt：使 用此檔案名生成級聯樣式表。
開啟檔案並輸入下列文字，以識別來源檔案路徑的根目錄：

#base=*[root]*

將* [root]*替換為包含源檔案（相對於TXT檔案）的資料夾的路徑。例如，當源檔案與TXT檔案位於同一資料夾時，請使用以下文本：

#base=.

以下代碼將root設定為cq:ClientLibraryFolder節點下名為mobile的資料夾：

#base=mobile
在#base=[root]下面的行中，鍵入源檔案相對於根檔案的路徑。將每個檔案名稱放在單獨的行上。
按一下保存全部。

連結至相依項

當用戶端程式庫資料夾中的程式碼參考其他程式庫時，請將其他程式庫識別為相依性。在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?lang=zh-Hant" type="text/javascript">
<script src="/etc/clientlibs/mylibs/publicmain.js?lang=zh-Hant" type="text/javascript">

從其他程式庫內嵌程式碼

您可以將用戶端程式庫的程式碼內嵌至另一個用戶端程式庫。在執行時期，內嵌程式庫產生的JS和CSS檔案包含內嵌程式庫的程式碼。

嵌入代碼對於提供對儲存在儲存庫的安全區域中的庫的訪問非常有用。

應用程式特定用戶端程式庫資料夾

將所有應用程式相關檔案保留在其應用程式資料夾/app下方是最佳實務。此外，拒絕網站訪客存取/app資料夾也是最佳做法。為滿足這兩種最佳做法，請在/etc資料夾下建立一個客戶端庫資料夾，該資料夾嵌入/app以下的客戶端庫。

使用categories屬性來識別要內嵌的用戶端程式庫資料夾。要嵌入庫，請使用以下屬性屬性將屬性添加到嵌入cq:ClientLibraryFolder節點：

名稱： embed
類型：字 串[]
值：要嵌入的節點的類別屬 cq:ClientLibraryFolder 性的值。

使用內嵌功能將要求減至最少

在某些情況下，您可能會發現，您的發佈例項為典型頁面產生的最終HTML包含相對大量的<script>元素，尤其是當您的網站使用用戶端內容資訊進行分析或定位時。例如，在未最佳化的專案中，您可能會在頁面的HTML中找到下列系列的<script>元素：

<script type="text/javascript" src="/etc/clientlibs/granite/jquery.js?lang=zh-Hant"></script>
<script type="text/javascript" src="/etc/clientlibs/granite/utils.js?lang=zh-Hant"></script>
<script type="text/javascript" src="/etc/clientlibs/granite/jquery/granite.js?lang=zh-Hant"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/jquery.js?lang=zh-Hant"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/shared.js?lang=zh-Hant"></script>
<script type="text/javascript" src="/etc/clientlibs/foundation/personalization/kernel.js?lang=zh-Hant"></script>

在這種情況下，將所有必要的用戶端程式庫程式碼結合到單一檔案中，以減少頁面載入時的來回請求數，是很有用的。若要這麼做，您可以使用cq:ClientLibraryFolder節點的embed屬性，將所需的程式庫embed放入應用程式專用的用戶端程式庫。

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檔案中的路徑

當您內嵌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%;
}

publicmain節點生成的CSS檔案使用原始影像的URL包含以下樣式：

body {
  padding: 0;
  margin: 0;
  background: url(../../../apps/myapp/clientlib/styles/images/bg-full.jpg) no-repeat center top;
  width: 100%;
}

使用特定行動群組的程式庫

使用用戶端程式庫資料夾的channels屬性來識別使用程式庫的行動群組。當針對不同的設備功能設計相同類別的庫時，channels屬性很有用。

要將客戶端庫資料夾與設備組關聯，請使用以下屬性將屬性添加到cq:ClientLibraryFolder節點：

名稱：頻 道
類型：字 串[]
值：行動群組的名稱。若要從群組排除程式庫資料夾，請在名稱前加上驚嘆號("!")。

例如，下表列出了cq.widgets類別中每個客戶端庫資料夾的channels屬性值：

用戶端程式庫資料夾	渠道屬性的值
`/libs/cq/analytics/widgets`	`!touch`
`/libs/cq/analytics/widgets/themes/default`	`!touch`
`/libs/cq/cloudserviceconfigs/widgets`	`!touch`
`/libs/cq/searchpromote/widgets`	`!touch`
`/libs/cq/searchpromote/widgets/themes/default`	[無值]
`/libs/cq/touch/widgets`	`touch`
`/libs/cq/touch/widgets/themes/default`	`touch`
`/libs/cq/ui/widgets`	`!touch`
`/libs/cq/ui/widgets/themes/default`	`!touch`

使用預處理器

AEM允許可插拔的預處理器，並隨附支援UYI Plaxporator的CSS和JavaScript以及Google Closure Compiler(GCC)的JavaScript，而UI已設定為AEM的預處理器。

可插拔的預處理器允許靈活使用，包括：

定義可處理指令碼源的指令碼處理器
處理器可配置選項
處理器可用於微型化，但也可用於非微型化的情況
clientlib可以定義要使用哪個處理器

注意

依預設，AEM會使用UYI壓縮器。有關已知問題的清單，請參見UYI壓縮機GitHub文檔。切換至特定客戶端的GCC壓縮機可解決使用UY時觀察到的一些問題。

注意

請勿將精簡的程式庫放在用戶端程式庫中。請改為提供原始程式庫，如果需要精簡，請使用預處理器的選項。

使用狀況

您可以選擇根據客戶端庫或整個系統配置預處理器配置。

在clientlibrary節點上添加多值屬性cssProcessor和jsProcessor
或者，透過HTML Library Manager OSGi組態定義系統預設組態

clientlib節點上的預處理器配置優先於OSGI配置。

格式與範例

格式

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

UYI壓縮器，用於CSS精簡化和GCC for JS

cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]

鍵入「預處理」，然後「GCC」，將「GCC」輸入為「最小化」和「模糊化」

jsProcessor: [
   "default:typescript",
   "min:typescript",
   "min:gcc;obfuscate=true"
]

其他GCC選項

failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")

有關GCC選項的詳細資訊，請參見GCC文檔。

設定系統預設管理器

UYI在AEM中設為預設微調字元。要將此更改為GCC，請執行以下步驟。

前往https://localhost:4502/system/console/configMgr的Apache Felix Config Manager
尋找並編輯Adobe Granite HTML Library Manager。
啟用Minify選項（如果尚未啟用）。
將值JS處理器預設配置設定為min:gcc。

若以分號(例如min:gcc;obfuscate=true。
按一下保存保存更改。

調試工具

AEM提供數種工具來除錯和測試用戶端程式庫資料夾。

請參閱嵌入檔案

若要追蹤內嵌程式碼的來源，或確保內嵌用戶端程式庫產生預期的結果，您可以在執行時期看到內嵌的檔案名稱。若要查看檔案名稱，請將debugClientLibs=true參數附加至網頁的URL。產生的程式庫包含@import陳述式，而非內嵌程式碼。

在上一個從其他庫嵌入代碼部分的示例中，/etc/client/libraries/myclientlibs/publicmain客戶端庫資料夾嵌入/apps/myapp/clientlib客戶端庫資料夾。將參數附加到網頁會在網頁的原始碼中產生下列連結：

<link rel="stylesheet" href="/etc/clientlibs/mycientlibs/publicmain.css?lang=zh-Hant">

開啟publicmain.css檔案會顯示下列程式碼：

@import url("/apps/myapp/clientlib/styles/main.css");

在網頁瀏覽器的位址方塊中，將下列文字附加至HTML的URL:

?debugClientLibs=true
頁面載入時，請檢視頁面來源。
按一下作為連結元素href提供的連結，以開啟檔案並檢視原始碼。

Discover客戶端庫

/libs/cq/granite/components/dumplibs/dumplibs元件生成有關係統上所有客戶端庫資料夾的資訊頁。 /libs/granite/ui/content/dumplibs節點將元件作為資源類型。若要開啟頁面，請使用下列URL（視需要變更主機和連接埠）:

https://<host>:<port>/libs/granite/ui/content/dumplibs.test.html

這些資訊包括程式庫路徑和類型（CSS或JS），以及程式庫屬性的值，例如類別和相依性。頁面上的後續表格會顯示每個類別和頻道中的程式庫。

請參閱生成的輸出

dumplibs元件包含測試選擇器，顯示為ui:includeClientLib標籤產生的原始碼。頁面包含js、css和主題屬性不同組合的程式碼。

使用下列其中一種方法來開啟「測試輸出」頁面：
- 在dumplibs.html頁面中，按一下按一下這裡以輸出測試文本中的連結。
- 在網頁瀏覽器中開啟下列URL（視需要使用不同的主機和連接埠）:
  - http://<host>:<port>/libs/granite/ui/content/dumplibs.html
預設頁面顯示沒有類別屬性值之標籤的輸出。
要查看類別的輸出，請鍵入客戶端庫的categories屬性的值，然後按一下提交查詢。