Strony domowe

Strony główne to nowa funkcja dodatków do Google Workspace, która umożliwia definiowanie co najmniej 1 karty niezależnej od kontekstu. Karty inne niż kontekstowe służą do wyświetlania interfejsu użytkownika poza określonym kontekstem, na przykład gdy użytkownik wyświetla skrzynkę odbiorczą Gmaila, ale nie otwiera wiadomości ani wersji roboczych.

Na stronach głównych możesz wyświetlać treści niezwiązane z kontekstem, tak jak aplikacje Google w panelu bocznym szybkiego dostępu (Keep, Kalendarz i Lista zadań). Strony główne mogą być też dla użytkowników punktem początkowym, gdy użytkownik uruchomi Twój dodatek i przy okazji nauczy Cię, jak z niego korzystać.

Możesz zdefiniować stronę główną dodatku, określając ją w pliku manifestu projektu i implementując 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ą hostuje Twój dodatek. Możesz też zdefiniować jedną domyślną stronę główną używaną w hostach bez określonej niestandardowej strony głównej.

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

  • Gdy dodatek jest otwierany po raz pierwszy na hoście (po autoryzacji).
  • Gdy użytkownik przełączy się z kontekstu kontekstowego na kontekst, który nie jest kontekstowy, podczas gdy dodatek jest otwarty. na przykład edytowanie wydarzenia w Kalendarzu do głównego kalendarza.
  • Gdy użytkownik kliknie przycisk Wstecz tyle razy, aby wysunąć inne karty z stosów wewnętrznych.
  • Gdy interakcja z interfejsem użytkownika na karcie niezwiązanej z kontekstem powoduje wywołanie metody Navigation.popToRoot().

Zaprojektowanie strony głównej nie jest obowiązkowe, ale zdecydowanie zalecane. Jeśli jej nie zdefiniujesz, używana będzie ogólna karta zawierająca nazwę dodatku, gdy użytkownik przejdzie na stronę główną.

Konfiguracja strony głównej

Dodatki do Google Workspace używają pola addOns.common.homepageTrigger do konfigurowania domyślnej zawartości dodatku (niezależnego od kontekstu) na potrzeby wszystkich aplikacji hosta w pliku manifestu:

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

  • runFunction: nazwa funkcji Apps Script, która jest wywoływana przez platformę dodatków Google Workspace do renderowania kart dodatków na stronie głównej. Jest to funkcja aktywatora strony głównej. 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ż jedna karta, aplikacja hosta wyświetli nagłówki kart na liście dostępnej dla użytkownika (patrz sekcja Zwracanie wielu kart).

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

Oprócz wspólnej konfiguracji dostępne są również identycznie uporządkowane zastąpienia poszczególnych hostów w konfiguracji aplikacji hosta, takie jak 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 }
        },
        ...
      }
    }

Odpowiada to fragmentowi 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 interfejs wyświetlany dla dodatku w danej usłudze hosta zależy od obecności odpowiedniego pola pliku manifestu i tego, czy istnieje powiązany element homepageTrigger. Poniższy przykład pokazuje, które funkcje aktywatora dodatku są wykonywane (jeśli występują), aby utworzyć interfejs strony głównej dla różnych konfiguracji pliku manifestu:

Przepływ strony głównej

Obiekty zdarzeń na stronie głównej

Po wywołaniu opisanej powyżej funkcji strony głównej (runFunction) jest przekazywany 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 następujących pól obiektów:

Więcej informacji znajdziesz w sekcji Obiekt zdarzenia.

Inne karty bez kontekstu

Twój interfejs dodatku może zawierać dodatkowe karty, które nie są stronami głównymi. Na przykład na stronie głównej może znajdować się przycisk, który otwiera kartę „Ustawienia”, na której użytkownik może dostosować ustawienia dodatku (w większości przypadków są one niezależne od kontekstu).

Karty niezwiązane z kontekstem są tworzone tak samo jak inne karty. Jedyna różnica polega na tym, jakie działanie lub zdarzenie generuje i wyświetla kartę. Szczegółowe informacje o tworzeniu przejść między kartami znajdziesz w artykule Metody nawigacji.