「首頁」是新的 Google Workspace 外掛程式功能,可讓您定義一或多個非內容相關資訊卡。非關聯資訊卡會在使用者位於特定情境時顯示,例如在使用者查看 Gmail 收件匣,但尚未開啟訊息或草稿時。
首頁可顯示非相關內容,就像快速側邊側邊面板 (Keep、日曆和 Tasks) 中的 Google 應用程式一樣。首頁也可以提供使用者初次開啟外掛程式的初始起點,對於新使用者而言,如何與外掛程式互動。
您可以在專案的資訊清單中指定首頁,並實作一或多個 homepageTrigger
函式,藉此定義外掛程式的首頁 (請參閱首頁設定)。
您可以擁有多個首頁,而每個附加應用程式會有一個外掛程式供擴充功能使用。您也可以定義單一通用預設首頁,這會用於您未指定自訂首頁的主機。
符合下列任一條件時,系統就會顯示您的外掛程式首頁:
- 外掛程式在主機上首次開啟時 (授權後)。
- 外掛程式開啟時,當使用者從上下文中切換為非背景資訊。例如,將日曆活動編輯至主要日曆。
- 當使用者點選返回按鈕的次數足以讓其他卡片從內部堆疊中彈出時。
- 當非關聯卡片的 UI 互動導致
Navigation.popToRoot()
呼叫時。
您不一定要設計首頁,但我們極力推薦您這麼做;如果未定義任何首頁,只要使用者前往首頁,系統就會使用內含外掛程式名稱的一般卡片。
首頁設定
Google Workspace 外掛程式會使用 addOns.common.homepageTrigger
欄位,在外掛程式資訊清單中為所有主機應用程式設定預設首頁 (非關聯) 外掛程式內容:
{
// ...
"addOns": {
// ...
"common": {
// ...
"homepageTrigger": {
"runFunction": "myFunction",
"enabled": true
}
}
}
}
runFunction
:Google Workspace 外掛程式架構叫用的 Apps Script 函式名稱,以叫用首頁外掛程式資訊卡。這個函式是首頁觸發條件函式。此函式必須建構並傳回組成首頁 UI 的Card
物件陣列。如果傳回多張卡片,主機應用程式會在清單中顯示卡片標題,供使用者選取。請參閱傳回多張卡片。enabled
:是否要為這個範圍啟用首頁資訊卡。這是選填欄位,預設為true
。如果設為false
,會停用所有主機的首頁資訊卡 (除非該主機已覆寫;請見下方說明)。
除了常用設定以外,各主機應用程式的設定 (addOns.gmail.homepageTrigger
、addOns.calendar.homepageTrigger
等) 中也提供以結構化結構為基礎的每個主機覆寫設定:
{
...
"addOns": {
...
"common": {
// By default, call 'buildHomePage' to render homepage content
// in all hosts. Since calendar.homepageTrigger below overrides
// this in Calendar and Drive and the homepageTrigger is disabled
// for Gmail, this homepage function never executes.
"homepageTrigger": { "runFunction": "buildHomePage" }
},
"calendar": {
// Show customized homepage content for Calendar only.
"homepageTrigger": { "runFunction": "buildCalendarHomepage" }
},
"drive": {
// Show customized homepage content for Drive only.
"homepageTrigger": { "runFunction": "buildDriveHomepage" }
}
"gmail": {
// Disable homepage add-on content in Gmail.
"homepageTrigger": { "enabled": false }
},
...
}
}
請注意,這等同於以下資訊清單摘錄:
{
...
"addOns": {
...
"common": { /* ... */ }, // Omitted a default homepageTrigger specification.
"calendar": {
// Show customized homepage content for Calendar only.
"homepageTrigger": { "runFunction": "myCalendarFunction" }
},
"drive": {
// Show customized homepage content for Drive only.
"homepageTrigger": { "runFunction": "myDriveFunction" }
}
"gmail": { /* ... */ },
...
}
}
這些 homepageTrigger
區段均無須填寫。但是,任何特定主機產品中外掛程式的 UI,取決於對應的資訊清單欄位,以及是否有相關的 homepageTrigger
。以下範例說明系統會執行哪些外掛程式觸發條件函式 (如果有的話),為不同資訊清單設定建立首頁 UI:
首頁事件物件
呼叫首頁時,上述的首頁觸發條件函式 (runFunction
) 會傳遞包含事件結構定義中資料的事件物件。
首頁事件物件不包含小工具或關聯資訊;傳遞的資訊僅限於下列常見事件物件欄位:
commonEventObject.clientPlatform
commonEventObject.hostApp
commonEventObject.userLocale
和commonEventObject.userTimezone
(如需限制資訊,請參閱存取使用者語言代碼和時區)。
詳情請參閱事件物件一節。
其他非內容比對資訊卡
您的外掛程式 UI 可包含非首頁的其他非內容比對資訊卡。例如,您的首頁可能會顯示一個按鈕,用來開啟「設定」資訊卡,讓使用者可以調整外掛程式設定 (這類設定在多數情況下會獨立於上下文,因此不必使用背景資訊)。
非內容比對資訊卡的建構方式與任何其他資訊卡一樣;唯一的差別在於動作或事件產生的並顯示資訊卡。如要進一步瞭解如何在資訊卡之間建立轉場效果,請參閱導覽方法一文。