Ta strona została przetłumaczona przez Cloud Translation API.

Widżety

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

Struktura innych widżetów, takich jak karty i sekcje,
Informacje dla użytkownika, takie jak tekst i obrazy;
środki do działania, takie jak przyciski, pola do wprowadzania tekstu lub pola wyboru;

Zestawy widżetów dodanych do sekcji kart definiują ogólny interfejs dodatku. Widżety mają ten sam wygląd i funkcje zarówno na stronach internetowych, jak i na urządzeniach mobilnych. W dokumentacji referencyjnej opisaliśmy kilka metod tworzenia zestawów widżetów.

Użyj zestawu dodatków do Google Workspace

Aby zaoszczędzić czas podczas projektowania widżetów dodatków, projektanci mogą skorzystać z zestawu elementów interfejsu dodatków do Google Workspace dostępnego na Figma. Możesz utworzyć konto Figma lub poprosić o licencję administratora organizacji.

Możesz przeglądać komponenty i używać szablonów do tworzenia i wizualizowania widżetów.

Pobierz zestaw projektowy

Typy widżetów

Widżety dodatków są podzielone na 3 grupy: widżety strukturalne, widżety informacyjne i interakcje użytkowników.

Widżety strukturalne

Widżety strukturalne to kontenery i porządek na potrzeby innych widżetów używanych w sztucznej inteligencji.

Widżety strukturalne

Zestaw przycisków – zbiór zawierający co najmniej 1 przycisk tekstu lub obrazu zgrupowany w poziomym wierszu.
Karta – karta kontekstu zawierająca co najmniej 1 sekcję karty. Możesz określić, w jaki sposób użytkownicy mogą przechodzić między kartami, konfigurując nawigację po kartach.
Nagłówek karty – nagłówek danej karty. Nagłówki kart mogą mieć tytuły, napisy 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 podzielona przez inne sekcje karty za pomocą poziomej reguły, opcjonalnie z nagłówkiem nagłówka. Każda karta musi mieć co najmniej 1 sekcję. Do sekcji nie można dodawać kart.

Oprócz tych podstawowych widżetów strukturalnych w dodatku do Google Workspace możesz korzystać z usługi kart, aby tworzyć struktury pokrywające się z bieżącą kartą: stałe stopki i karty podglądu:

Stała stopka

Teraz możesz dodać stały rząd przycisków na dole karty. Ten wiersz nie przesuwa się ani nie przewija razem z resztą treści karty. Ten fragment kodu pokazuje, jak zdefiniować przykładową stałą stopkę i dodać ją do karty:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();

Karta podglądu

Przykład karty podglądu

Gdy użytkownik wywoła nowe treści kontekstowe, na przykład otworzy wiadomość w Gmailu, możesz wyświetlić nowe treści kontekstowe od razu (ustawienie domyślne) lub wyświetlić powiadomienie karty u dołu paska bocznego. Jeśli użytkownik kliknie przycisk Wstecz , aby wrócić na stronę główną, gdy aktywna jest reguła kontekstowa, pojawi się karta podglądu, która ułatwi im ponowne znalezienie treści.

Aby wyświetlić podgląd, gdy dostępne będą nowe treści kontekstowe, zamiast natychmiast wyświetlać nowe treści kontekstowe, dodaj .setDisplayStyle(CardService.DisplayStyle.PEEK) do klasy CardBuilder. Karta podglądu jest widoczna tylko wtedy, gdy pojedynczy obiekt karty jest zwracany przez aktywator kontekstowy. 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() za pomocą standardowego obiektu CardHeader. Domyślnie nagłówek karty Peek zawiera tylko nazwę dodatku.

Ten kod, który powstał na podstawie krótkiego wprowadzenia do Google Workspace dodatku Cats Google Workspace, powiadamia użytkowników o nowych treściach kontekstowych za pomocą karty Peek i dostosowuje jej nagłówek tak, aby był wyświetlany temat tego wątku wiadomości.

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 prezentują informacje użytkownikowi.

Image – obraz wskazywany przez hostowany i dostępny publicznie adres URL.
Dekorowany tekst – ciąg tekstowy, który można połączyć z innymi elementami, takimi jak etykiety tekstowe u góry i u dołu, oraz obraz lub ikona. Widżety DekorowaneTeksty mogą też mieć widżet Przycisk lub Przełącz. Dodane przełączniki mogą być prostymi przełącznikami lub polami wyboru. Tekst zawartości widżetu „Dekorowany tekst” może korzystać z formatu HTML, a etykiety górne i dolne – tylko zwykłego tekstu.
Akapit tekstowy – prosty akapit, który może zawierać elementy sformatowane w HTML-u.

Widżety interakcji użytkownika

Widżet akcji karty

Widżety interakcji użytkowników pozwalają na dodatek reagować na działania użytkowników. Możesz skonfigurować te widżety z odpowiedziami na działanie, aby wyświetlać różne karty, otwierać adresy URL, pokazywać powiadomienia, tworzyć e-maile w wersji roboczej lub uruchamiać inne funkcje Apps Script. Więcej informacji znajdziesz w przewodniku po tworzeniu interaktywnych kart.

Widżety interakcji użytkownika

Karta – pozycja menu umieszczona w menu nagłówka dodatku. Menu paska nagłówka może też zawierać elementy zdefiniowane jako działania uniwersalne widoczne na każdej karcie zdefiniowanej przez dodatek.
Selektory daty i godziny – widżety umożliwiające użytkownikom wybranie daty, godziny lub obu tych opcji. Więcej informacji znajdziesz poniżej w sekcji selektory daty i godziny.
Przycisk obrazu – przycisk, który zamiast obrazu zawiera obraz. Możesz użyć jednej z kilku wstępnie zdefiniowanych ikon lub obrazu przechowywanego publicznie na podstawie adresu URL.
Pole wyboru – pole wejściowe reprezentujące zbiór opcji. Widżety do wprowadzania danych prezentowane jako pola wyboru, przyciski i pola z menu.
Switch – widżet przełącznika. Przełączników możesz używać tylko w połączeniu z widżetem decorationedText. Domyślnie są one wyświetlane jako przełącznik, ale mogą powodować wyświetlanie ich jako pola wyboru.
Przycisk tekstowy – przycisk z etykietą tekstową. Możesz określić kolor wypełnienia przycisków tekstowych (wartość domyślna to przezroczysta). W razie potrzeby możesz też wyłączyć przycisk.
Pole tekstowe – pole do wprowadzania tekstu. Widżet może zawierać tekst tytułu, podpowiedzi i wielowierszowy tekst. Widżet może uruchamiać działania w przypadku zmiany wartości tekstu.
Siatka – wielokolumnowy układ reprezentujący zbiór elementów. Możesz podawać elementy z obrazem, tytułem, podtytułem i różnymi opcjami dostosowywania, takimi jak obramowanie i style przycinania.

Pole wyboru Dekorowanego tekstu

Zamiast przełącznika lub przycisku binarnego możesz zdefiniować widżet DecoratedText z zaznaczonym polem wyboru. Tak jak w przypadku przełączników, wartość pola wyboru jest zawarta w obiekcie zdarzenia czynności, który jest przekazywany do Action dołączonego do DecoratedText przy użyciu metody setOnClickAction(action).

Ten fragment kodu pokazuje, jak zdefiniować widżet pola wyboru DecoratedText, 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));

Przykład widżetu z zaznaczonym polem tekstowym

Selektory daty i godziny

Możesz zdefiniować widżety pozwalające użytkownikom wybrać godzinę, datę lub jedno i drugie. Za pomocą setOnChangeAction() możesz przypisać funkcję modułu obsługi widżetu do wykonania, gdy zmieni się wartość selektora.

Fragment kodu poniżej pokazuje, jak zdefiniować selektor tylko daty, selektor daty i godziny oraz selektor daty i godziny, który możesz dodać na karcie:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter the 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 the 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 the date and time in EDT 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 podano przykład funkcji obsługi widżetu wyboru daty i godziny. Ta funkcja tylko 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. Po wybraniu tej opcji selektor dat otwiera miesięczny kalendarz, który pozwala użytkownikom szybko wybrać nową datę.

Gdy użytkownik wybierze selektor czasu na komputerach, otworzy się menu z listą godzin oddzielonych co 30 minut, które użytkownik może wybrać. Użytkownik może też wpisać konkretną godzinę. Na urządzeniach mobilnych możesz wybrać wbudowany selektor czasu na zegarze.

Komputery	Urządzenia mobilne

Siatka

Wyświetlaj elementy w układzie obejmującym wiele kolumn za pomocą widżetu siatki. Każdy element może wyświetlać 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 określonego w siatce.

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.SQUARE);

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));

Formatowanie tekstu

Niektóre widżety tekstowe obsługują proste formatowanie tekstu HTML. Ustawiając zawartość tekstową tych widżetów, wystarczy dołączyć odpowiednie tagi HTML. Obsługiwane są te formaty:

Format	Przykład	Wyrenderowany wynik
pogrubienia,	`<b>test</b>`	test
kursywy,	`<i>test</i>`	test
Podkreślenie	`<u>test</u>`	test
Przekreślenie	`<s>test</s>`	~~test~~
Kolor czcionki	`<font color="#ea9999">test</font>`	test
Hiperlink	`<a href="http://www.google.com">google</a>`	google
Godzina	`<time>2020-02-16 15:00</time>`	16.02.2020 15:00
Nowy wiersz	`test <br> test`	test test