首頁

首頁是新的 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 可能包含非首頁以外的其他非內容資訊卡。舉例來說，您首頁上的按鈕可能會開啟「設定」資訊卡，讓使用者可以調整外掛程式設定 (這類設定在大部分情況下都是與內容無關，因此並非內容相關)。

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