Widżety

Widget to element interfejsu, który umożliwia co najmniej 1 z tych działań:

• strukturę innych widżetów, takich jak karty i sekcje;
• informacje dla użytkownika, takie jak tekst i obrazy, lub
• Elementy umożliwiające działanie, takie jak przyciski, pola tekstowe czy pola wyboru.

Zestawy widżetów dodanych do sekcji kart określają ogólny interfejs dodatku. Widżety mają taki sam wygląd i takie same funkcje w wersji internetowej i na urządzeniach mobilnych. Dokumentacja referencyjna zawiera kilka metod tworzenia zestawów widżetów.

Typy widżetów

Widgety dodatków są zwykle podzielone na 3 grupy: widgety strukturalne, informacyjne i interakcyjne.

Widgety strukturalne

Widżety strukturalne zapewniają kontenery i organizację innych widżetów używanych w interfejsie.

• Zestaw przycisków – zbiór co najmniej 1 przycisku tekstowego lub graficznego, pogrupowanych w poziomy wiersz.
• Karta – pojedyncza karta kontekstowa zawierająca co najmniej 1 sekcję karty. Możesz określić sposób poruszania się użytkowników między kartami, konfigurując nawigację po kartach.
• Nagłówek karty – nagłówek danej karty. Nagłówki kart mogą zawierać tytuły, podtytuły i obraz. Działania na karcie i działania uniwersalne pojawiają się w nagłówku karty, jeśli dodatek ich używa.
• Sekcja karty – zebrana grupa widżetów, oddzielona od innych sekcji karty poziomą linią i opcjonalnie zawierająca nagłówek sekcji. Każda karta musi mieć co najmniej 1 sekcję. Do sekcji kart nie można dodawać kart ani nagłówków kart.

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ę: stopki i karty podglądu:

Stała stopka

Do dolnej części karty możesz dodać stały rząd przycisków. Ten wiersz nie będzie się przesuwać ani przewijać wraz z pozostałymi elementami karty.

Ten fragment kodu pokazuje, jak zdefiniować przykładowy stały nagłówek i dodać go 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();

Karta Peek

Gdy nowe treści kontekstowe są wywoływane przez działanie użytkownika, np. otwarcie wiadomości w Gmailu, możesz wyświetlić nowe treści kontekstowe natychmiast (zachowanie domyślne) lub powiadomienie z kartą podglądu u dołu paska bocznego. Jeśli użytkownik kliknie Wstecz arrow_back, aby wrócić na stronę główną, gdy aktywny jest kontekstualny przełącznik, pojawi się karta podglądu, która pomoże mu ponownie znaleźć kontekstualne treści.

Aby wyświetlić kartę podglądu, gdy dostępna jest nowa treść kontekstowa, zamiast natychmiast wyświetlać nową treść kontekstową, dodaj .setDisplayStyle(CardService.DisplayStyle.PEEK) do klasy CardBuilder. Karta podglądu pojawia się tylko wtedy, gdy w ramach kontekstowego wyzwalacza zwracany jest pojedynczy obiekt karty. W przeciwnym razie zwracane karty natychmiast zastępują bieżącą kartę.

Aby dostosować nagłówek karty, podczas tworzenia karty kontekstowej dodaj metodę .setPeekCardHeader() z standardowym obiektem CardHeader. Domyślnie nagłówek karty Peek zawiera tylko nazwę dodatku.

Poniższy kod, oparty na dodatku Google Workspace „Cats”, informuje użytkowników o nowych treściach kontekstowych za pomocą karty Peek i dostosowuje nagłówek tej karty, 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

Widgety informacyjne wyświetlają użytkownikowi informacje.

• Obraz – obraz wskazany przez podany przez Ciebie adres URL, który jest hostowany i publicznie dostępny.
• DecoratedText – ciąg tekstowy, który możesz łączyć z innymi elementami, takimi jak etykiety tekstowe u góry i u dołu oraz obraz lub ikona. Widżety DecoratedText mogą też zawierać widżet przycisku lub widżet przełącznika. Dodane przełączniki mogą być przełącznikami lub polami wyboru. Treść tekstu widgetu DecoratedText może używać formatowania HTML, a etykiety górna i dolna muszą być w zwykłym tekście.
• Akapit tekstowy – akapit tekstowy, który może zawierać elementy sformatowanego kodu HTML.

Widgety interakcji użytkownika

Widżety interakcji z użytkownikiem umożliwiają dodatkowi reagowanie na działania użytkowników. Możesz skonfigurować te widżety, aby wyświetlały różne karty, otwierały adresy URL, pokazywały powiadomienia, tworzyły wersje robocze e-maili lub wykonywały inne funkcje Apps Script. Szczegółowe informacje znajdziesz w przewodniku Tworzenie kart interaktywnych.

• Działanie na karcie – element menu umieszczony w menu paska nagłówka dodatku. Menu w pasku nagłówka może też zawierać elementy zdefiniowane jako czynności uniwersalne, które pojawiają się na każdej karcie zdefiniowanej przez dodatek.
• Selektory daty i godziny – widżety, które umożliwiają użytkownikom wybranie daty, godziny lub obu tych elementów. Więcej informacji znajdziesz w sekcji Selektory daty i godziny.
• Przycisk z obrazem – przycisk, który zamiast tekstu zawiera obraz. Możesz użyć jednej z kilku wstępnie zdefiniowanych ikon lub publicznie dostępnego obrazu wskazanego przez jego adres URL.
• Wybór danych wejściowych – pole danych wejściowych, które reprezentuje zbiór opcji. Pola wyboru w postaci pól wyboru, przycisków opcji lub menu.
• Przełącznik – przełącznik. Przełączniki możesz używać tylko w połączeniu z widżetem DecoratedText. Domyślnie te opcje są wyświetlane jako przełączniki, ale możesz je wyświetlać jako pola wyboru.
• Przycisk tekstowy – przycisk z etykietą tekstową. Możesz określić kolor tła przycisków tekstowych (domyślnie jest przezroczysty). W razie potrzeby możesz też wyłączyć przycisk.
• Wprowadzanie tekstu – pole tekstowe. Widżet może zawierać tekst tytułu, tekst podpowiedzi i tekst wielowierszowy. Gdy wartość tekstu się zmieni, widżet może wywołać działanie.
• Siatka – układ z wieloma kolumnami, który przedstawia kolekcję elementów. Możesz reprezentować elementy za pomocą obrazu, tytułu, podtytułu i różnych opcji dostosowywania, takich jak obramowanie i style przycinania.

DecoratedText pole wyboru

Zamiast przycisku lub przełącznika binarnego możesz zdefiniować widget DecoratedTextz polem wyboru. Podobnie jak w przypadku przełączników wartość pola wyboru jest uwzględniona w obiekcie zdarzenia działania, który jest przekazywany do metody Action dołączonej do tego obiektu DecoratedText za pomocą metody setOnClickAction(action).

Ten fragment kodu pokazuje, jak zdefiniować element sterujący pole wyboru DecoratedText, który można 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 umożliwiają użytkownikom wybranie godziny, daty lub obu tych elementów. Za pomocą funkcji setOnChangeAction() możesz przypisać funkcję obsługi widżetu do wykonania, gdy zmieni się wartość selektora.

Ten fragment kodu pokazuje, jak zdefiniować selektor tylko daty, selektor tylko godziny i selektor daty i godziny, które można 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. Ten handler formatuje i zapisują ciąg tekstowy reprezentujący datę i godzinę wybrane 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/workspace/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);
  }
}

Tabela poniżej zawiera przykłady interfejsów selektora na komputerach i urządzeniach mobilnych. Po wybraniu selektora daty otwiera się interfejs kalendarza oparty na miesiącu, który umożliwia użytkownikowi szybki wybór nowej daty.

Gdy użytkownik wybierze selektor czasu na komputerze, otworzy się menu z listą godzin z co 30 minut, z których może wybrać odpowiednią. Użytkownik może też wpisać konkretny czas. Na urządzeniach mobilnych wybranie selektora czasu powoduje otwarcie wbudowanego w urządzenie mobilne selektora „zegar”.

Komputer	Urządzenia mobilne

Siatka

Wyświetlaj elementy w układzie z wieloma kolumnami za pomocą widżetu siatki. Każdy element może zawierać obraz, tytuł i podtytuł. Użyj dodatkowych opcji konfiguracji, aby ustawić położenie tekstu względem obrazu w elemencie siatki.

Możesz skonfigurować element siatki z identyfikatorem, który jest zwracany jako parametr działania zdefiniowanego w sięci.

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 mogą obsługiwać proste formatowanie tekstu HTML. Podczas ustawiania zawartości tekstowej tych widżetów uwzględnij odpowiednie tagi HTML.

Obsługiwane tagi i ich przeznaczenie: