Widżet to element interfejsu, który udostępnia co najmniej jeden z tych elementów:
- Struktura innych widżetów, takich jak karty i sekcje,
- informacji dla użytkownika, takich jak tekst i obrazy;
- Możliwości działań, takie jak przyciski, pola do wprowadzania tekstu czy pola wyboru.
Zestawy widżetów dodanych do sekcji kart definiują ogólny interfejs dodatku. Widżety wyglądają tak samo i działają tak samo zarówno w przeglądarce, jak i na urządzeniach mobilnych. W dokumentacji referencyjnej opisujemy kilka metod tworzenia zestawów widżetów.
Typy widżetów
Widżety dodatków dzielą się zwykle na 3 grupy: widżety strukturalne, widżety informacyjne i widżety interakcji użytkowników.
Widżety strukturalne
Widżety strukturalne zapewniają kontenery i umożliwiają porządkowanie innych widżetów używanych w interfejsie.
- Zestaw przycisków – zbiór co najmniej 1 przycisku z tekstem lub obrazem pogrupowanych w poziomym wierszu.
- Karta – pojedyncza karta kontekstowa, która zawiera co najmniej 1 sekcję karty. Aby określić, w jaki sposób użytkownicy mogą przechodzić między kartami, skonfiguruj nawigację po kartach.
- Nagłówek karty – nagłówek danej karty. Nagłówki kart mogą zawierać tytuły, podpisy i obrazy. Działania karty i działania uniwersalne są widoczne w nagłówku karty, jeśli dodatek ich używa.
- Sekcja karty – zbiorcza grupa widżetów rozdzielonych od innych sekcji kart regułą poziomą. Opcjonalnie może mieć nagłówek sekcji. Każda karta musi zawierać co najmniej jedną sekcję karty. Nie można dodawać kart ani ich nagłówków do sekcji karty.
Oprócz tych podstawowych widżetów strukturalnych w dodatku do Google Workspace możesz używać usługi kart do tworzenia struktur, które nakładają się na bieżącą kartę: stałe stopki i karty podglądu:
Stała stopka
Na dole karty możesz dodać stały rząd przycisków. Ten wiersz nie przesuwa się ani nie przewija razem z resztą zawartości karty.
Poniższy fragment kodu pokazuje, jak zdefiniować przykładową stopkę stałą i dodać ją do karty:
var fixedFooter = CardService.newFixedFooter()
.setPrimaryButton(
CardService.newTextButton()
.setText("Primary")
.setOpenLink(CardService.newOpenLink()
.setUrl("https://www.google.com")))
.setSecondaryButton(
CardService.newTextButton()
.setText("Secondary")
.setOnClickAction(
CardService.newAction()
.setFunctionName(
"secondaryCallback")));
var card = CardService.newCardBuilder()
// (...)
.setFixedFooter(fixedFooter)
.build();
Podgląd karty
Gdy działanie użytkownika (np. otwarcie wiadomości w Gmailu) wywoła nowe treści kontekstowe, możesz natychmiast wyświetlić nową treść kontekstową (ustawienie domyślne) lub wyświetlić powiadomienie na karcie podglądu u dołu paska bocznego. Jeśli użytkownik kliknie Wstecz , aby wrócić na stronę główną, gdy jest aktywny aktywator kontekstowy, pojawi się karta podsumowania ułatwiająca użytkownikom ponowne znalezienie treści kontekstowych.
Aby wyświetlać kartę podsumowania, gdy dostępne są nowe treści kontekstowe, zamiast natychmiast wyświetlać nową treść kontekstową, dodaj .setDisplayStyle(CardService.DisplayStyle.PEEK)
do klasy CardBuilder
. Karta podglądu pojawia się tylko wtedy, gdy za pomocą reguły kontekstowej zostanie zwrócony pojedynczy obiekt karty. W przeciwnym razie zwrócone karty natychmiast zastępują bieżącą kartę.
Aby dostosować nagłówek karty podglądu, podczas tworzenia karty kontekstowej dodaj metodę .setPeekCardHeader()
ze standardowym obiektem CardHeader
. Domyślnie nagłówek karty Peek zawiera tylko nazwę dodatku.
Poniższy kod, oparty na krótkim wprowadzeniu do dodatku do Google Workspace dla kotów, za pomocą karty Podgląd informuje użytkowników o nowych treściach kontekstowych i dostosowuje nagłówek karty Podgląd tak, aby wyświetlał temat wybranego wątku wiadomości w Gmailu.
var peekHeader = CardService.newCardHeader()
.setTitle('Contextual Cat')
.setImageUrl('https://www.gstatic.com/images/
icons/material/system/1x/pets_black_48dp.png')
.setSubtitle(text);
. . .
var card = CardService.newCardBuilder()
.setDisplayStyle(CardService.DisplayStyle.PEEK)
.setPeekCardHeader(peekHeader);
Widżety informacyjne
Widżety informacyjne wyświetlają informacje użytkownikowi.
- Obraz – obraz wskazywany przez podany przez Ciebie hostowany i publicznie dostępny adres URL.
- DecoratedText – ciąg tekstowy, który możesz łączyć z innymi elementami, np. górną i dolną etykietą tekstową oraz obrazem lub ikoną. Widżety decorationedText mogą też zawierać widżet Button lub Switch. Dodane przełączniki mogą być przełącznikami lub polami wyboru. Tekst zawartości widżetu decorationedText może zawierać formatowanie HTML. Etykiety na górze i na dole muszą mieć zwykły tekst.
- Akapit tekstu – akapit tekstowy, który może zawierać elementy w formacie HTML.
Widżety interakcji użytkownika
Widżety interakcji użytkownika umożliwiają dodatkowi reagowanie na działania podejmowane przez użytkowników. Możesz skonfigurować te widżety, dodając odpowiedzi na działania, aby wyświetlać różne karty, otwierać adresy URL, pokazywać powiadomienia, pisać wersje robocze e-maili lub uruchamiać inne funkcje Apps Script. Więcej informacji znajdziesz w przewodniku Tworzenie kart interaktywnych.
- Działanie karty – element menu w menu na pasku nagłówka dodatku. Menu na pasku nagłówka może też zawierać elementy zdefiniowane jako działania uniwersalne, które pojawiają się na każdej karcie zdefiniowanej przez dodatek.
- Selektory daty i godziny – widżety, które pozwalają użytkownikom wybrać datę, godzinę lub obie te opcje. Więcej informacji znajdziesz w sekcji Selektory daty i godziny poniżej.
- Przycisk graficzny – przycisk z obrazem zamiast tekstu. Możesz użyć jednej z kilku wstępnie zdefiniowanych ikon lub hostowanego publicznie obrazu wskazanego przez jej adres URL.
- Dane wejściowe do wyboru – pole do wprowadzania danych reprezentujące zbiór opcji. Widżety do wprowadzania danych wyświetlane w postaci pól wyboru, przycisków opcji lub menu.
- Przełącz – widżet przełączania. Przełączników można używać tylko w połączeniu z widżetem DecoratedText. Domyślnie są one wyświetlane jako przełącznik, ale możesz też zmienić je na pola wyboru.
- Przycisk tekstowy – przycisk z etykietą tekstową. Możesz określić kolor tła przycisków tekstowych (domyślnie jest to przezroczyste). W razie potrzeby możesz też wyłączyć przycisk.
- Pole do wprowadzania tekstu – pole do wprowadzania tekstu. Widżet może zawierać tytuł, tekst podpowiedzi i tekst wielowierszowy. Widżet może uruchamiać działania po zmianie wartości tekstowej.
- Siatka – wielokolumnowy układ reprezentujący zbiór elementów. Możesz reprezentować elementy za pomocą obrazu, tytułu i podtytułu oraz różnych opcji dostosowania, takich jak style obramowania i przycięcia.
DecoratedText
pola wyboru
Zamiast przycisku czy przełącznika binarnego możesz określić widżet DecoratedText
z dołączonym polem wyboru. Podobnie jak w przypadku przełączników, wartość pola wyboru znajduje się w obiekcie zdarzenia działania, który jest przekazywany do obiektu Action
dołączonego do tego DecoratedText
przez metodę setOnClickAction(action)
.
Z tego fragmentu kodu dowiesz się, jak zdefiniować widżet DecoratedText
z polami wyboru, który możesz następnie dodać do karty:
var decoratedText = CardService.newDecoratedText()
// (...)
.setSwitch(CardService.newSwitch()
.setFieldName('form_input_switch_key')
.setValue('switch_is_on')
.setControlType(
CardService.SwitchControlType.CHECK_BOX));
Selektory daty i godziny
Możesz zdefiniować widżety, które pozwalają użytkownikom wybrać godzinę, datę lub oba te elementy.
Za pomocą polecenia setOnChangeAction()
możesz przypisać funkcję obsługi widżetu, która będzie uruchamiana w przypadku zmiany wartości selektora.
Z tego fragmentu kodu dowiesz się, jak zdefiniować selektor określający tylko datę, selektor ograniczony czasowo i selektor daty i godziny, które możesz następnie dodać do karty:
var dateOnlyPicker = CardService.newDatePicker()
.setTitle("Enter a date")
.setFieldName("date_field")
// Set default value as May 24 2019. Either a
// number or string is acceptable.
.setValueInMsSinceEpoch(1558668600000)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleDateChange"));
var timeOnlyPicker = CardService.newTimePicker()
.setTitle("Enter a time")
.setFieldName("time_field")
// Set default value as 23:30.
.setHours(23)
.setMinutes(30)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleTimeChange"));
var dateTimePicker = CardService.newDateTimePicker()
.setTitle("Enter a date and time")
.setFieldName("date_time_field")
// Set default value as May 24 2019 03:30 AM UTC.
// Either a number or string is acceptable.
.setValueInMsSinceEpoch(1558668600000)
// EDT time is 4 hours behind UTC.
.setTimeZoneOffsetInMins(-4 * 60)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleDateTimeChange"));
Poniżej znajdziesz przykład funkcji obsługi widżetu selektora daty i godziny. Ta moduł obsługi formatuje i rejestruje ciąg znaków reprezentujący datę i godzinę wybraną przez użytkownika w widżecie selektora daty i godziny o identyfikatorze „myDateTimePickerWidgetID”:
function handleDateTimeChange(event) {
var dateTimeInput =
event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
var msSinceEpoch = dateTimeInput.msSinceEpoch;
var hasDate = dateTimeInput.hasDate;
var hasTime = dateTimeInput.hadTime;
// The following requires you to configure the add-on to read user locale
// and timezone.
// See https://developers.google.com/apps-script/add-ons/how-tos/access-user-locale
var userTimezoneId = event.userTimezone.id;
// Format and log the date-time selected using the user's timezone.
var formattedDateTime;
if (hasDate && hasTime) {
formattedDateTime = Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
} else if (hasDate) {
formattedDateTime = Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
+ ", Time unspecified";
} else if (hasTime) {
formattedDateTime = "Date unspecified, "
+ Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
}
if (formattedDateTime) {
console.log(formattedDateTime);
}
}
W tabeli poniżej znajdziesz przykłady interfejsów wyboru selektora na komputerach i urządzeniach mobilnych. Gdy wybierzesz tę opcję, selektor daty otworzy interfejs kalendarza z okresem miesięcznym, aby użytkownik mógł szybko wybrać nową datę.
Gdy użytkownik wybierze selektor godziny na komputerze, pojawi się menu z listą godzin do wyboru w 30-minutowych odstępach. Użytkownik może też podać konkretną godzinę. Na urządzeniach mobilnych wybranie selektora godziny otwiera wbudowany selektor godziny.
Komputer | Urządzenia mobilne |
---|---|
Siatka
Wyświetlaj elementy w układzie wielokolumnowym za pomocą widżetu siatki. Każdy element może zawierać obraz, tytuł i podtytuł. Skorzystaj z dodatkowych opcji konfiguracji, aby ustawić położenie tekstu względem obrazu w elemencie siatki.
Możesz skonfigurować element siatki z identyfikatorem zwracanym jako parametr działania zdefiniowanego w siatce.
var gridItem = CardService.newGridItem()
.setIdentifier("item_001")
.setTitle("Lucian R.")
.setSubtitle("Chief Information Officer")
.setImage(imageComponent);
var cropStyle = CardService.newImageCropStyle()
.setImageCropType(CardService.ImageCropType.RECTANGLE_4_3);
var imageComponent = CardService.newImageComponent()
.setImageUrl("https://developers.google.com/workspace/
images/cymbal/people/person1.jpeg")
.setCropStyle(cropStyle)
var grid = CardService.newGrid()
.setTitle("Recently viewed")
.addItem(gridItem)
.setNumColumns(2)
.setOnClickAction(CardService.newAction()
.setFunctionName("handleGridItemClick"));
Formatowanie tekstu
Niektóre widżety tekstowe obsługują proste formatowanie tekstu HTML. Przy ustawianiu zawartości tekstowej tych widżetów uwzględnij tylko odpowiednie tagi HTML.
Obsługiwane tagi i ich przeznaczenie znajdziesz w tej tabeli:
Format | Przykład | Wyrenderowany wynik |
---|---|---|
Pogrubienie | "This is <b>bold</b>." |
To jest pogrubione. |
Kursywa | "This is <i>italics</i>." |
To jest kursywa. |
Podkreśl | "This is <u>underline</u>." |
To podkreślenie. |
Przekreślenie | "This is <s>strikethrough</s>." |
Jest to |
Kolor czcionki | "This is <font color=\"#FF0000\">red font</font>." |
Jest to czerwona czcionka. |
Hiperlink | "This is a <a href=\"https://www.google.com\">hyperlink</a>." |
To jest hiperlink. |
Godzina | "This is a time format: <time>2023-02-16 15:00</time>." |
Format godziny: . |
Nowy wiersz | "This is the first line. <br> This is a new line. ′′ |
To jest pierwszy wiersz. To jest nowy wiersz. |