Strony domowe

Strony główne to funkcja dodatków do Google Workspace, która umożliwia zdefiniowanie co najmniej jednej karty niezależnej od kontekstu. Karty niekontekstowe wyświetlają interfejs użytkownika, gdy użytkownik nie znajduje się w określonym kontekście, np. gdy przegląda skrzynkę odbiorczą Gmaila bez otwartej wiadomości lub wersji roboczej.

Strony główne umożliwiają wyświetlanie treści niezwiązanych z kontekstem, podobnie jak aplikacje Google w panelu bocznym szybkiego dostępu (Google Keep, Kalendarz Google i Lista zadań Google). Strony główne mogą też stanowić punkt wyjścia, gdy użytkownik po raz pierwszy otworzy dodatek. Są one przydatne, aby nauczyć nowych użytkowników, jak korzystać z dodatku.

Zdefiniuj stronę główną dodatku, określając ją w pliku manifestu projektu i wdrażając co najmniej 1 homepageTriggerfunkcję (patrz Konfiguracja strony głównej).

Możesz mieć wiele stron głównych, po jednej dla każdej aplikacji hosta, którą rozszerza Twój dodatek. Możesz też zdefiniować jedną wspólną domyślną stronę główną, która będzie używana na hostach, na których nie została określona niestandardowa strona główna.

Strona główna dodatku jest wyświetlana w tych przypadkach:

• Gdy dodatek zostanie po raz pierwszy otwarty w aplikacji hosta (po autoryzacji).
• Gdy użytkownik przełącza się z kontekstu kontekstowego na niekontekstowy, gdy dodatek jest otwarty. Na przykład z edytowania wydarzenia w Kalendarzu do głównego Kalendarza.
• Gdy użytkownik kliknie przycisk Wstecz wystarczająco wiele razy, aby usunąć z wewnętrznych stosów co drugą kartę.
• Gdy interakcja z interfejsem w karcie niekontekstowej powoduje wywołanie Navigation.popToRoot.

Zalecamy zaprojektowanie strony głównej. Jeśli nie zdefiniujesz żadnej karty, za każdym razem, gdy użytkownik przejdzie na stronę główną, będzie używana ogólna karta zawierająca nazwę dodatku.

Konfiguracja strony głównej

Dodatki do Google Workspace używają pola addOns.common.homepageTrigger do konfigurowania domyślnej strony głównej (niezależnej od kontekstu) dodatku dla aplikacji hostujących w pliku manifestu dodatku:

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

• runFunction: nazwa funkcji Google Apps Script, którą platforma dodatków do Google Workspace wywołuje w celu renderowania kart dodatku na stronie głównej. Ta funkcja to funkcja wywołująca stronę główną. Ta funkcja musi tworzyć i zwracać tablicę obiektów Card, które składają się na interfejs strony głównej. Jeśli zwrócono więcej niż 1 kartę, aplikacja hostująca wyświetla nagłówki kart na liście, z której użytkownik może wybrać kartę (patrz Zwracanie wielu kart).

• enabled: czy karty strony głównej powinny być włączone w tym zakresie. To pole jest opcjonalne, a jego domyślna wartość to true. Ustawienie tej wartości na false spowoduje wyłączenie kart na stronie głównej na wszystkich hostach (chyba że zostanie to zastąpione w przypadku danego hosta; patrz konfiguracja specyficzna dla hosta).

Aby host mógł korzystać ze wspólnej strony głównej, zarówno element addOns.common.homepageTrigger, jak i zasób najwyższego poziomu hosta muszą być obecne w manifeście dodatku. Jeśli na przykład element addOns.gmail nie występuje w pliku manifestu, dodatek jest wyłączony w Gmailu i nie wyświetla strony głównej ani innych funkcji w tej usłudze.

Oprócz wspólnej konfiguracji w konfiguracji każdej aplikacji hosta dostępne są identycznie skonstruowane zastąpienia dla poszczególnych hostów w przypadku addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger i innych wyzwalaczy specyficznych dla hosta.

Poniższy przykład pokazuje plik manifestu, w którym zdefiniowano typowy wyzwalacz strony głównej, ale został on zastąpiony funkcjami niestandardowymi w przypadku Kalendarza i Dysku oraz wyłączony w przypadku Gmaila. W tej konfiguracji wspólna funkcja buildHomePage nigdy nie jest wykonywana, ponieważ jest zastępowana lub host jest wyłączony.

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

Poniższy fragment pliku manifestu jest odpowiednikiem poprzedniego przykładu, mimo że pominięto domyślny element homepageTrigger i konfigurację Gmaila:

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

Żadna z sekcji homepageTrigger nie jest wymagana. Interfejs dodatku wyświetlany w produkcie hostującym zależy od obecności odpowiedniego pola manifestu i tego, czy jest z nim powiązany plik homepageTrigger. W przykładzie poniżej pokazujemy, które funkcje wyzwalacza dodatku są wykonywane w celu utworzenia interfejsu strony głównej w przypadku różnych konfiguracji pliku manifestu:

Obiekty zdarzeń na stronie głównej

Po wywołaniu funkcji wyzwalacza strony głównej (runFunction) opisanej wcześniej przekazywany jest obiekt zdarzenia zawierający dane z kontekstu wywołania.

Obiekty zdarzeń na stronie głównej nie zawierają informacji o widżecie ani informacji kontekstowych. Przekazywane informacje są ograniczone do tych pól obiektu zdarzenia wspólnego:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale i commonEventObject.userTimezone (informacje o ograniczeniach znajdziesz w artykule Dostęp do regionu i strefy czasowej użytkownika).

Więcej informacji znajdziesz w sekcji Obiekt zdarzenia.

Inne karty niekontekstowe

Interfejs dodatku może zawierać dodatkowe karty niekontekstowe, które nie są stronami głównymi. Na przykład na stronie głównej może znajdować się przycisk, który otwiera kartę „Ustawienia” umożliwiającą dostosowanie ustawień dodatku (takie ustawienia są zwykle niezależne od kontekstu).

Karty niezależne od kontekstu są tworzone jak inne karty. Jedyna różnica polega na tym, jakie działanie lub zdarzenie generuje i wyświetla kartę. Więcej informacji o tworzeniu przejść między kartami znajdziesz w sekcji Metody nawigacji.