Strony główne to nowa funkcja dodatków Google Workspace, która umożliwia zdefiniowanie co najmniej 1 niekontekstualnych kart. Karty bez kontekstu służą do wyświetlania interfejsu użytkownika, 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 niekontekstualnych, podobnie jak aplikacje Google w panelu bocznym szybkiego dostępu (Keep, Kalendarz i Lista zadań). Strony główne mogą też stanowić początkowy punkt, z którego użytkownik może otworzyć dodatek, a także służyć do nauczania nowych użytkowników, jak korzystać z dodatku.
Stronę główną dodatku możesz zdefiniować, podając ją w manifeście projektu i wdrażając co najmniej jedną funkcję homepageTrigger (patrz Konfiguracja strony głównej).
Możesz mieć wiele stron głównych, po jednej dla każdej aplikacji hosta, którą rozszerza Twój dodatek. Możesz też zdefiniować jedną wspólną domyślną stronę główną, która będzie używana w przypadku hostów, w 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:
- Gdy dodatek zostanie otwarty po raz pierwszy w hostie (po autoryzacji).
- Gdy użytkownik przełączy się z kontekstu związanego na kontekst niezwiązany, 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 wysunąć wszystkie karty z zewnętrznych stosów.
- Gdy interakcja z interfejsem na karcie bez kontekstu powoduje wywołanie
Navigation.popToRoot().
Projektowanie strony głównej nie jest obowiązkowe, ale jest wysoce zalecane. Jeśli nie zdefiniujesz żadnej strony głównej, za każdym razem, gdy użytkownik będzie chciał przejść na stronę główną, będzie używana ogólna karta z nazwą dodatku.
Konfiguracja strony głównej
Dodatki Google Workspace używają pola addOns.common.homepageTrigger, aby skonfigurować domyślne treści strony głównej (niekontekstualne) dla wszystkich aplikacji hosta w pliku manifestu dodatku:
{
// ...
"addOns": {
// ...
"common": {
// ...
"homepageTrigger": {
"runFunction": "myFunction",
"enabled": true
}
}
}
}
runFunction: nazwa funkcji Apps Script, którą wywołuje framework dodatków Google Workspace, aby renderować karty dodatków na stronie głównej. Ta funkcja to funkcja reguły strony głównej. Ta funkcja musi tworzyć i zwracać tablicę obiektówCard, które tworzą interfejs strony głównej. Jeśli zwróconych zostanie więcej niż 1 karta, aplikacja hosta wyświetli nagłówki kart na liście, z której użytkownik może dokonać wyboru (patrz Zwracanie wielu kart).enabled: czy karty strony głównej mają być włączone w przypadku tego zakresu. To pole jest opcjonalne i domyślnie ustawione natrue. Ustawienie tej opcji nafalsepowoduje wyłączenie kart na stronie głównej dla wszystkich hostów (chyba że zostały one zastąpione dla danego hosta; patrz poniżej).
Oprócz wspólnej konfiguracji w konfiguracji każdej aplikacji hosta dostępne są też zastąpienia o identycznej strukturze 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 }
},
...
}
}
Pamiętaj, że jest to równoważne z tym fragmentem 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 użytkownika wyświetlany dla dodatku w danym produkcie hosta zależy od obecności odpowiedniego pola manifestu i od tego, czy jest powiązany z homepageTrigger. Ten przykład pokazuje, które funkcje reguły dodatku są wykonywane (jeśli w ogóle) w celu utworzenia interfejsu strony głównej w różnych konfiguracjach pliku manifestu:
Obiekty zdarzeń na stronie głównej
Gdy wywołana zostanie funkcja aktywatora strony głównej (runFunction), o której mowa powyżej, przekazywany jest jej obiekt zdarzenia zawierający dane z kontekstu wywołania.
Obiekty zdarzeń strony głównej nie zawierają informacji o widżecie ani informacji kontekstowych. Przekazywane informacje są ograniczone do tych pól obiektu zdarzenia wspólnego:
commonEventObject.clientPlatformcommonEventObject.hostAppcommonEventObject.userLocaleicommonEventObject.userTimezone(ale dostęp do lokalizacji i strefy czasowej użytkownika znajdziesz w informacjach o ograniczeniach).
Więcej informacji znajdziesz w sekcji Obiekt zdarzenia.
Inne karty bez kontekstu
Interfejs dodatku może zawierać dodatkowe karty bez kontekstu, 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, a zatem niekontekstualne).
Karty bez kontekstu są tworzone tak samo jak inne karty. Różnica polega tylko na tym, jakie działanie lub zdarzenie powoduje ich wyświetlenie. Szczegółowe informacje o tworzeniu przejść między kartami znajdziesz w artykule Metody nawigacji.