針對Sidekick開發
本檔案的目標是說明開發人員如何與Sidekick互動，以及如何在專案層級進行自訂。
事件
sidekick會引發下列事件：
可在event.detail屬性中找到事件的裝載。
接聽事件
在您的專案程式碼（例如在/scripts/scripts.js中）中，您可以對Sidekick事件做出如下反應（將foo取代為您要監聽之事件的名稱）：
const doFoo = ({ detail: payload }) => {
console.log('something happened', payload);
// your custom code goes here
};
const sk = document.querySelector('aem-sidekick');
if (sk) {
// sidekick already loaded
sk.addEventListener('foo', doFoo);
} else {
// wait for sidekick to be loaded
document.addEventListener('sidekick-ready', () => {
// sidekick now loaded
document.querySelector('aem-sidekick')
.addEventListener('foo', doFoo);
}, { once: true });
}
自訂Sidekick
您可以自訂專案的Sidekick。 您可以將/tools/sidekick/config.json設定檔新增至專案的GitHub存放庫，或使用設定服務。
{
"project": "My project",
"host": "www.mydomain.prod",
"plugins": []
}
如需所有可用的組態選項，請參閱組態結構描述。 以下提供開始使用的一些基本知識：
外掛程式
外掛程式可讓您將自訂功能新增到Sidekick，增強您的使用者體驗。
通用外掛程式屬性
下列屬性適用於所有外掛程式型別：
id（字串）是必填專案，且在sidekick設定中必須是唯一的。title（字串）將顯示在外掛程式按鈕上。titleI18n(object<string， string>)定義選擇性翻譯的標題。pinned（布林值）決定外掛程式是釘選到工具列（預設）還是摺疊到……功能表中。environments(string[])會指定外掛程式應該出現的位置（dev、edit、admin、preview、live或prod）。exclude_paths(string[])定義模式，以根據目前索引標籤URL中的路徑排除外掛程式。include_paths(string[])會根據目前索引標籤URL中的路徑定義包含外掛程式的模式。
URL型外掛程式
您可以指定在按一下外掛程式按鈕時，會在新索引標籤中開啟的url：
{
"plugins": [
{
"id": "foo",
"title": "Foo",
"url": "/tools/sidekick/foo.html"
}
]
}
事件型外掛程式
或者，您可以指定在按一下外掛程式按鈕時要觸發的event名稱。 這可讓您藉由監聽sidekick元素上的事件，在頁面的內容中執行自訂JavaScript程式碼。 自訂事件將有custom:首碼。 為方便起見，傳送的自訂事件包含目前Sidekick狀態的副本。
注意： 事件型外掛程式只能用於下列環境：開發、預覽、即時和生產。 在「編輯」或「管理」中無法執行自訂程式碼。
{
"plugins": [
{
"id": "foo",
"title": "Foo",
"event": "foo"
}
]
}
在您的專案程式碼（例如在/scripts/scripts.js中）中，您可以依照以下方式回應事件：
const doFoo = ({ detail: payload }) => {
console.log('a custom event happened', payload);
// your custom code goes here
};
const sk = document.querySelector('aem-sidekick');
if (sk) {
// sidekick already loaded
sk.addEventListener('custom:foo', doFoo);
} else {
// wait for sidekick to be loaded
document.addEventListener('sidekick-ready', () => {
// sidekick now loaded
document.querySelector('aem-sidekick')
.addEventListener('custom:foo', doFoo);
}, { once: true });
}
特殊外掛程式型別
浮動視窗外掛程式
調色盤是URL型外掛程式的變體，會載入已設定的URL內嵌，而非開啟新標籤。
isPalette（布林值）在浮動視窗中開啟URL型外掛程式的目標，而非新索引標籤。paletteRect（字串）可選擇以DOMRect的格式定義調色盤的大小和位置。
下列範例會建立放置在視窗左下方的標準調色盤：
{
"plugins": [
{
"id": "tools",
"title": "Tools",
"url": "/tools/sidekick/foo-palette.html",
"isPalette": true
}
]
}
如果您想要變更調色盤的大小和位置，請使用paletteRect：
{
"plugins": [
{
"id": "tools",
"title": "Tools",
"url": "/tools/sidekick/foo-palette.html",
"isPalette": true,
"paletteRect": "top:150px;left:7%;height:675px;width:85vw;"
}
]
}
容器外掛程式
容器可讓您將外掛程式分組在一起，並有助於節省工具列中的空間。 按一下容器外掛程式就會切換其下拉式清單，它無法擁有自己的URL或事件動作。
isContainer（布林值）會將外掛程式呈現為下拉式清單，而非按鈕。containerId（字串）將外掛程式新增至具有指定ID的容器外掛程式。
下列範例會建立名為「Tools」的容器，並在其中放置外掛程式「Foo」：
{
"plugins": [
{
"id": "tools",
"title": "Tools",
"isContainer": true
},
{
"id": "foo",
"containerId": "tools",
"title": "Foo",
"event": "foo"
}
]
}
徽章外掛程式
徽章可讓您在特定條件下，將標籤新增到Sidekick。 它們將會在工具列的右側呈現。 徽章具有美利裝飾目的，無法點選。
isBadge（布林值）會將外掛程式呈現為徽章，而非按鈕。badgeVariant（字串）可選擇性地決定徽章的色彩配置（灰色、紅色、橙色、黃色、Chartreuse、芹菜、綠色、海泡糖、青色、藍色、靛藍、紫色、紫紅色或洋紅色）
以下範例將「Stage」徽章新增到預覽環境中的Sidekick：
{
"plugins": [
{
"id": "stage",
"title": "Stage",
"isBadge": true,
"environments" ["preview"]
}
]
}
自訂編輯URL
如果您的專案未使用SharePoint或Google Drive作為內容來源，您可以告訴Sidekick當使用者按一下 編輯 時，如何連結到您的自訂編輯環境。
下列兩個設定選項可供使用：
editUrlLabel（字串）設定使用者可見的標籤editUrlPattern（字串）定義自訂編輯環境的URL模式。 支援{{contentSourceUrl}}或{{pathname}}等預留位置。
{
"editUrlLabel": "Your Editor",
"editUrlPattern": "{{contentSourceUrl}}{{pathname}}?cmd=open"
}
特殊檢視
您可以指定特殊檢視，讓目前的索引標籤URL符合特定模式時，Sidekick重新導向至。 這可協助您提供跨不同媒體型別的順暢使用者體驗，也可啟用自訂程式碼（事件型外掛程式）的執行。 原始資源URL將在url查詢引數中可用。
屬性path和viewer是必要的。 您可以選擇指定顯示在頂端的title，並且您可以在titleI18n物件中提供當地語系化的標題：
{
"specialViews": [
{
"title": "Custom JSON Viewer",
"path" : "**.json",
"viewer": "/tools/sidekick/custom-json-viewer/index.html"
}
]
}
在viewer指定的路徑下，將HTML檔案新增至您的GitHub存放庫，例如：
<html>
<head>
<title>Custom JSON Viewer</title>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="./custom-json-viewer.css">
<!-- add your custom code -->
<script src="./custom-json-viewer.js"></script>
</head>
<body>
</body>
</html>
在同一目錄中新增選用的CSS檔案，以及含有自訂邏輯的JS檔案，例如：
try {
// get the resource URL from the url query parameter
const url = new URL(window.location.href).searchParams.get('url');
if (url) {
const res = await fetch(url);
if (res.ok) {
const text = await res.text();
const data = JSON.parse(text);
// do something with the data, e.g.
document.body.innerHTML = `
<pre>
${JSON.stringify(data, null, 2)}
</pre>
`;
} else {
throw new Error(`failed to load ${url}: ${res.status}`);
}
}
} catch (e) {
console.error('error rendering custom json view', e);
}
開發工作流程
以下工作流程是專為分離式Sidekick開發而設計，以防止對您生產網站上的作者造成無意的中斷：
使用網站副本
如果您的網站組態儲存在組態服務中，您可以使用暫存的網站復本進行Sidekick開發：
- 在組態服務中建立網站🔗的復本。 例如，如果原始網站的名稱為
site1，您可以建立site1-dev，重複使用相同的程式碼和內容。 - 在瀏覽器中開啟
site1-dev的預覽URL：https://main--site1-dev--org.aem.page。 - 在
site1-dev組態中對sidekick物件進行您想要的變更。 - 在每次變更後重新整理瀏覽器標籤以測試您的變更。
- 完成後，將sidekick物件從
site1-dev複製到site1設定，以將您的變更轉出給所有作者。
注意： 在編輯器環境(Google磁碟機或Microsoft Sharepoint)中使用Sidekick時，預設會從原始網站載入設定。 如果您希望sidekick允許您選擇要載入的設定，請先從預覽或即時URL將新網站🔗新增到您的sidekick。 Sidekick現在將顯示選取器以及所有相符的網站。
使用存放庫分支
如果您的網站組態未儲存在組態服務中，您可以使用GitHub中的分支進行sidekick開發：
- 在您網站的GitHub存放庫上，從
main建立分支。 在此範例中，我們將使用dev作為分支名稱。 - 在瀏覽器中開啟
dev分支的預覽URL：https://dev--site1--org.aem.page。 - 開啟或建立存放庫中的下列檔案：
/tools/sidekick/config.json。 - 對sidekick設定檔案進行所需的變更，並將變更推送到
dev分支。 - 在每次變更後重新整理瀏覽器標籤以測試您的變更。
- 完成時，請建立提取請求，並將變更合併至存放庫的
main分支。
警告： 絕對不要直接認可原始存放庫中的main分支。 在合併至main之前，請一律建立分支，並透過提取請求要求稽核您的變更。
注意： 在編輯器環境(Google磁碟機或Microsoft Sharepoint)中使用Sidekick時，預設會從原始網站載入設定。 如果您希望sidekick允許您選擇要載入的設定，請先從預覽或即時URL將新網站🔗新增到您的sidekick。 Sidekick現在將顯示選取器以及所有相符的網站。