Widgets

Ein Widget ist ein UI-Element, das mindestens eines der folgenden Elemente bietet:

  • Struktur für andere Widgets wie Karten und Bereiche
  • Informationen für den Nutzer wie Texte und Bilder oder
  • Ermäßigungen für Aktionen wie Schaltflächen, Texteingabefelder oder Kästchen.

Widgets, die den Kartenbereichen hinzugefügt werden, definieren die gesamte Add-on-UI. Die Widgets haben sowohl auf Web- als auch auf Mobilgeräten die gleiche Darstellung und Funktion. In der Referenzdokumentation werden mehrere Methoden zum Erstellen von Widget-Sets beschrieben.

Widget-Typen

Add-on-Widgets werden im Allgemeinen in drei Gruppen unterteilt: Struktur-Widgets, Informations-Widgets und Widgets für Nutzerinteraktionen.

Strukturelle Widgets

Strukturelle Widgets bieten Container und eine Organisation für die anderen in der UI verwendeten Widgets.

  • Schaltflächensatz: Eine Sammlung aus einer oder mehreren Text- oder Bildschaltflächen, die in einer horizontalen Zeile zusammengefasst sind.
  • Karte: Eine einzelne Kontextkarte, die einen oder mehrere Kartenabschnitte enthält. Sie legen fest, wie Nutzer zwischen Karten wechseln können, indem Sie die Kartennavigation konfigurieren.
  • Kartenüberschrift: Der Titel einer bestimmten Karte. Kartenüberschriften können Titel, Unterüberschriften und ein Bild enthalten. Kartenaktionen und universelle Aktionen werden im Kartenheader angezeigt, wenn das Add-on sie verwendet.
  • Kartenbereich: Eine Sammlung von Widgets, die durch eine horizontale Regel von den anderen Kartenabschnitten getrennt sind und optional eine Abschnittsüberschrift haben. Jede Karte muss mindestens einen Kartenbereich haben. Sie können einem Kartenabschnitt keine Karten oder Kopfzeilen hinzufügen.

Strukturelle Widgets

Zusätzlich zu diesen grundlegenden strukturellen Widgets können Sie in einem Google Workspace-Add-on den Kartendienst verwenden, um Strukturen zu erstellen, die die aktuelle Karte überlappen: feste Fußzeilen und Vorschaukarten:

Sie können unten auf der Karte eine feste Reihe von Schaltflächen hinzufügen. Diese Zeile bewegt oder scrollt nicht mit dem Rest des Karteninhalts.

Beispiel für ein fixiertes Fußzeilen-Widget

Der folgende Codeauszug zeigt, wie Sie eine Beispielfußzeile definieren und einer Karte hinzufügen:

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();

Karte kurz anzeigen

Beispielkarte

Wenn neue kontextbezogene Inhalte durch eine Nutzeraktion ausgelöst werden, z. B. das Öffnen einer Gmail-Nachricht, können Sie diese entweder sofort anzeigen lassen (Standardverhalten) oder unten in der Seitenleiste eine Vorschaukarte einblenden. Wenn ein Nutzer auf „Zurück“ klickt, um zu Ihrer Startseite zurückzukehren, während ein kontextbezogener Trigger aktiv ist, wird eine Vorschaukarte eingeblendet, über die Nutzer den Kontext wieder finden können.

Fügen Sie der Klasse CardBuilder .setDisplayStyle(CardService.DisplayStyle.PEEK) hinzu, um eine Vorschaukarte anzuzeigen, wenn neuer kontextbezogener Inhalt verfügbar ist, anstatt den neuen Kontextinhalt sofort anzuzeigen. Eine Peek-Karte wird nur angezeigt, wenn mit Ihrem kontextabhängigen Trigger ein einzelnes Kartenobjekt zurückgegeben wird. Andernfalls wird die aktuelle Karte sofort durch die zurückgegebenen Karten ersetzt.

Wenn Sie den Header der Peek-Karte anpassen möchten, fügen Sie beim Erstellen der Kontextkarte die Methode .setPeekCardHeader() mit einem Standardobjekt CardHeader hinzu. Der Header der Peek-Karte enthält standardmäßig nur den Namen des Add-ons.

Beispiel für eine benutzerdefinierte Vorschaukarte

Der folgende Code, der auf der Kurzanleitung zum Google Workspace-Add-on für Cats basiert, benachrichtigt Nutzer mit einer Peek-Karte über neue kontextbezogene Inhalte und passt den Header der Peek-Karte so an, dass der Betreff des ausgewählten Gmail-Nachrichtenthreads angezeigt wird.

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);

Informations-Widgets

Informations-Widgets bieten dem Nutzer Informationen.

  • Bild: Ein Bild, das durch eine von Ihnen angegebene gehostete und öffentlich zugängliche URL angezeigt wird.
  • DecoratedText: Ein Textinhaltsstring, den Sie mit anderen Elementen wie Textlabels oben und unten und einem Bild oder Symbol kombinieren können. Dekorierte Text-Widgets können auch ein Button- oder Switch-Widget enthalten. Hinzugefügte Schalter können Ein-/Aus-Schaltflächen oder Kästchen sein. Für den Inhaltstext des Deals vom Typ „DekorierteText“ kann HTML-Formatierung verwendet werden. Die oberen und unteren Labels müssen im Klartextformat angegeben werden.
  • Textabsatz: Ein Textabsatz, der HTML-formatierte Elemente enthalten kann.

Informations-Widgets

Nutzerinteraktions-Widgets

Mithilfe von Nutzerinteraktions-Widgets kann das Add-on auf Nutzeraktionen reagieren. Sie können diese Widgets mit Aktionsantworten konfigurieren, um verschiedene Karten anzuzeigen, URLs zu öffnen, Benachrichtigungen anzuzeigen, E-Mail-Entwürfe zu verfassen oder andere Apps Script-Funktionen auszuführen. Weitere Informationen finden Sie in der Anleitung Interaktive Karten erstellen.

  • Kartenaktion: Ein Menüelement im Menü der Add-on-Kopfzeile. Das Menü in der Headerleiste kann auch Elemente enthalten, die als universelle Aktionen definiert sind und auf jeder vom Add-on definierten Karte angezeigt werden.
  • DateTime-Auswahl – Widgets, mit denen Nutzer ein Datum, eine Uhrzeit oder beides auswählen können. Weitere Informationen finden Sie unter Datums- und Uhrzeitauswahl.
  • Bildschaltfläche: Eine Schaltfläche, die statt Text ein Bild verwendet. Sie können eines von mehreren vordefinierten Symbolen oder ein öffentlich gehostetes Bild verwenden, das anhand seiner URL angegeben wird.
  • Auswahleingabe: Ein Eingabefeld, das für eine Sammlung von Optionen steht. Auswahleingabe-Widgets als Kontrollkästchen, Optionsfelder oder Drop-down-Auswahlfelder.
  • Switch: Ein Umschalt-Widget. Sie können Schalter nur in Verbindung mit einem DecoratedText-Widget verwenden. Standardmäßig werden sie als Umschalter angezeigt, Sie können jedoch festlegen, dass sie stattdessen als Kästchen angezeigt werden.
  • Textschaltfläche: Eine Schaltfläche mit einem Textlabel. Sie können eine Hintergrundfarbe für Textschaltflächen festlegen. Die Standardeinstellung ist "transparent". Sie können die Schaltfläche auch nach Bedarf deaktivieren.
  • Texteingabe: Ein Texteingabefeld. Das Widget kann Titel, Hinweistext und mehrzeiligen Text enthalten. Das Widget kann Aktionen auslösen, wenn sich der Textwert ändert.
  • Raster: Ein mehrspaltiges Layout, das eine Sammlung von Elementen darstellt. Sie können Elemente mit einem Bild, einem Titel, einem Untertitel und verschiedenen Anpassungsoptionen wie Rand- und Zuschnittsstilen darstellen.
Widget für Kartenaktionen Nutzerinteraktions-Widgets

DecoratedText Kästchen

Sie können anstelle einer Schaltfläche oder eines binären Umschalters ein DecoratedText-Widget definieren, dem ein Kästchen zugeordnet ist. Wie bei Schaltern ist der Wert des Kästchens im Aktionsereignisobjekt enthalten, das von der Methode setOnClickAction(action) an die Action übergeben wird, die an diese DecoratedText angehängt ist.

Beispiel für ein Widget mit dem angepassten Text

Der folgende Codeausschnitt zeigt, wie ein Kästchen-Widget DecoratedText definiert wird, das Sie dann einer Karte hinzufügen können:

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));

Datums- und Uhrzeitauswahl

Sie können Widgets definieren, über die Nutzer eine Uhrzeit, ein Datum oder beides auswählen können. Mit setOnChangeAction() können Sie eine Widget-Handler-Funktion zuweisen, die ausgeführt werden soll, wenn sich der Wert der Auswahl ändert.

Beispiel für eine benutzerdefinierte Vorschaukarte

Der folgende Codeausschnitt zeigt, wie Sie eine Datums- und Uhrzeitauswahl sowie eine Datums-/Uhrzeitauswahl definieren, die Sie dann einer Karte hinzufügen können:

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"));

Im Folgenden finden Sie ein Beispiel für eine Widget-Handler-Funktion zur Datums-/Uhrzeitauswahl. Dieser Handler formatiert und protokolliert einen String, der das vom Nutzer ausgewählte Datum und Uhrzeit in einem Datums-/Uhrzeitauswahl-Widget mit der ID "myDateTimePickerWidgetID" darstellt:

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);
  }
}

 

Die folgende Tabelle enthält Beispiele für die Auswahloberflächen zur Auswahl auf Computern und Mobilgeräten. Wenn diese Option ausgewählt ist, öffnet die Datumsauswahl eine monatsbasierte Kalender-UI, in der der Nutzer schnell ein neues Datum auswählen kann.

Wenn der Nutzer die Zeitauswahl auf Desktop-Geräten auswählt, wird ein Drop-down-Menü mit einer Liste von Uhrzeiten geöffnet, die in 30-Minuten-Schritten voneinander getrennt sind. Der Nutzer kann auch eine bestimmte Uhrzeit eingeben. Auf Mobilgeräten wird durch die Auswahl einer Zeitauswahl die integrierte Uhrenauswahl geöffnet.

Computer Mobilgeräte
Beispiel für die Datumsauswahl Beispiel für die mobile Datumsauswahl
Beispiel für die Auswahl der Zeitauswahl Beispiel für die Auswahl der Zeitauswahl in der mobilen Zeit

Raster

Elemente mit dem Raster-Widget in einem mehrspaltigen Layout anzeigen. Für jedes Element können ein Bild, ein Titel und eine Unterüberschrift angezeigt werden. Verwenden Sie zusätzliche Konfigurationsoptionen, um die Positionierung von Text relativ zum Bild in einem Rasterelement festzulegen.

Sie können ein Rasterelement mit einer Kennung konfigurieren, die als Parameter an die im Raster definierte Aktion zurückgegeben wird.

Beispiel für ein Raster-Widget

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"));

Textformatierung

Einige textbasierte Widgets unterstützen die einfache Textformatierung im HTML-Format. Wenn Sie den Textinhalt dieser Widgets festlegen, fügen Sie einfach die entsprechenden HTML-Tags ein.

Die unterstützten Tags und ihr Zweck sind in der folgenden Tabelle aufgeführt:

Format Beispiel Gerendertes Ergebnis
Fett "This is <b>bold</b>." Diese ist fett.
Kursiv "This is <i>italics</i>." Dies ist kursiv.
Unterstreichen "This is <u>underline</u>." Diese sind unterstrichen.
Durchgestrichen "This is <s>strikethrough</s>." Das ist eine Durchgestrichen.
Schriftfarbe "This is <font color=\"#FF0000\">red font</font>." Dies ist eine rote Schriftart.
Hyperlink "This is a <a href=\"https://www.google.com\">hyperlink</a>." Dies ist ein Hyperlink.
Uhrzeit "This is a time format: <time>2023-02-16 15:00</time>." Das ist ein Zeitformat: .
Zeilenvorschub "This is the first line. <br> This is a new line. Das ist die erste Zeile.
Dies ist eine neue Zeile.