Widżety

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

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

  • Struktura innych widżetów, na przykład kart i sekcji;
  • Informacje dla użytkownika, takie jak tekst i obrazy;
  • Czynności, takie jak przyciski, pola wprowadzania tekstu lub 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 funkcjonalność zarówno na stronach internetowych, jak i na urządzeniach mobilnych. W dokumentacji referencyjnej opisujemy kilka metod tworzenia zestawów widżetów.

Używanie zestawu dodatków do Google Workspace

Aby zaoszczędzić czas podczas projektowania dodatków, projektanci mogą użyć zestawu dodatków do Google Workspace dostępnego w Figma. Możesz utworzyć konto Figma lub poprosić o licencję od administratora organizacji.

Możesz przeglądać komponenty i używać wbudowanych szablonów, aby tworzyć i wizualizować widżety.

Uzyskaj pakiet projektowy

Typy widżetów

Widżety dodatkowe dzielą się na 3 grupy: widżety strukturalne, widżety informacyjne i widżety do interakcji z użytkownikiem.

Widżety strukturalne

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

Widżety strukturalne

  • Zestaw przycisków – zbiór co najmniej jednego przycisku tekstowego lub graficznego pogrupowanego w poziomie.
  • Karta – pojedyncza karta kontekstowa zawierająca co najmniej 1 sekcję karty. Możesz określać, jak użytkownicy mogą poruszać się 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 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 inne sekcje karty na poziomą regułę i opcjonalnie nagłówek sekcji. Każda karta musi mieć co najmniej 1 sekcję. Do sekcji nie można dodawać kart.

Oprócz podstawowych widżetów strukturalnych w dodatku Google Workspace możesz użyć usługi kart, aby utworzyć struktury, które pokrywają się z bieżącą kartą: stałe stopki i karty podglądu:

Teraz możesz dodać stały rząd przycisków na dole karty. Ten wiersz nie jest przenoszony ani przewijany razem z resztą treści karty. Poniższy 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();
      

 

Przykład widżetu z stałą stopką

Karta Peek Card

Przykład karty Peek Card

Gdy użytkownik wywoła działanie kontekstowe, np. otwiera wiadomość w Gmailu, może wyświetlić ją natychmiast (działanie domyślne) lub wyświetlić powiadomienie na karcie w dolnej części paska bocznego. Jeśli użytkownik kliknie Wstecz , aby wrócić na stronę główną w czasie, gdy reguła kontekstowa będzie aktywna, pojawi się karta podglądu, która ułatwia użytkownikom znalezienie treści kontekstowych.

Aby wyświetlić podgląd karty, gdy pojawią się nowe treści kontekstowe, zamiast natychmiast wyświetlać nowe treści kontekstowe, dodaj .setDisplayStyle(CardService.DisplayStyle.PEEK) do klasy CardBuilder. Karta pionowa wyświetla się tylko wtedy, gdy obiekt z kontekstem zwróci pojedynczą kartę. W przeciwnym razie zwrócone karty natychmiast zastępują bieżącą.

Aby dostosować nagłówek karty Peek, dodaj metodę .setPeekCardHeader() za pomocą standardowego obiektu CardHeader podczas tworzenia karty kontekstowej. Domyślnie nagłówek karty Peek zawiera tylko nazwę dodatku.

Ten kod, oparty na krótkim wprowadzeniu do Google Workspace dotyczącym kotów, powiadamia użytkowników o nowych treściach kontekstowych za pomocą karty Peek i dostosowuje nagłówek karty Peek tak, aby wyświetlić wybrany wątek 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);
      

 

Przykład dostosowanej karty szybkim

Widżety informacyjne

Widżety informacyjne

Widżety informacyjne prezentują informacje użytkownikowi.

  • Obraz – obraz wskazywany przez podany przez Ciebie hostowany i publicznie dostępny adres URL.
  • DekorowaneTeksty – ciąg tekstowy, który można połączyć z innymi elementami, takimi jak etykiety tekstowe u góry i na dole, oraz obraz lub ikonę. Widżety decorationedText mogą też mieć widżet Przycisk lub Przełącz. Dodane przełączniki mogą być prostym przełącznikiem lub polem wyboru. Tekst zawartości widżetu ozdobionego może korzystać z formatowania HTML. Etykiety górne i dolne muszą być zapisane zwykłym tekstem.
  • Akapit tekstowy – prosty akapit tekstu, który może zawierać elementy sformatowane w HTML.




Widżety interakcji użytkowników

Widżet działań na karcie

Widżety interakcji użytkowników umożliwiają reagowanie na działania podejmowane przez użytkowników. Możesz skonfigurować te widżety z odpowiedziami na działanie, aby wyświetlać różne karty, otwierać adresy URL, wyświetlać powiadomienia, tworzyć wersje robocze e-maili lub uruchamiać inne funkcje Apps Script. Więcej informacji znajdziesz w przewodniku Tworzenie kart interaktywnych.

Widżety interakcji użytkowników

  • Karta – działanie – element menu umieszczony w menu paska nagłówka dodatku. Menu na pasku 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 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 korzystający z obrazu, a nie z tekstu. Możesz użyć jednej z kilku wstępnie zdefiniowanych ikon lub obrazu przechowywanego publicznie, którego URL wskazuje.
  • Pole wyboru – pole do wprowadzania danych reprezentujące różne opcje. Widżety wprowadzania danych w postaci pól wyboru, przycisków opcji lub rozwijanych pól.
  • Switch – widżet przełączania Przełączników możesz używać tylko w połączeniu z widżetem Dekorowany tekst. Domyślnie są one wyświetlane jako przełącznik, ale możesz ich użyć jako pola wyboru.
  • Przycisk tekstowy – przycisk z etykietą tekstową. Możesz określić kolor tła przycisków przycisków tekstowych (domyślnie jest przezroczysty). W razie potrzeby możesz też wyłączyć ten przycisk.
  • Pole tekstowe – pole do wprowadzania tekstu. Widżet może zawierać tekst tytułu, podpowiedzi oraz wielowierszowy. Widżet może wywoływać działania w przypadku zmiany wartości tekstowej.
  • Siatka – układ wielokolumnowy reprezentujący zbiór elementów. Możesz reprezentować elementy obrazu, tytułu, podtytułu oraz różnych opcji dostosowywania, np. obramowania i stylów przycinania.

Pole wyboru „Dekorowany tekst”

Zamiast przełącznika przycisku lub przełącznika binarnego możesz zdefiniować widżet DecoratedText zawierający dołączone pole wyboru. Tak jak w przypadku przełączników, pole wyboru jest zawarte w obiekcie zdarzenia czynności przekazywanego do 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 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 z tekstem

Selektory daty i godziny

Możesz zdefiniować 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 wykonania, gdy wartość selektora się zmieni.

Poniższy fragment kodu pokazuje, jak zdefiniować selektor daty i godziny oraz selektor daty i godziny, które możesz dodać 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"));
      

 

Przykład dostosowanej karty szybkim

Poniżej podano przykład funkcji obsługi widżetu selektora daty i godziny. Ten moduł obsługuje tylko format i rejestruje ciąg znaków reprezentujący 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 interfejsu wyboru selektora na komputerach i urządzeniach mobilnych. Po wybraniu tej opcji selektor dat otworzy miesięczny interfejs kalendarza, aby użytkownik mógł szybko wybrać nową datę.

Gdy użytkownik wybierze selektor czasu na komputerze, otworzy się menu z listą godzin rozdzielonych w 30-minutowych odstępach. Użytkownik może również wpisać konkretną godzinę. Na urządzeniach mobilnych wybór selektora czasu powoduje otwarcie wbudowanego selektora &mobilnego zegara.

Komputery Urządzenia mobilne
przykład selektora dat przykład selektora selektora urządzeń mobilnych
przykład wyboru selektora czasu przykład selektora selektora urządzeń mobilnych

Siatka

Wyświetlaj elementy w kolumnie z wieloma kolumnami za pomocą widżetu 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 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"));
      

 

Przykład widżetu siatki

Formatowanie tekstu

Niektóre widżety tekstowe mogą obsługiwać proste formatowanie HTML tekstu. Przy ustawianiu treści tekstowej tych widżetów wystarczy dołączyć odpowiednie tagi HTML. Obsługiwane są te formaty:

Format Przykład Renderowany wynik
pogrubienia, <b>test</b> test
Kursywa <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
Czas <time>2020-02-16 15:00</time> 16.02.2020 15:00
Nowy wiersz test <br> test test