什麼是 Sidekick 庫？
Sidekick 庫是 AEM Sidekick 的擴充功能，可讓開發人員能夠為內容作者建立 UI 驅動的工具。此工具包含一個內建的區塊外掛程式，可以以直觀的方式向作者顯示所有區塊的列表，作者無需記住或搜尋區塊的每種變異形式。開發人員也可以為 sidekick 庫編寫自己的外掛程式。
如何使用Sidekick資料庫？
以下步驟詳細說明如何設定Sidekick程式庫和設定區塊外掛程式。
程式庫工作表設定
sidekick程式庫會使用工作表填入您的外掛程式和外掛程式內容。
1. 首先，在sharepoint或gdrive中建立您要儲存程式庫內容的目錄。 我們建議將內容儲存在掛接點根目錄的/tools/sidekick （或任何其他名稱）中。 後續步驟將假設該目錄名為/tools/sidekick。
2. 接下來，在/tools/sidekick目錄中建立名為library （或任何其他名稱）的活頁簿（Excel檔案）。 活頁簿中的每個工作表都代表外掛程式，將由Sidekick程式庫載入。 工作表名稱會決定要載入的外掛程式名稱。 工作表中包含的任何資料在載入時會傳遞至外掛程式。 外掛程式工作表名稱必須加上helix-前置詞。 例如，如果您想要載入名為tags的外掛程式，您可以建立名為helix-tags的工作表。
3. 在本教學課程中，我們將建立blocks外掛程式的工作表。 建立工作表（或重新命名預設工作表），然後將其呼叫'helix-blocks'，並暫時保留空白。
封鎖外掛程式
Sidekick資料庫隨附blocks外掛程式。
封鎖外掛程式設定
若要為區塊外掛程式產生內容，您必須為要包含的每個區塊準備個別的Word檔案。
1. 在/tools/sidekick目錄中建立一個目錄，用來儲存所有區塊變數。 例如，您可以在/tools/sidekick內建立名為blocks的目錄。
2. 在此範例中，假設我們要定義名為columns之區塊的所有變數。 首先，在blocks目錄中建立名為columns的Word檔案，並提供columns區塊所有變數的範例。 在每個區塊變數之後新增一個區段分隔符號。
3. 預覽並發佈columns檔案。
4. 開啟在最後一個區段中建立的資料庫活頁簿，在helix-blocks工作表內，建立兩個名為name和path的欄。
6. 接下來，我們需要為我們的columns區塊新增一列。 在第一欄新增區塊名稱，並在第二欄新增定義區塊變數的檔案url。 例如，如果您想要新增columns區塊，您可以建立名稱為Columns且路徑為/tools/sidekick/blocks/columns的列。 為了讓程式庫跨環境(page、live、prod)運作，您不應為路徑欄使用絕對url。
7. 預覽和發佈library活頁簿。
>由於範例區塊正在發佈，您應該使用大量中繼資料來排除/tools/**內的內容，以免編制索引。
範例library.xlsx
程式庫中繼資料
區塊外掛程式支援名為library metadata的特殊區塊型別，這可讓開發人員告知區塊外掛程式有關區塊或應如何呈現的資訊。
支援的程式庫中繼資料選項
預設程式庫中繼資料和程式庫中繼資料
library metadata有兩種型別。 位於包含區塊的區段中的資料庫中繼資料，或適用於整個檔案的 預設 library metadata，並位於其本身的區段中（稱為library metadata的區塊是區段中的唯一子系）。
以有5種變體的主圖區塊為例。 假設您想要為區塊的每個變數新增相同的說明，而不是將包含說明的library metadata複製到包含變數的每個區段中。 您可以改用 預設 library metadata，將相同的描述套用至區塊的每個變數。 如果您決定某個變數實際需要稍微不同的說明，您可以將library metadata新增至包含該變數的區段，而且當它呈現在區塊外掛程式中時，它會覆寫 預設 library metadata說明。
使用程式庫中繼資料編寫區塊名稱和說明
依預設，區塊名稱（具有變數）將用於呈現區塊外掛程式中的專案。 例如，如果區塊的名稱為columns (center, background)，則在區塊外掛程式中呈現該名稱時，會將該名稱當作標籤使用。 可透過在與區塊相同的區段中建立library metadata區段來自訂此專案。 程式庫中繼資料也可用來編寫區塊的描述，以及新增searchTags以包含使用搜尋功能時的區塊別名。
具有自訂名稱和說明的範例區塊
內容
顯示區
自動封鎖和預設內容
區塊外掛程式能夠呈現預設內容和自動區塊。 為了達成此目的，必須將您的default content或autoblock放在專用區段中，其中應包括定義name屬性的library metadata資料表，如前所述。 如果程式庫中繼資料中未指定名稱，該專案將會標示為「未命名專案」。
由後續區段中的內容所組成的區塊
在某些情況下，開發人員可能會希望區塊包含後續區段中的內容。 不建議使用此模式，原因如下這裡，但如果您選擇使用，區塊外掛程式可以使用library metadata中的include next sections屬性來轉譯這些專案。
範本
範本是將整個檔案分組到Sidekick資料庫中單一元素的方法。 要將檔案標示為範本集type （在default library metadata中）為template。
>重要，library metadata必須在其本身的區段中，並且是唯一可視為default library metadata的子項。
範本也需要支援metadata。 若要將中繼資料表格新增至範本，您可以使用Page metadata區塊。
複製範本時，會將具有值的metadata與內容一起新增到剪貼簿。
Sidekick外掛程式設定
由於Sidekick程式庫託管於與內容相同的原點，因此需建立靜態HTML頁面以載入及設定內容。
1. 在tools/sidekick/中建立名為library.html的檔案；
2. 在library.html中貼上下列程式碼。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, viewport-fit=cover"
/>
<meta name="Description" content="AEM Sidekick Library" />
<meta name="robots" content="noindex" />
<base href="/" />
<style>
html,
body {
margin: 0;
padding: 0;
font-family: sans-serif;
background-color: #ededed;
height: 100%;
}
helix-sidekick { display: none }
</style>
<title>Sidekick Library</title>
</head>
<body>
<script
type="module"
src="https://www.aem.live/tools/sidekick/library/index.js"
></script>
<script>
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
}
document.body.prepend(library)
</script>
</body>
</html>
在上述程式碼中，我們從aem.live載入Sidekick程式庫，然後建立自訂sidekick-library元素並將其新增至頁面。 sidekick-library元素接受設定Sidekick程式庫所需的config物件。
支援的設定引數
區塊外掛程式支援以下可使用外掛程式物件設定的設定屬性。
封鎖外掛程式設定引數
範例
影像編碼
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
encodeImages: true,
}
}
}
自訂檢視區（簡短形式）
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
viewPorts: [600, 900],
}
}
}
自訂檢視區
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
viewPorts: [
{
width: '599px',
label: 'Small',
icon: 'device-phone',
},
{
width: '899px',
label: 'Medium',
icon: 'device-tablet',
},
{
width: '100%',
label: 'Large',
icon: 'device-desktop',
default: true,
},
],
}
}
}
自訂表格標頭顏色
貼上從區塊外掛程式複製的區塊、區段中繼資料或中繼資料時，您可以自訂表格標頭背景和前景顏色。
可使用css變數在library.html中設定預設樣式。
<style>
:root {
--sk-block-table-background-color: #03A;
--sk-block-table-foreground-color: #fff;
--sk-section-metadata-table-background-color: #f30;
--sk-section-metadata-table-foreground-color: #000;
--sk-metadata-table-background-color: #000;
--sk-metadata-table-foreground-color: #fff;
}
</style>
可以使用資料庫中繼資料覆寫這些值。
>根據使用者電腦選取的系統色彩配置（深色模式），Word可能會變更選取的顏色，以嘗試改善協助工具。
自訂外掛程式設定
以下範例在設定中定義了tags外掛程式。 外掛程式物件的金鑰必須符合外掛程式的名稱，外掛程式物件中定義的任何其他屬性將可透過decorate方法的內容引數供外掛程式使用。
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
tags: {
src: '/tools/sidekick/plugins/tags/tags.js',
foo: 'bar'
}
}
}
擴充程式庫
在某些情況下，可能希望合併兩個區塊程式庫。 定義擴充程式庫時，sidekick程式庫應用程式會將基礎程式庫和擴充程式庫合併為作者的單一程式庫清單。
下列範例會定義要合併至基底程式庫的基底程式庫和擴充程式庫（位於另一個原點）。
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
extends: 'https://main--repo--owner.hlx.live/tools/sidekick/library.json'
}
>必須在library.json和擴充程式庫的區塊上設定Access-Control-Allow-Origin標頭，才能將其載入sidekick程式庫。 如需詳細資訊，請參閱自訂HTTP回應標題。
>由於瀏覽器在iframe上強制實施的原點相同原則，目前無法載入擴充區塊的預覽。
Sidekick config.json設定
接下來，為了讓sidekick程式庫出現在sidekick中，必須在tools/sidekick/config.json建立設定檔。 此設定檔案需要在程式碼匯流排中建立，且應簽入github。
{
"project": "Example",
"plugins": [
{
"id": "library",
"title": "Library",
"environments": ["edit"],
"url": "/tools/sidekick/library.html",
"includePaths": ["**.docx**"]
}
]
}
外掛程式組態中的url屬性指出Sidekick應載入外掛程式的位置。 這應該指向我們先前建立的library.html檔案。
>必須將sidekick設定簽入main分支，才能讓外掛程式出現在sidekick中。
>如果github存放庫中不存在tools/sidekick/config.json檔案，則必須建立該檔案。 如需sidekick外掛程式組態選項的詳細資訊，請參閱檔案。
程式庫建置區塊時的注意事項
Sidekick程式庫會先擷取區塊的plain.html轉譯來轉譯區塊，然後將其從內容中的任何其他區塊中移除（例如，如果回應中有多個區塊的變數）。 然後它會要求相同的頁面（沒有.plain.html），並以已剝離的區塊取代main元素，並使用srcdoc屬性將整個檔案載入iframe。
使用window.location
由於區塊是使用srcdoc屬性載入iframe中，因此網站程式碼所使用的window.location物件執行個體將不會包含您預期會看到的典型值。
在程式庫中執行時範例window.location物件
{
"host": "",
"hostname": "",
"href": "about:srcdoc"
"origin": "null"
"pathname": "srcdoc"
"port": ""
"protocol": "about:"
}
因此，如果您的區塊需要使用window.location物件，我們建議將下列函式新增至您的scripts.js檔案，並將它們匯入您的函式以供使用。
/**
* Returns the true origin of the current page in the browser.
* If the page is running in a iframe with srcdoc, the ancestor origin is returned.
* @returns {String} The true origin
*/
export function getOrigin() {
const { location } = window;
return location.href === 'about:srcdoc' ? window.parent.location.origin : location.origin;
}
/**
* Returns the true of the current page in the browser.mac
* If the page is running in a iframe with srcdoc,
* the ancestor origin + the path query param is returned.
* @returns {String} The href of the current page or the href of the block running in the library
*/
export function getHref() {
if (window.location.href !== 'about:srcdoc') return window.location.href;
const { location: parentLocation } = window.parent;
const urlParams = new URLSearchParams(parentLocation.search);
return `${parentLocation.origin}${urlParams.get('path')}`;
}
在lib-aem中使用createOptimizedPicture
lib-aem中的createOptimizedPicture函式也使用 window.location.href。 如果您使用此函式，建議將其移至scripts.js中，並修改以使用上方的getHref()函式。
檢查是否存在Sidekick程式庫
有時您可能想知道頁面或區塊是否在sidekick程式庫中執行。 要執行此操作，有幾個選項。
1. 檢查window.location.href === 'about:srcdoc'
2. main元素和區塊元素將包含sidekick-library類別
建立外掛程式
開發外掛程式類似於在AEM中建構區塊。 一旦使用者嘗試載入外掛程式，sidekick程式庫就會在您的外掛程式上觸發decorate()方法。 此方法會接收容器以轉譯外掛程式，以及外掛程式工作表中包含的任何資料。
/**
* Called when a user tries to load the plugin
* @param {HTMLElement} container The container to render the plugin in
* @param {Object} data The data contained in the plugin sheet
* @param {String} query If search is active, the current search query
* @param {Object} context contains any properties set when the plugin was registered
*/
export async function decorate(container, data, query, context) {
// Render your plugin
}
>必須從外掛程式匯出decorate()函式。
外掛程式預設匯出與搜尋
從外掛程式匯出的預設值，可讓作者自訂載入時標題中顯示的外掛程式名稱，並啟動sidekick程式庫中的搜尋功能。
export default {
title: 'Tags',
searchEnabled: true,
};
當searchEnabled屬性為true時，載入外掛程式時，資料庫標題會顯示搜尋圖示。 如果使用者透過輸入查詢來起始搜尋，將會再次觸發外掛程式的decorate()函式，這次是透過在decorate()函式的查詢引數中傳遞的搜尋字串。
外掛程式網頁元件
外掛程式作者在建立自訂外掛程式時，可以利用Spectrum中的一組精選Web元件。
下列是Spectrum中的可用元件
也可使用頻譜中的下列圖示
外掛程式事件
外掛程式作者可以從他們的外掛程式傳送事件到父sidekick程式庫，以顯示載入器或顯示快顯通知訊息。
快顯通知訊息
import { PLUGIN_EVENTS } from 'https://www.aem.live/tools/sidekick/library/events/events.js';
export async function decorate(container, data, query) {
// Show a toast message
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.TOAST, { detail: { message: 'Toast Shown!', variant: 'positive | negative' } }))
}
顯示和隱藏載入器
import { PLUGIN_EVENTS } from 'https://www.aem.live/tools/sidekick/library/events/events.js';
export async function decorate(container, data, query) {
// Show loader
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.SHOW_LOADER))
...
// Hide loader
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.HIDE_LOADER))
}