Widżety

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.

Widżety strukturalne

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:

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.

Przykład widżetu z poprawioną stopką

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

Przykład karty Podsumowującej

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.

Przykład spersonalizowanej karty ze podglądem

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 informacyjne

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.
Widżet działań na karcie Widżety interakcji użytkownika

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).

Przykład widżetu pola wyboru z dekorowanym tekstem

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.

Przykład spersonalizowanej karty ze podglądem

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
przykład wyboru selektora dat przykład wyboru selektora dat na urządzenia mobilne
Przykład wyboru selektora godziny Przykład wyboru selektora czasu mobilnego

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.

Przykład widżetu siatki

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 przekreślenie.
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.