Widżety

Widżet to element interfejsu, który zapewnia co najmniej jedną z tych funkcji:

• struktura innych widżetów, takich jak karty i sekcje;
• informacje dla użytkownika, takie jak tekst i obrazy, lub
• Afordancje działania, takie jak przyciski, pola do wprowadzania danych lub pola wyboru.

Zestawy widżetów dodanych do sekcji kart określają ogólny interfejs dodatku. Widżety wyglądają i działają tak samo na urządzeniach mobilnych i w internecie. W dokumentacji znajdziesz opis kilku metod tworzenia zestawów widżetów.

Typy widżetów

Widżety dodatków są zwykle podzielone na 3 grupy: widżety strukturalne, widżety informacyjne i widżety interakcji z użytkownikiem.

Widżety strukturalne

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

• Zestaw przycisków: zbiór co najmniej 1 przycisku tekstowego lub graficznego zgrupowanego w poziomym wierszu.
• Karta: pojedyncza karta kontekstowa, która zawiera co najmniej 1 sekcję karty. Określ, jak użytkownicy poruszają się 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 są używane.
• Sekcja kart: grupa widżetów oddzielona od innych sekcji kart linią poziomą i opcjonalnie zawierająca nagłówek sekcji. Każda karta musi mieć co najmniej 1 sekcję. Nie możesz dodawać kart ani nagłówków kart do sekcji kart.

Gdy dodasz widżet do jednego z kontenerów, utworzysz i dodasz jego kopię. Jeśli po dodaniu widżetu wprowadzisz w nim zmiany, nie zostaną one odzwierciedlone w interfejsie. Zanim dodasz widżet, sprawdź, czy jest kompletny. Jeśli po dodaniu widżetu chcesz go zmienić, musisz ponownie utworzyć całą sekcję karty lub kartę. Więcej informacji znajdziesz w sekcji Tworzenie kart.

Oprócz tych podstawowych widżetów strukturalnych w dodatku Google Workspace możesz używać usługi Card do tworzenia struktur, które nakładają się na bieżącą kartę: stałych stopek i kart podglądu:

Stała stopka

Możesz dodać stały wiersz przycisków u dołu karty. Ten wiersz nie przesuwa się ani nie przewija wraz z pozostałą treścią karty.

Poniższy fragment kodu pokazuje, jak zdefiniować przykładowy stały stopkę 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();

Karta Peek

Gdy nowe treści kontekstowe zostaną wywołane przez działanie użytkownika, np. otwarcie wiadomości w Gmailu, możesz wyświetlić nowe treści kontekstowe od razu (domyślne zachowanie) lub wyświetlić powiadomienie w postaci karty 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 wyzwalacz kontekstowy, pojawi się karta podglądu, która pomoże mu ponownie znaleźć treści kontekstowe.

Aby wyświetlać kartę podglądu, gdy dostępna jest nowa treść kontekstowa, dodaj .setDisplayStyle(CardService.DisplayStyle.PEEK) do klasy CardBuilder. Karta podglądu pojawi się tylko wtedy, gdy w odpowiedzi na wywołanie kontekstowe zostanie zwrócony pojedynczy obiekt karty. W przeciwnym razie zwrócone karty zastąpią bieżącą kartę.

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

Na podstawie krótkiego wprowadzenia do dodatku do Google Workspace Cats poniższy kod powiadamia użytkowników o nowych treściach kontekstowych za pomocą karty podglądu i dostosowuje nagłówek karty podglądu, 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ą użytkownikowi informacje.

• Obraz: obraz wskazany przez hostowany i dostępny publicznie adres URL.
• DecoratedText: ciąg tekstowy, który możesz połączyć z innymi elementami, takimi jak etykiety górne i dolne oraz obraz lub ikona. Widżety DecoratedText mogą też zawierać widżet Button lub Switch. Dodane przełączniki mogą być przełącznikami lub polami wyboru. Tekst treści może używać formatowania HTML, a etykiety u góry i u dołu muszą być zwykłym tekstem.
• Akapit tekstu: akapit tekstu, który może zawierać elementy sformatowane w HTML.

Widżety interakcji użytkownika

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

• Działanie karty: element menu umieszczony w menu paska nagłówka dodatku. Menu paska 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 umożliwiające użytkownikom wybór daty, godziny lub obu tych wartości. Więcej informacji znajdziesz w artykule Selektory daty i godziny.
• Przycisk z obrazem: przycisk, który zamiast tekstu używa obrazu. Użyj jednej z kilku predefiniowanych ikon lub obrazu hostowanego publicznie.
• Pole wyboru: pole do wprowadzania danych, które reprezentuje zbiór opcji. Widżety wprowadzania wyboru w postaci pól wyboru, przycisków opcji lub menu rozwijanych.
• Przełącznik: widżet przełącznika używany z widżetem DecoratedText. Domyślnie wyświetlają się one jako przełącznik, ale możesz je wyświetlać jako pole wyboru.
• Przycisk tekstowy: przycisk z etykietą tekstową. Określ kolor wypełnienia tła przycisków tekstowych (domyślnie jest przezroczysty). W razie potrzeby możesz też wyłączyć ten przycisk.
• Wprowadzanie tekstu: pole do wprowadzania danych. Widżet może zawierać tekst tytułu, tekst podpowiedzi i tekst wielowierszowy. Widżet może wywoływać działania, gdy zmieni się wartość tekstowa.
• Siatka: układ wielokolumnowy. Przedstawiaj produkty za pomocą obrazu, tytułu, podtytułu i opcji dostosowywania, takich jak obramowanie i style przycinania.

DecoratedText pola wyboru

Możesz zdefiniować widżet DecoratedText z dołączonym polem wyboru zamiast przycisku lub przełącznika binarnego. Podobnie jak w przypadku przełączników, wartość pola wyboru jest uwzględniana w obiekcie zdarzenia działania przekazywanym do Action dołączonego do tego DecoratedText przez metodę setOnClickAction.

Poniższy fragment kodu pokazuje, jak zdefiniować widżet pola wyboru DecoratedText, który można 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

Określ widżety, które umożliwiają użytkownikom wybieranie godziny, daty lub obu tych wartości. Użyj setOnChangeAction, aby przypisać funkcję obsługi widżetu, która ma być wykonywana, gdy zmieni się wartość selektora.

Poniższy fragment kodu pokazuje, jak zdefiniować selektor tylko daty, selektor tylko czasu i selektor daty i godziny, aby dodać je 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 wyboru daty i godziny. Ten procedura obsługi formatuje i rejestruje ciąg tekstowy 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/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);
  }
}

W tabeli poniżej znajdziesz przykłady interfejsów wyboru na komputerach i urządzeniach mobilnych. Po wybraniu selektora daty otworzy się interfejs kalendarza miesięcznego, w którym użytkownik może wybrać nową datę.

Gdy użytkownik wybierze selektor czasu na urządzeniu stacjonarnym, otworzy się menu z listą godzin podzielonych na 30-minutowe przedziały. Użytkownik może też wpisać konkretną godzinę. Na urządzeniach mobilnych wybranie selektora czasu otwiera wbudowany selektor czasu „zegara”.

Komputer	Urządzenia mobilne

Siatka

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

Skonfiguruj element siatki z identyfikatorem, który jest zwracany jako parametr do 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ą podstawowe formatowanie tekstu w HTML. Podczas ustawiania treści tekstowej tych widżetów uwzględnij odpowiednie tagi HTML.

Obsługiwane tagi i ich przeznaczenie znajdziesz w tej tabeli: