Strony domowe

Strony główne to nowa funkcja dodatków do Google Workspace, która umożliwia zdefiniowanie co najmniej 1 karty niezależnej od kontekstu. Karty bez kontekstu służą do wyświetlania interfejsu użytkownika, gdy użytkownik nie znajduje się w określonym kontekście, np. gdy przegląda skrzynkę odbiorczą Gmaila, ale nie otworzył wiadomości ani 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 (Keep, Kalendarz i Lista zadań). Strony główne mogą też stanowić punkt wyjścia, gdy użytkownik po raz pierwszy otworzy dodatek. Są one przydatne do uczenia nowych użytkowników, jak korzystać z dodatku.

Stronę główną dodatku możesz zdefiniować, określając ją w pliku manifestu projektu i wdrażając co najmniej 1 funkcję homepageTrigger (patrz Konfiguracja strony głównej).

Możesz mieć wiele stron głównych, po jednej dla każdej aplikacji hosta, którą rozszerza 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, gdy spełniony jest jeden z tych warunków:

• Gdy dodatek zostanie po raz pierwszy otwarty w aplikacji hosta (po autoryzacji).
• Gdy użytkownik przełącza się z kontekstu kontekstowego na kontekst niekontekstowy, gdy dodatek jest otwarty. Na przykład z edycji 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 bez kontekstu powoduje wywołanie funkcji Navigation.popToRoot().

Zaprojektowanie strony głównej nie jest obowiązkowe, ale wysoce zalecane. Jeśli nie zdefiniujesz żadnej strony głównej, za każdym razem, gdy użytkownik będzie chciał przejść do strony głównej, 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 wszystkich aplikacji hosta w pliku manifestu dodatku:

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

• runFunction: nazwa funkcji 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 hosta 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 powoduje wyłączenie kart na stronie głównej na wszystkich hostach (chyba że zostanie to zastąpione dla danego hosta; patrz poniżej).

Oprócz wspólnej konfiguracji w konfiguracji każdej aplikacji hosta dostępne są też identycznie skonstruowane zastąpienia dla poszczególnych hostów w plikach 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 }
        },
        ...
      }
    }

Pamiętaj, że 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 interfejs wyświetlany w przypadku dodatku w dowolnym produkcie hostującym zależy od obecności odpowiedniego pola pliku manifestu i od tego, czy jest z nim powiązany plik homepageTrigger. Przykład poniżej pokazuje, które funkcje wyzwalacza dodatku są wykonywane (jeśli w ogóle) w celu utworzenia interfejsu strony głównej dla różnych konfiguracji pliku manifestu:

Obiekty zdarzeń na stronie głównej

Po wywołaniu funkcja wyzwalacza strony głównej (runFunction) opisana powyżej otrzymuje 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:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale i commonEventObject.userTimezone (ale informacje o ograniczeniach znajdziesz w sekcji Uzyskiwanie dostępu 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”, na której użytkownik może dostosować ustawienia dodatku (takie ustawienia w większości przypadków są niezależne od kontekstu, a więc nie są kontekstowe).

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.