首頁是新的 Google Workspace 外掛程式功能,可讓您定義一或多張非內容資訊卡。非內容資訊卡會在使用者位於特定情境外 (例如使用者正在查看 Gmail 收件匣,但尚未開啟郵件或草稿時) 顯示使用者介面。
首頁可讓您顯示非相關內容,就像在快速存取側邊面板 (Keep、Google 日曆和 Tasks) 中的 Google 應用程式一樣。首頁還可以讓使用者在首次開啟外掛程式時展開初始位置,有助於教導新使用者如何與外掛程式互動。
您可以在專案資訊清單中指定外掛程式的首頁,並實作一或多個 homepageTrigger
函式 (請參閱首頁設定)。
您可以建立多個首頁,每個外掛程式擴充的代管應用程式一個。您也可以定義一個通用的預設首頁,用於尚未指定自訂首頁的主機。
只要符合下列任一條件,外掛程式首頁就會顯示:
- 外掛程式初次在主機中開啟時 (經過授權後)。
- 當使用者開啟外掛程式時,從內容比對內容切換至非上下文情境。例如,從編輯日曆活動到主要日曆。
- 當使用者按一下返回按鈕足夠次,就會從內部堆疊中移除所有其他資訊卡。
- 非內容資訊卡中的使用者介面互動會導致
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 可能包含非首頁以外的其他非內容資訊卡。舉例來說,您首頁上的按鈕可能會開啟「設定」資訊卡,讓使用者可以調整外掛程式設定 (這類設定在大部分情況下都是與內容無關,因此並非內容相關)。
非內容資訊卡的建構方式與任何其他資訊卡一樣,唯一的差別在於系統產生及顯示資訊卡的動作或事件。請參閱「導覽方法」,進一步瞭解如何在資訊卡之間建立轉場效果。