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

Widżety

Widżet to prosty element interfejsu, który zapewnia 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;
Obszary działania, takie jak przyciski, pola do wprowadzania tekstu czy pola wyboru.

Zestawy widżetów dodanych do sekcji kart definiują ogólny interfejs użytkownika dodatku. Widżety mają ten sam wygląd i działanie zarówno na stronach internetowych, jak i na urządzeniach mobilnych. W dokumentacji znajdziesz 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 dodatków do interfejsu Google Workspace w interfejsie użytkownika dostępnego na Figma. Możesz utworzyć konto Figma lub poprosić o licencję administratora organizacji.

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

Pobierz pakiet projektowy

Typy widżetów

Widżety dodatkowe są zasadniczo podzielone na 3 grupy: widżety strukturalne, widżety informacyjne oraz widżety interakcji użytkowników.

Widżety strukturalne

Widżety strukturalne udostępniają kontenery i organizacje innych widżetów używanych w AI.

Widżety strukturalne

Zbiór przycisków – zbiór zawierający co najmniej 1 przycisk tekstu lub obrazu zgrupowany w wierszu poziomym.
Karta – pojedyncza karta kontekstowa, która zawiera co najmniej 1 sekcję kart. Aby dowiedzieć się, jak użytkownicy mogą poruszać się między kartami, skonfiguruj nawigację po kartach.
Nagłówek karty – nagłówek danej karty. Nagłówki kart mogą zawierać tytuły, napisy i obraz. Działania karty 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 pozostałe sekcje karty za pomocą poziomej reguły i (opcjonalnie) nagłówka sekcji. Każda karta musi mieć co najmniej 1 sekcję. Do sekcji nie można dodawać kart ani nagłówków.

Oprócz tych podstawowych widżetów strukturalnych, w dodatku Google Workspace możesz użyć usługi Karty, aby utworzyć struktury, które nakładają się na 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 wraz z pozostałą treścią karty. Z tego fragmentu kodu dowiesz się, jak zdefiniować przykładową stopkę stałą 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();

Podgląd karty

Przykładowy podgląd karty

Po wywołaniu działania użytkownika przez nowe treści kontekstowe takie jak otwarcie wiadomości w Gmailu możesz wyświetlić nową zawartość kontekstową (ustawienie domyślne) lub wyświetlić powiadomienie karty podglądu u dołu paska bocznego. Jeśli użytkownik kliknie Wstecz , aby wrócić na stronę główną, gdy aktywny jest kontekst kontekstowy, wyświetli mu się karta, która pomoże im ponownie znaleźć treści kontekstowe.

Jeśli chcesz wyświetlić podgląd, gdy pojawią się nowe treści kontekstowe, zamiast dodawać je od razu, dodaj .setDisplayStyle(CardService.DisplayStyle.PEEK) do klasy CardBuilder. Karta podglądu jest widoczna tylko wtedy, gdy wraz z kontekstem zwrotnym zostanie zwrócony pojedynczy obiekt karty. W przeciwnym razie zwracane 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, oparty na krótkim wprowadzeniu do kotów Google Workspace, powiadamia użytkowników o nowych treściach kontekstowych za pomocą karty Peek i dostosowuje jej nagłówek, 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 prezentują informacje użytkownikowi.

Obraz – obraz zdefiniowany przez hostowany i publicznie dostępny URL.
decorationedText – ciąg tekstowy, który można połączyć z innymi elementami, takimi jak etykiety tekstowe na górze i na dole, oraz obraz lub ikona. Widżety DekorowaneTekst mogą też zawierać widżet Przycisk lub Przełącz. Dodane przełączniki mogą zawierać proste przełączniki lub pola wyboru. Tekst zawartości widżetu Dekorowany tekst może korzystać z formatu HTML. Etykiety górna i dolna muszą używać zwykłego tekstu.
Akapit z tekstem – prosty akapit zawierający elementy sformatowane w HTML.

Widżety interakcji użytkowników

Widżet akcji

Widżety interakcji użytkowników pozwalają dodatku reagować na działania użytkowników. Te widżety możesz tak skonfigurować, aby pokazywały różne karty, otwierały różne adresy URL, pokazywały powiadomienia, tworzyły wersje robocze e-maili lub korzystały z innych funkcji Apps Script. Więcej informacji znajdziesz w przewodniku dotyczącym tworzenia interaktywnych kart.

Widżety interakcji użytkowników

Działanie karty – pozycja menu umieszczona w menu paska nagłówka dodatku. Menu na pasku nagłówka może też zawierać elementy zdefiniowane jako działania uniwersalne wyświetlane na każdej karcie zdefiniowanej przez dodatek.
Selektory daty i godziny – widżety pozwalające użytkownikom wybrać datę, godzinę lub oba te elementy. Więcej informacji znajdziesz poniżej w sekcji Selektory daty i godziny.
Przycisk Obraz – przycisk, który zamiast obrazu zawiera obraz. Możesz użyć jednej ze wstępnie zdefiniowanych ikon lub publicznie dostępnych obrazów wskazywanych przez ich adresy URL.
Pole wyboru – pole wejściowe reprezentujące zbiór opcji. Widżety do wprowadzania tekstu zaznaczone jako pola wyboru, przyciski lub menu wyboru.
Switch (Przełącz) – widżet przełączania. Przełączników możesz używać tylko w połączeniu z widżetem ozdobnego tekstu. Domyślnie wyświetlają się jako przełączniki, ale mogą sprawić, że będą wyświetlane jako pole wyboru.
Przycisk tekstowy – przycisk z etykietą tekstową. Możesz określić kolor tła tła przycisków (wartość domyślna to przezroczysta). W razie potrzeby możesz też wyłączyć ten przycisk.
Wpisywanie tekstu – pole do wprowadzania tekstu. Widżet może zawierać tekst tytułu, tekst podpowiedzi oraz tekst wielowierszowy. Widżet może wywoływać działania po zmianie wartości tekstowej.
Siatka – wielokolumnowy układ reprezentujący kolekcję elementów. Możesz przedstawić elementy z obrazem, tytułem, podtytułem i różnymi opcjami dostosowywania, takimi jak obramowanie i style przycinania.

Pola dekorowanego tekstu

Zamiast przełącznika lub przycisku binarnego możesz określić widżet DecoratedText z dołączonym polem wyboru. Tak jak w przypadku przełączników, wartość pola wyboru jest uwzględniana w obiekcie zdarzenia działania przekazywanym do elementu Action dołączonego do metody DecoratedText za pomocą metody setOnClickAction(action).

Poniższy 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 pola wyboru tekstu dekorowanego

Selektory daty i godziny

Możesz zdefiniować widżety umożliwiające użytkownikom wybór godziny, daty lub obu opcji. Za pomocą setOnChangeAction() możesz przypisać funkcję obsługi widżetu, która będzie uruchamiana w przypadku zmiany wartości selektora.

Poniższy fragment kodu pokazuje, jak zdefiniować selektor tylko daty, selektor daty i godziny oraz dodać go do karty:

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 znajdziesz przykład funkcji modułu obsługi selektora daty i godziny. Ta aplikacja po prostu formatuje i rejestruje ciąg znaków reprezentujący datę i godzinę wybrany 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 to zrobisz, selektor daty otworzy interfejs kalendarza, który pozwoli użytkownikom szybko wybrać nową datę.

Gdy użytkownik wybierze selektor czasu na komputerach, pojawi się menu z listą przedziałów czasowych w 30-minutowych odstępach czasu, które może wybrać. Użytkownik może też wpisać konkretną godzinę. Na urządzeniach mobilnych wbudowany selektor godziny na zegarze.

Komputery	Urządzenia mobilne

Siatka

Wyświetlaj elementy w układzie wielokolumnowym z widżetem siatki. Każdy element może wyświetlać obraz, tytuł i podtytuł. Za pomocą dodatkowych opcji konfiguracji możesz 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 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 HTML tekstu. Ustawiając zawartość tekstową tych widżetów, dołącz po prostu odpowiednie tagi HTML.

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

Format	Przykład	Wyrenderowany wynik
pogrubienia,	`"This is <b>bold</b>."`	To jest pogrubione.
Kursywa	`"This is <i>italics</i>."`	Jest to kursywa.
Podkreślenie	`"This is <u>underline</u>."`	To jest podkreślenie.
Przekreślenie	`"This is <s>strikethrough</s>."`	Jest to ~~przekreślenie~~.
Kolor czcionki	`"This is <font color=\"#FF0000\">red font</text>."`	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>."`	Użyj formatu daty: 2023-05-10 15:00.
Nowy wiersz	`"This is the first line. <br> This is a new line.`	To jest pierwszy wiersz. To jest nowy wiersz.