首頁

首頁是 Google Workspace 外掛程式的新功能，可定義一或多張非情境式資訊卡。當使用者不在特定情境中時，系統會顯示非情境式資訊卡的使用者介面，例如使用者正在查看 Gmail 收件匣，但尚未開啟郵件或草稿。

首頁可顯示非脈絡內容，就像快速存取側邊面板 中的 Google 應用程式 (Keep、日曆和 Tasks) 一樣。首頁也可以做為使用者首次開啟外掛程式時的初始起點，並教導新使用者如何與外掛程式互動。

您可以在專案資訊清單中指定外掛程式的首頁，並實作一或多個 homepageTrigger 函式，藉此定義外掛程式的首頁 (請參閱「首頁設定」)。

您可以有多個首頁，每個首頁對應一個外掛程式擴充的主機應用程式。您也可以決定定義單一通用預設首頁，用於未指定自訂首頁的主機。

符合下列任一條件時，系統就會顯示外掛程式首頁：

• 首次在主機中開啟外掛程式 (授權後)。
• 使用者在開啟外掛程式時，從情境式情境切換至非情境式情境。例如從編輯日曆活動的頁面返回主要日曆。
• 使用者點選返回按鈕的次數足夠多，可從內部堆疊中彈出其他所有卡片。
• 當非情境式資訊卡中的 UI 互動導致 Navigation.popToRoot() 呼叫時。

設計首頁並非必要，但強烈建議您這麼做。如果您未定義任何首頁，使用者導覽至首頁時，系統會使用含有外掛程式名稱的一般資訊卡。

首頁設定

Google Workspace 外掛程式會使用 addOns.common.homepageTrigger 欄位，為外掛程式資訊清單中的所有主機應用程式，設定預設首頁 (非情境式) 外掛程式內容：

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }

• runFunction：Google Workspace 外掛程式架構會叫用這個 Apps Script 函式，以算繪外掛程式首頁資訊卡。這個函式是首頁觸發函式。這個函式必須建構並傳回 Card 物件的陣列，組成首頁 UI。如果傳回多張資訊卡，主機應用程式會將資訊卡標題顯示在清單中，供使用者選取 (請參閱「傳回多張資訊卡」)。

• enabled：是否應為這個範圍啟用首頁資訊卡。這個欄位為選填，預設值為 true。如果設為 false，所有主機都會停用首頁資訊卡 (除非該主機已覆寫設定；請參閱下文)。

注意： 如要讓主機使用通用首頁，外掛程式資訊清單中必須同時存在 addOns.common.homepageTrigger 和主機的頂層資源。舉例來說，如果資訊清單中沒有 addOns.gmail，外掛程式就會在 Gmail 中停用，且不會顯示首頁 (或該主機中的任何其他功能)。

除了常見設定外，每個主機應用程式的設定中也有結構相同的每個主機覆寫，位於 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) 會傳遞 event 物件，其中包含來自叫用環境的資料。

首頁事件物件不包含小工具或脈絡資訊；傳遞的資訊僅限於下列常見事件物件欄位：

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale 和 commonEventObject.userTimezone (但請參閱「存取使用者地區設定和時區」一文，瞭解相關限制)。

詳情請參閱事件物件。

其他非情境式資訊卡

外掛程式 UI 可以包含其他非脈絡資訊卡，這些資訊卡並非首頁。舉例來說，首頁可能會有一個按鈕，可開啟「設定」資訊卡，讓使用者調整外掛程式設定 (這類設定通常與內容無關，因此屬於非內容相關設定)。

非情境式資訊卡的建構方式與其他資訊卡相同，唯一的差別在於產生及顯示資訊卡的動作或事件。如要進一步瞭解如何建立資訊卡之間的轉場效果，請參閱「導覽方法」。