文件AEM核心元件指南

搭配核心元件使用Adobe使用者端資料層 data-layer-core-components

Last update: Tue Jun 24 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

  • 開發人員
  • 管理員

Adobe Client Data Layer的目標是提供標準化方法，公開和存取任何指令碼的任何型別的資料，以減少檢測網站所需的工作量。

Adobe Client Data Layer不受平台限制，但已完全整合至核心元件，以與AEM搭配使用。

和核心元件一樣，Adobe Client Data Layer的程式碼可在GitHub與其開發人員檔案中取得。 本檔案概述核心元件與資料層的互動方式，但完整技術詳細資訊將遞延至GitHub檔案。

TIP
如需Adobe Client Data Layer的詳細資訊，請參閱其GitHub存放庫中的資源。
如需Adobe使用者端資料層與核心元件整合的詳細技術資訊，請參閱核心元件存放庫中的DATA_LAYER_INTEGRATION.md檔案。
TIP
您是否考慮過適用於 AEM 的 Edge Delivery Services？
現有的專案可以繼續使用本文件中所述的方法。然而，針對新專案，Adobe 建議採用 Edge Delivery Services。

安裝及啟用 installation-activation

截至核心元件2.9.0版，Data Layer會作為AEM使用者端程式庫隨核心元件發佈，無需安裝。 AEM專案原型v. 24+產生的所有專案預設包含已啟動的資料層。

若要手動啟動資料層，您必須為其建立內容感知設定：

  1. 在/conf/<mySite>資料夾下方建立下列結構，其中<mySite>是您網站的專案名稱：

    • /conf/<mySite>/sling:configs/com.adobe.cq.wcm.core.components.internal.DataLayerConfig
    • 其中每個節點都將jcr:primaryType設定為nt:unstructured。

  2. 新增名稱為enabled的布林值屬性，並將其設定為true。

    WKND參照站台中 DataLayerConfig的位置

    WKND參照站台中​ DataLayerConfig的位置

  3. 將sling:configRef屬性新增至您網站的jcr:content節點，位置在/content （例如/content/<mySite>/jcr:content）下，並將其設定為上一步驟中的/conf/<mySite>。

  4. 啟用後，您可以在編輯器之外載入網站的頁面，例如使用編輯器中的​ 以發佈的形式檢視 ​選項，以驗證啟動。 檢查頁面來源，<body>標籤應包含屬性data-cmp-data-layer-enabled

    code language-html 
    <body class="page basicpage" id="page-id" data-cmp-data-layer-enabled>
    <script>
      window.adobeDataLayer = window.adobeDataLayer || [];
      adobeDataLayer.push({
          page: JSON.parse("{\x22page\u002D6c5d4b9fdd\x22:{\x22xdm:language\x22:\x22en\x22,\x22repo:path\x22:\x22\/content\/wknd\/language\u002Dmasters\/en.html\x22,\x22xdm:tags\x22:[],\x22xdm:template\x22:\x22\/conf\/wknd\/settings\/wcm\/templates\/landing\u002Dpage\u002Dtemplate\x22,\x22@type\x22:\x22wknd\/components\/page\x22,\x22dc:description\x22:\x22WKND is a collective of outdoors, music, crafts, adventure sports, and travel enthusiasts that want to share our experiences, connections, and expertise with the world.\x22,\x22dc:title\x22:\x22WKND Adventures and Travel\x22,\x22repo:modifyDate\x22:\x222020\u002D09\u002D29T07:50:13Z\x22}}"),
          event:'cmp:show',
          eventInfo: {
              path: 'page.page\u002D6c5d4b9fdd'
          }
      });
    </script>

  5. 您也可以開啟瀏覽器的開發人員工具，然後在主控台中，adobeDataLayer JavaScript物件應該可供使用。 輸入下列命令以取得目前頁面的「資料層」狀態：

    code language-javascript 
    window.adobeDataLayer.getState();

支援的元件 supported-components

下列元件支援資料層。

另請參閱元件所觸發的事件。

核心元件資料結構描述 data-schemas

以下是核心元件搭配Data Layer使用的結構描述清單。

元件/容器專案結構描述 item

元件/容器專案結構用於以下元件中：

元件/容器專案結構描述的定義如下。

id: {                   // component ID
    @type               // resource type
    repo:modifyDate     // last modified date
    dc:title            // title
    dc:description      // description
    xdm:text            // text
    xdm:linkURL         // link URL
    parentId            // parent component ID
}

下列事件與元件/容器專案結構描述相關：

  • cmp:click

頁面結構描述 page

「頁面」綱要由下列元件使用：

「頁面」綱要的定義如下。

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    xdm:tags            // page tags
    repo:path           // page path
    xdm:template        // page template
    xdm:language        // page language
}

頁面載入時會觸發cmp:show事件。 此事件從緊接在開頭<body>標籤下方的內嵌JavaScript中傳送，使其成為資料層事件佇列中最早的事件。

容器結構描述 container

容器結構描述可供下列元件使用：

容器結構描述的定義如下。

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    shownItems          // array of the displayed item IDs
}

下列個事件與容器結構描述相關：

  • cmp:click
  • cmp:show
  • cmp:hide

影像結構描述 image

影像結構描述可供下列元件使用：

影像結構的定義如下。

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    image               // asset detail (see below section)
}

下列事件與影像結構描述相關：

  • cmp:click

資產結構 asset

資產結構描述用於影像元件內。

資產結構的定義如下。

id: {
    repo:id             // asset UUID
    repo:path           // asset path
    @type               // asset resource type
    xdm:tags            // asset tags
    repo:modifyDate
}

下列事件與資產結構描述相關：

  • cmp:click

內容片段結構描述 content-fragment

內容片段結構描述已由內容片段元件使用。

內容片段結構的定義如下。

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    elements            // array of the Content Fragment elements
}

用於內容片段元素的結構描述如下。

{
    xdm:title           // title
    xdm:text            // text
}

核心元件事件 events

核心元件會透過「資料層」觸發許多事件。 與資料層互動的最佳實務是註冊事件接聽程式，然後​ 根據事件型別和/或觸發事件的元件採取動作。 ​這將避免與非同步指令碼的潛在競爭條件。

以下為AEM核心元件所提供的現成事件：

  • cmp:click — 按一下可點按的元素（具有data-cmp-clickable屬性的元素）會導致資料層觸發cmp:click事件。
  • cmp:show ​和​ cmp:hide — 操作收合式選單（展開/摺疊）、轉盤（下一個/上一個按鈕）和標籤（索引標籤選取）元件會導致資料層分別觸發cmp:show和cmp:hide事件。 cmp:show事件也會在頁面載入時傳送，且預期會成為第一個事件。
  • cmp:loaded — 使用頁面上的核心元件填入Data Layer之後，Data Layer就會觸發cmp:loaded事件。

元件觸發的事件 events-components

下表列出會觸發事件以及這些事件的標準核心元件。

元件
事件
折疊式面板
cmp:show和cmp:hide
按鈕
cmp:click
階層連結
cmp:click
傳送
cmp:show和cmp:hide
語言導覽
cmp:click
導覽
cmp:click
頁面
cmp:show
索引標籤
cmp:show和cmp:hide
Teaser
cmp:click

事件路徑資訊 event-path-info

AEM核心元件觸發的每個Data Layer事件將包含具有以下JSON物件的裝載：

eventInfo: {
    path: '<component-path>'
}

其中<component-path>是資料層中觸發事件的元件的JSON路徑。 值是重要的，可透過event.eventInfo.path使用，因為它可以用作adobeDataLayer.getState(<component-path>)的引數，它會擷取觸發事件的元件目前狀態，允許自訂程式碼存取其他資料並將其新增到資料層。

例如：

function logEventObject(event) {
    if(event.hasOwnProperty("eventInfo") && event.eventInfo.hasOwnProperty("path")) {
        var dataObject = window.adobeDataLayer.getState(event.eventInfo.path);
        console.debug("The component that triggered this event: ");
        console.log(dataObject);
    }
}

window.adobeDataLayer = window.adobeDataLayer || [];
window.adobeDataLayer.push(function (dl) {
     dl.addEventListener("cmp:show", logEventObject);
});

教學課程

想要更詳細地探索資料層和核心元件嗎？ 檢視此實作教學課程。

TIP
若要進一步探索Data Layer的彈性，請檢閱相關的整合選項，包括如何為自訂元件啟用Data Layer。
recommendation-more-help
d2be9096-a81e-404b-9952-d8925af7219c