Widżety

Widżet to element interfejsu, który zapewnia co najmniej jeden z tych elementów:

• strukturę innych widżetów, takich jak karty i sekcje,
• informacji dla użytkownika, takich jak tekst i obrazy;
• Dodatki do działań, takie jak przyciski, pola do wprowadzania tekstu lub pola wyboru.

Zestawy widżetów dodanych do sekcji kart określają ogólny obraz interfejsu dodatku. Widżety wyglądają i działają tak samo zarówno w internecie, jak i na urządzeniach mobilnych. dokumentacja referencyjna opisuje kilka metod tworzenia zestawów widżetów.

Typy widżetów

Widżety dodatków są ogólnie podzielone na trzy kategorie: grupy: widżety strukturalne, widżety informacyjne i interaktywne.

Widżety strukturalne

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

• Button set (Zestaw przycisków) – A zbiór co najmniej jednego przycisku tekstowego lub graficznego zgrupowanego razem poziomego wiersza.
• Karta – pojedynczy kontekst zawierającą co najmniej 1 sekcję karty. Ty określasz, w jaki sposób użytkownicy mogą przenosić dane między kartami, konfigurując nawigacji po kartach.
• Nagłówek karty – w nagłówku danej karty. Nagłówki kart mogą zawierać tytuły, napisy . Działania na karcie oraz działania uniwersalne pojawiają się w: nagłówka karty, jeśli dodatek ich używa.
• Sekcja karty – A zebranej grupy widżetów, które są podzielone od innych sekcji karty przez linię poziomą i opcjonalnie nagłówek sekcji. Każda karta musi mieć co najmniej jedną sekcję karty. Nie można dodać kart ani nagłówków kart .

Poza tymi podstawowymi widżetami strukturalnymi w Dodatek do Google Workspace, którego możesz używać usługa karty, aby utworzyć struktury, które nakładają się na bieżącą kartę: poprawione stopki i karty podglądu:

Stała stopka

U dołu karty możesz dodać stały rząd przycisków. Ten wiersz nie przesuwa się ani nie przewija razem z pozostałą zawartością karty.

Poniżej pokazuje, jak zdefiniować przykładową stałą 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 podglądu

Gdy nowe treści kontekstowe jest wywoływane przez działanie użytkownika, takie jak otwarcie wiadomości w Gmailu, możesz natychmiast wyświetlić nową zawartość kontekstową (działanie domyślne) lub wyświetl powiadomienie z podglądem karty u dołu na pasku bocznym. Jeśli użytkownik kliknie Wstecz arrow_back aby wrócić na stronę główną, gdy aktywny jest wyzwalacz kontekstowy, pojawia się karta podglądu, która pomaga użytkownikom treści kontekstowych.

Aby wyświetlić kartę podglądu, gdy dostępne są nowe treści kontekstowe, zamiast natychmiast po wyświetleniu nowej treści kontekstowej, dodaj .setDisplayStyle(CardService.DisplayStyle.PEEK) na CardBuilder. zajęcia. Karta podglądu jest widoczna tylko wtedy, gdy wraz z wyzwalacz kontekstowy; w przeciwnym razie zwrócone karty natychmiast zastępują bieżącej karcie.

Aby dostosować nagłówek karty podglądu, dodaj metodę .setPeekCardHeader() za pomocą parametru standardowy CardHeader obiekt podczas tworzenia karty kontekstowej. Domyślnie nagłówek karty podglądu zawiera tylko nazwę Twojego dodatku.

Poniższy kod na podstawie Krótkie wprowadzenie do dodatku do Google Workspace Cats, powiadamia użytkowników o nowych treściach kontekstowych za pomocą karty Podgląd i dostosowuje w nagłówku karty podglądu, aby wyświetlić wybraną wiadomość z Gmaila temat wątku.

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. wskazany za pomocą przekazanego przez Ciebie adresu URL hostowanego i dostępnego publicznie.
• DecoratedText – A tekst ciąg znaków, który można łączyć z innymi elementami, takimi jak góra i dół etykiet tekstowych oraz obrazu lub ikony. Widżety decorationedText mogą też zawierać Button lub Przełącz widżet. Dodane przełączniki mogą to być przełączniki lub pola wyboru. Tekst treści widżetu Dekorowany tekst może używać Formatowanie HTML; na szczyt i dolne etykiety muszą być zwykłym tekstem.
• Akapit tekstowy – A akapitu, który może zawierać elementy HTML.

Widżety interakcji użytkownika

Widżety interakcji użytkownika pozwalają dodatkowi na reagowanie na działania wykonywane przez użytkowników. Możesz skonfigurować te widżety z odpowiedziami na działania wyświetlanie różnych kart, otwieranie adresów URL, pokazywanie powiadomień, tworzenie wersji roboczych e-maili, lub uruchamianie innych funkcji Apps Script. Zobacz Przewodnik po tworzeniu kart interaktywnych dla: .

• Działanie karty – menu. umieszczony w menu na pasku nagłówka dodatku. W menu paska nagłówka można też zawierają elementy zdefiniowane jako działania uniwersalne, widoczne na każdej karcie zdefiniowanej przez dodatek.
• Selektory daty i godziny – widżety które pozwalają użytkownikom wybrać datę, godzinę lub oba te elementy. Zobacz Selektory daty i godziny poniżej.
• Przycisk Obraz – A który zawiera obraz zamiast tekstu. Możesz użyć jednej z kilku metod, wstępnie zdefiniowanych ikon lub obrazów udostępnianych publicznie wskazanej za pomocą adresu URL.
• Dane wejściowe – pole do wprowadzania danych, które reprezentuje zbiór opcji. Widżety wyboru mogą mieć postać pól wyboru, przycisków opcji lub menu wyboru.
• Przełącz – przełącznik widżet. Przełączników możesz używać tylko w połączeniu z Widżet DecoratedText. Domyślnie to przełącznik, ale możesz skonfigurować je tak, by wyświetlały się pole wyboru.
• Przycisk Tekst – A z etykietą tekstową. Możesz określić wypełnienie kolorem tła tekstu. (domyślnie jest to przezroczyste). Możesz też wyłączyć przycisk, niezbędną.
• Pole tekstowe – tekst. pola do wprowadzania danych. Widżet może mieć tytuł, tekst podpowiedzi i tekst wielowierszowy. Widżet może uruchamiać działania po zmianie wartości tekstowej.
• Siatka – wiele kolumn. reprezentujący kolekcję elementów. Elementy te możesz reprezentować za pomocą atrybutu obraz, tytuł, podtytuł oraz wiele opcji dostosowywania, takich jak obramowanie i stylów przycinania.

Pola wyboru: DecoratedText

Możesz zdefiniować DecoratedText widżet z dołączonym polem wyboru, a nie przyciskiem czy binarnym przełącznikiem Tak jak w przypadku przełączników, wartość tego pola wyboru znajduje się w sekcji action event obiekt które jest przekazywane do funkcji Action dołączone do tego elementu DecoratedText przez setOnClickAction(action) .

Poniższy fragment kodu pokazuje, jak zdefiniować pole wyboru DecoratedText który możesz 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 definiować widżety, które pozwalają użytkownikom wybrać godzinę, datę lub oba te elementy. Za pomocą setOnChangeAction() możesz przypisać funkcję obsługi widżetu do: uruchamia się, gdy zmieni się wartość selektora.

Poniższy fragment kodu pokazuje, jak zdefiniować selektor zawierający tylko datę oraz selektor daty i godziny, który możesz 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 znajduje się przykład funkcji obsługi widżetu selektora daty i godziny. Ten modułu obsługi 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/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 selektora na komputerach i urządzeniach mobilnych urządzenia. Wybranie tej opcji spowoduje, że selektor dat będzie otwierał interfejs kalendarza dla danego miesiąca, aby umożliwić użytkownik może szybko wybrać nową datę.

Gdy użytkownik wybierze selektor czasu na komputerze, otworzy się menu z listą czasów rozdzielonych co 30 minut, które użytkownik może wybrać . Użytkownik może też wpisać konkretną godzinę. Na urządzeniu mobilnym wybranie selektor godziny otwiera wbudowany mobilny „zegar” .

Komputer	Urządzenia mobilne

Siatka

Wyświetlaj elementy w układzie wielokolumnowym z widżetem siatki. Każdy element może wyświetlić obraz, tytuł i podtytuł. Użyj dodatkowych opcji konfiguracji, aby ustaw położenie tekstu względem obrazu w elemencie siatki.

Możesz skonfigurować element siatki o identyfikatorze, 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 mogą obsługiwać proste formatowanie tekstowe HTML. Podczas ustawiania zawartość tekstową tych widżetów, wystarczy dodać odpowiednie tagi HTML.

Obsługiwane tagi i ich przeznaczenie znajdziesz poniżej tabela: