首頁

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

首頁可顯示非情境式內容，類似於快速存取側邊面板中的 Google 應用程式 (Google Keep、Google 日曆和 Google Tasks)。使用者首次開啟外掛程式時，首頁也能做為初始起點，有助於教導新使用者如何與外掛程式互動。

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

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

在下列情況下，系統會顯示外掛程式首頁：

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

建議設計首頁。如果未定義任何項目，使用者前往首頁時，系統會使用含有外掛程式名稱的一般資訊卡。

首頁設定

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

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

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

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

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

除了常見設定外，每個主機應用程式的設定中，也提供結構相同的每個主機覆寫，位於 addOns.gmail.homepageTrigger、addOns.calendar.homepageTrigger 和其他主機專屬觸發條件。

以下範例顯示資訊清單，其中定義了常見的資訊主頁觸發條件，但日曆和雲端硬碟會覆寫該條件，並停用 Gmail 的觸發條件。在這個設定中，由於 buildHomePage 函式遭到覆寫或主機已停用，因此永遠不會執行。

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

下列資訊清單摘錄內容與上一個範例等效，即使省略了預設 homepageTrigger 和 Gmail 設定也一樣：

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

homepageTrigger 區段皆為選填。主機產品中顯示的附加元件 UI，取決於是否有對應的資訊清單欄位，以及是否有相關聯的 homepageTrigger。以下範例說明執行哪些外掛程式觸發函式，可為不同的資訊清單設定建立首頁 UI：

顯示外掛程式首頁觸發函式執行流程的圖表

首頁活動物件

呼叫時，先前說明的首頁觸發函式 (runFunction) 會傳遞 event 物件，其中包含來自叫用環境的資料。

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

  • commonEventObject.clientPlatform
  • commonEventObject.hostApp
  • commonEventObject.userLocale 和 commonEventObject.userTimezone (如需限制資訊，請參閱「存取使用者語言代碼和時區」)。

詳情請參閱事件物件。

其他非情境式資訊卡

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

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