Strony domowe

Strony główne to nowa funkcja dodatków do Google Workspace, która umożliwia zdefiniowanie jednej lub kilku kart niekontekstowych. Karty niezwiązane z kontekstem służą do wyświetlania interfejsu, gdy użytkownik znajduje się poza określonym kontekstem, np. podczas przeglądania skrzynki odbiorczej w Gmailu, ale nie otworzył wiadomości ani wersji roboczej.

Na stronach głównych możesz wyświetlać treści niekontekstowe, tak jak aplikacje Google, w panelu bocznym szybkiego dostępu (Keep, Kalendarz i Lista zadań). Strony główne mogą też służyć za pierwszym razem, gdy użytkownik otworzy Twój dodatek, i umożliwiają nauczenie nowych użytkowników, jak z niego korzystać.

Możesz zdefiniować stronę główną dodatku. Aby to zrobić, określ go w pliku manifestu projektu i zaimplementuj co najmniej jedną funkcję homepageTrigger (zobacz Konfigurację strony głównej).

Możesz mieć wiele stron głównych, po jednej dla każdej aplikacji hosta, którą wzbogaca Twój dodatek. Możesz też zdefiniować pojedynczą domyślną stronę główną, która będzie używana na hostach, które nie mają określonej strony głównej.

Strona główna dodatku jest wyświetlana, gdy jest spełniony jeden z tych warunków:

  • Przy pierwszym uruchomieniu dodatku w hostze (po autoryzacji).
  • Gdy użytkownik przechodzi z kontekstu kontekstowego na kontekst niekontekstowy, gdy dodatek jest otwarty. Na przykład przechodzenie z wydarzenia w Kalendarzu do głównego.
  • Gdy użytkownik kliknie przycisk Wstecz wystarczająco długo, aby wypchnąć każdą kartę z stosów wewnętrznych.
  • Gdy interakcja z użytkownikiem na karcie niezwiązanej z kontekstem powoduje wywołanie Navigation.popToRoot().

Zaprojektowanie strony głównej nie jest obowiązkowe, ale zdecydowanie zalecane. Jeśli nie określisz żadnej strony, za każdym razem, gdy użytkownik przejdzie na stronę główną, zostanie użyta ogólna karta zawierająca Twój dodatek.

Konfiguracja strony głównej

Dodatki do Google Workspace wykorzystują pole addOns.common.homepageTrigger do konfigurowania domyślnej treści głównej (niekontekstowej) dla wszystkich aplikacji hosta w pliku manifestu:

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }
  • runFunction: nazwa funkcji Apps Script, która jest wywoływana przez wtyczkę do dodatków Google Workspace, aby renderować karty dodatków na stronie głównej. Jest to funkcja uruchamiająca stronę główną. Ta funkcja musi utworzyć i zwrócić tablicę obiektów Card, które składają się na interfejs strony głównej. Jeśli zostanie zwróconych więcej niż 1 karta, aplikacja hosta wyświetli nagłówki kart z listy do wyboru (patrz Zwracanie wielu kart).

  • enabled: określa, czy karty na stronie głównej powinny być włączone dla tego zakresu. To pole jest opcjonalne i ma domyślną wartość true. Jeśli zasada ma wartość false, karty strony głównej są wyłączane na wszystkich hostach (chyba że zostały one zastąpione dla tego hosta – patrz niżej).

Oprócz wspólnej konfiguracji dostępne są też identyczne struktury na hosta w każdej konfiguracji aplikacji hosta, m.in. addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger i tak:

    {
      ...
      "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 }
        },
        ...
      }
    }

Jest to odpowiednik tego fragmentu pliku manifestu:

    {
      ...
      "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": { /* ... */ },
        ...
      }
    }

Żadna z sekcji homepageTrigger nie jest wymagana. Interfejs wyświetlany w dodatku w danej usłudze hosta zależy jednak od obecności odpowiedniego pola pliku manifestu oraz tego, czy jest powiązany element homepageTrigger. Poniższy przykład pokazuje, które funkcje aktywujące dodatek są wykonywane (jeśli występują), aby utworzyć interfejs strony głównej dla różnych konfiguracji pliku manifestu:

Przepływ na stronie głównej

Obiekty zdarzeń na stronie głównej

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

Obiekty zdarzeń na stronie głównej nie zawierają widżetów ani informacji kontekstowych. Przekazane informacje są ograniczone do tych pól popularnego obiektu zdarzenia:

Więcej informacji znajdziesz w sekcji Obiekt zdarzenia.

Inne karty niezwiązane z kontekstem

Interfejs użytkownika może zawierać dodatkowe karty niezwiązane z kontekstem, które nie są stronami głównymi. Na przykład na stronie głównej może być widoczny przycisk, który pozwala otworzyć kartę z ustawieniami dodatku. W większości przypadków ustawienia te są niezależne od kontekstu, dzięki czemu nie jest kontekstowy.

Karty niekontekstowe są tworzone jak inne karty; jedyna różnica polega na tym, jakie działanie lub zdarzenie powoduje ich wyświetlenie i wyświetlenie. Szczegółowe informacje o tworzeniu przejść między kartami znajdziesz w artykule Metody nawigacji.