Strony domowe

Strony główne to nowa funkcja dodatków do Google Workspace, która umożliwia zdefiniowanie jednej lub większej liczby kart niekontekstowych. Karty niekontekstowe służą do wyświetlania interfejsu, gdy użytkownik znajduje się poza określonym kontekstem, na przykład gdy przegląda skrzynkę odbiorczą Gmaila, ale nie otworzył wiadomości ani wersji roboczej.

Strony główne umożliwiają wyświetlanie treści bez kontekstu, tak jak aplikacje Google w panelu bocznym szybkiego dostępu (Keep, Kalendarz i Lista zadań). Strony główne mogą też stanowić początkowe miejsce, od którego użytkownik po raz pierwszy otworzy dodatek. Są one też przydatne, gdy chcesz uczyć nowych użytkowników korzystania z dodatku.

Możesz zdefiniować stronę główną dodatku, określając ją w pliku manifestu projektu i implementując co najmniej 1 funkcję homepageTrigger (zobacz Konfiguracja strony głównej).

Możesz mieć wiele stron głównych, po jednej dla każdej aplikacji hosta rozszerzanej przez dodatek. Możesz też zdefiniować pojedynczą domyślną stronę główną, która będzie używana w hostach, na których nie określono niestandardowej strony głównej.

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

  • Kiedy dodatek zostanie po raz pierwszy otwarty na hoście (po autoryzacji).
  • Gdy użytkownik przełączy się z kontekstu kontekstowego na kontekst niekontekstowy, gdy dodatek jest otwarty. Dotyczy to na przykład edytowania wydarzenia w Kalendarzu na główny Kalendarz.
  • Gdy użytkownik kliknie przycisk Wstecz kilka razy, aby wysunąć pozostałe karty ze stosów wewnętrznych.
  • Interakcja w interfejsie z kartą niekontekstową skutkuje wywołaniem Navigation.popToRoot().

Zaprojektowanie strony głównej nie jest obowiązkowe, ale zdecydowanie zalecane. Jeśli jej nie zdefiniujesz, za każdym razem, gdy użytkownik wejdzie na stronę główną, wyświetli się ogólna karta z nazwą dodatku.

Konfiguracja strony głównej

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

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

  • runFunction: nazwa funkcji Apps Script wywoływana przez platformę dodatków Google Workspace w celu renderowania kart dodatków na stronie głównej. Jest to funkcja aktywatora strony głównej. Ta funkcja musi tworzyć i zwracać tablicę obiektów Card, które składają się na interfejs strony głównej. Jeśli zostanie zwrócona więcej niż 1 karta, aplikacja hostująca wyświetli nagłówki kart na liście, z której użytkownik może skorzystać (patrz sekcja Zwracanie wielu kart).

  • enabled: określa, czy karty na stronie głównej mają być włączone na tym zakresie. To pole jest opcjonalne i ma wartość domyślną true. Ustawienie tej wartości na false powoduje, że karty strony głównej są wyłączone dla wszystkich hostów (chyba że w przypadku tego hosta zostanie to zastąpione – patrz niżej).

Oprócz typowej konfiguracji w konfiguracji każdej aplikacji hosta dostępne są też identycznie uporządkowane zastąpienia dla poszczególnych hostów (addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger itd.):

    {
      ...
      "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. Jednak to, czy interfejs dodatku jest wyświetlany w dowolnej usłudze hosta, zależy od obecności odpowiedniego pola pliku manifestu i tego, czy istnieje powiązany element homepageTrigger. Ten przykład pokazuje, które funkcje aktywujące dodatki są wykonywane (jeśli istnieją) w celu utworzenia interfejsu strony głównej dla różnych konfiguracji w pliku manifestu:

Przepływ pracy na stronie głównej

Obiekty zdarzeń na stronie głównej

Po wywołaniu opisana powyżej funkcja aktywatora strony głównej (runFunction) przekazuje obiekt zdarzenia zawierający dane z kontekstu wywołania.

Obiekty zdarzeń na stronie głównej nie zawierają widżetów ani informacji kontekstowych. Przekazywane informacje są ograniczone do tych typowych obiektów zdarzeń:

Więcej informacji znajdziesz w artykule Obiekt zdarzenia.

Inne karty niekontekstowe

Interfejs dodatku może zawierać dodatkowe karty niekontekstowe, które nie są stronami głównymi. Na przykład strona główna może zawierać przycisk, który otwiera kartę „Ustawienia”, na której użytkownik może dostosować ustawienia dodatku (w większości przypadków będą one niezależne od kontekstu, a tym samym – bez kontekstu).

Karty niekontekstowe są tworzone tak jak wszystkie inne karty. Jedyną różnicą jest to, jakie działanie lub zdarzenie generuje i wyświetla. Szczegółowe informacje o tym, jak tworzyć przejścia między kartami, znajdziesz w sekcji Metody nawigacji.