Strony domowe

Strony główne to nowa funkcja dodatków do Google Workspace, która umożliwia definiowanie co najmniej 1 karty niekontekstowej. Karty niezwiązane z kontekstem służą do wyświetlania interfejsu użytkownika poza określonym kontekstem, takim jak wyświetlanie skrzynki odbiorczej Gmaila, ale bez otwarcia wiadomości lub wersji roboczej.

Strony główne pozwalają wyświetlać treści niekontekstowe, tak jak aplikacje Google, w panelu bocznym szybkiego dostępu (Keep, Kalendarz i Lista zadań). Strony główne mogą służyć jako punkt początkowy, gdy użytkownik otworzy Twój dodatek, i mogą być przydatne dla użytkowników, którzy chcą korzystać z Twojego dodatku.

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

Możesz mieć wiele stron głównych – po jednej na każdą aplikację hostującą rozszerzenie. Możesz też zdefiniować pojedynczą domyślną stronę główną używaną na potrzeby hostów, dla których nie określono niestandardowej strony głównej.

Strona główna dodatku jest wyświetlana po spełnieniu jednego z tych warunków:

• Gdy dodatek jest otwierany po raz pierwszy na hoście (po autoryzacji).
• Gdy użytkownik przełącza się z kontekstu kontekstowego na niekontekstowy, gdy dodatek jest otwarty. Na przykład od edytowania wydarzenia w Kalendarzu do głównego.
• Gdy użytkownik klika przycisk Wstecz, ile razy ma potrzebę, aby wyciągnąć każdą inną kartę ze stosu wewnętrznego.
• Interakcja z interfejsem użytkownika na karcie niezwiązanej z kontekstem powoduje wywołanie wywołania Navigation.popToRoot().

Projektowanie strony głównej nie jest obowiązkowe, ale bardzo zalecane. Jeśli go nie zdefiniujesz, używana będzie ogólna karta zawierająca Twój dodatek, gdy użytkownik będzie chciał otworzyć stronę główną.

Konfiguracja strony głównej

Dodatki do Google Workspace wykorzystują pole addOns.common.homepageTrigger, aby skonfigurować domyślną treść dodatku (niekontekstowego) dla wszystkich aplikacji hosta w pliku manifestu:

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

• runFunction: nazwa funkcji Apps Script, którą wywołania platformy dodatków do Google Workspace powodują wyświetlenie 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 będzie wyświetlać nagłówki karty na liście, którą użytkownik może wybrać (patrz 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 true. Jeśli zasada ma wartość false, karty na stronie głównej są wyłączane u wszystkich hostów (chyba że zostały zastąpione dla tego hosta – patrz niżej).

Uwaga: aby host mógł używać wspólnej strony głównej, musi on zawierać zarówno addOns.common.homepageTrigger, jak i zasoby najwyższego poziomu gospodarza. Jeśli na przykład w pliku manifestu nie ma addOns.gmail, dodatek jest wyłączony w Gmailu i nie wyświetla strony głównej (ani żadnych innych funkcji na tym hoście).

Oprócz wspólnej konfiguracji dostępne są również identycznie uporządkowane zastąpienia hosta w konfiguracji każdej aplikacji hosta (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 interfejs wyświetlany jako dodatek w danej usłudze hosta zależy od obecności odpowiedniego pola pliku manifestu oraz od tego, czy istnieje powiązany element homepageTrigger. Poniższy przykład pokazuje, które funkcje aktywatora dodatkowego są wykonywane (jeśli istnieją), aby utworzyć interfejs strony głównej dla różnych konfiguracji pliku manifestu:

Obiekty zdarzeń na stronie głównej

Po wywołaniu wskazana powyżej funkcja aktywatora strony głównej (runFunction) jest przekazywana do obiektu zdarzenia zawierającego 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ń:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale i commonEventObject.userTimezone (informacje o ograniczeniach znajdziesz w sekcji Uzyskiwanie dostępu do ustawień regionalnych i strefy czasowej użytkownika).

Więcej informacji znajdziesz w sekcji Obiekt zdarzenia.

Inne karty bez kontekstu

Twój interfejs dodatku może zawierać dodatkowe karty inne niż kontekstowe, które nie są stronami głównymi. Na przykład na stronie głównej może znajdować się przycisk otwierający kartę „Ustawienia”, na której użytkownik może dostosować ustawienia dodatku (w większości przypadków będzie to niezależnie od kontekstu i dlatego nie ma związku z kontekstem).

Karty inne niż kontekstowe są tworzone jak pozostałe karty. Jedyna różnica to to, jakie działanie lub zdarzenie jest generowane i wyświetlane. Szczegółowe informacje o tworzeniu przełączeń między kartami znajdziesz w sekcji Metody nawigacji.