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 bez kontekstu, 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 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 jest otwierany po raz pierwszy w hostie (po autoryzacji).
- gdy użytkownik przełączy się z kontekstu kontekstowego na kontekst niekontekstowy, a dodatek jest otwarty. Na przykład z edycji wydarzenia w Kalendarzu do Kalendarza głównego.
- Gdy użytkownik kliknie przycisk Wstecz wystarczająco dużo razy, aby wysunąć wszystkie karty z wewnę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ślną stronę główną (niekontekstualną) dla wszystkich aplikacji hosta w dodatku w pliku manifestu:
{
// ...
"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ócono więcej niż 1 kartę, aplikacja hosta wyświetla 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 zostaną one zastąpione dla danego hosta; patrz poniżej).
Oprócz wspólnej konfiguracji w pliku konfiguracji każdej aplikacji hosta (addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger itd.) dostępne są również zastąpienia o identycznej strukturze:
{
...
"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 zostanie wywołana, opisana powyżej funkcja aktywatora strony głównej (runFunction) 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 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).
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.