Widgets

Ein Widget ist ein UI-Element, das mindestens eine der folgenden Funktionen bietet:

  • Struktur für andere Widgets wie Karten und Abschnitte
  • Informationen für den Nutzer, z. B. Text und Bilder, oder
  • Affordances für Aktionen wie Schaltflächen, Texteingabefelder oder Kästchen.

Die Add-on-Benutzeroberfläche wird durch die Gruppen von Widgets definiert, die den Kartenabschnitten hinzugefügt werden. Widgets sehen auf Computern und Mobilgeräten gleich aus und funktionieren auch gleich. In der Referenzdokumentation werden mehrere Methoden zum Erstellen von Widget-Sets beschrieben.

Widget-Typen

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

Struktur-Widgets

Struktur-Widgets bieten Container und Organisation für die anderen Widgets, die in der Benutzeroberfläche verwendet werden.

  • Schaltflächensatz: Eine Sammlung von einer oder mehreren Text- oder Bildschaltflächen, die in einer horizontalen Zeile gruppiert sind.
  • Karte: Eine einzelne Kontextkarte, die einen oder mehrere Kartenabschnitte enthält. Legen Sie fest, wie Nutzer zwischen Karten wechseln, indem Sie die Kartennavigation konfigurieren.
  • Kartenüberschrift: Die Überschrift für eine bestimmte Karte. Kartenüberschriften können Titel, Untertitel und ein Bild enthalten. Kartenaktionen und universelle Aktionen werden in der Kartenüberschrift angezeigt, sofern sie verwendet werden.
  • Kartenbereich: Eine Gruppe von Widgets, die durch eine horizontale Linie von anderen Kartenbereichen getrennt ist und optional eine Bereichsüberschrift hat. Jede Karte muss mindestens einen Kartenabschnitt haben. Sie können einem Kartenbereich keine Karten oder Kartenheader hinzufügen.

Beispiel für eine Karte mit Struktur-Widgets

Wenn Sie einem der Container ein Widget hinzufügen, erstellen und fügen Sie eine Kopie dieses Widgets hinzu. Wenn Sie das Widget nach dem Hinzufügen ändern, wird die Änderung nicht in der Benutzeroberfläche angezeigt. Achten Sie darauf, dass das Widget vollständig ist, bevor Sie es hinzufügen. Wenn Sie ein Widget nach dem Hinzufügen ändern möchten, müssen Sie den gesamten Kartenbereich oder die gesamte Karte neu erstellen. Weitere Informationen finden Sie unter Karten erstellen.

Zusätzlich zu diesen grundlegenden Struktur-Widgets können Sie in einem Google Workspace-Add-on den Card-Dienst verwenden, um Strukturen zu erstellen, die die aktuelle Karte überlappen: fixierte Fußzeilen und Peek-Karten:

Sie können unten auf der Karte eine feste Zeile mit Schaltflächen hinzufügen. Diese Zeile wird nicht mit dem restlichen Karteninhalt verschoben oder gescrollt.

Beispiel für ein fixes Footer-Widget

Der folgende Codeausschnitt zeigt, wie Sie eine Beispiel-Fuß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

Beispiel für eine Benachrichtigung in Form einer Übersichtskarte

Wenn neue kontextbezogene Inhalte durch eine Nutzeraktion ausgelöst werden, z. B. durch das Öffnen einer Gmail-Nachricht, können Sie die neuen kontextbezogenen Inhalte entweder sofort anzeigen (Standardverhalten) oder unten in der Seitenleiste eine Benachrichtigungskarte anzeigen. Wenn ein Nutzer auf „Zurück“  klickt, um zu Ihrer Startseite zurückzukehren, während ein kontextbezogener Trigger aktiv ist, wird eine Übersichtskarte eingeblendet, damit Nutzer die kontextbezogenen Inhalte leichter wiederfinden.

Wenn Sie eine Übersichtskarte anzeigen möchten, wenn neue kontextbezogene Inhalte verfügbar sind, fügen Sie .setDisplayStyle(CardService.DisplayStyle.PEEK) Ihrer Klasse CardBuilder hinzu. Eine Übersichtskarte wird nur angezeigt, wenn mit Ihrem kontextbezogenen Trigger ein einzelnes Kartenobjekt zurückgegeben wird. Andernfalls werden die zurückgegebenen Karten durch die aktuelle Karte ersetzt.

Wenn Sie die Kopfzeile der Übersichtskarte anpassen möchten, fügen Sie beim Erstellen der Kontextkarte die .setPeekCardHeader-Methode mit einem Standardobjekt CardHeader hinzu. Standardmäßig enthält der Header einer Peek-Karte nur den Namen Ihres Add-ons. Beispiel für eine angepasste Übersichtskarte

Basierend auf dem Google Workspace-Add-on „Cats“ – Schnellstart werden Nutzer mit dem folgenden Code über neue kontextbezogene Inhalte mit einer Übersichtskarte benachrichtigt. Außerdem wird die Kopfzeile der Übersichtskarte angepasst, um den Betreff des ausgewählten Gmail-Nachrichten-Threads anzuzeigen.

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 präsentieren dem Nutzer Informationen.

  • Bild: Ein Bild, das durch eine gehostete und öffentlich zugängliche URL angegeben wird.
  • DecoratedText: Ein String mit Textinhalten, der mit anderen Elementen wie oberen und unteren Labels sowie einem Bild oder Symbol kombiniert werden kann. DecoratedText-Widgets können auch ein Button- oder Switch-Widget enthalten. Hinzugefügte Schalter können Ein/Aus-Schalter oder Kästchen sein. Für den Inhaltstext kann HTML-Formatierung verwendet werden. Die oberen und unteren Labels müssen Nur-Text enthalten.
  • Textabsatz: Ein Textabsatz, der HTML-formatierte Elemente enthalten kann.

Beispiele für Informations-Widgets auf einer Karte

Widgets für Nutzerinteraktionen

Mit Widgets für Nutzerinteraktionen kann das Add-on auf Nutzeraktionen reagieren. Konfigurieren Sie diese Widgets mit Aktionsantworten, um verschiedene Karten anzuzeigen, URLs zu öffnen, Benachrichtigungen einzublenden, E‑Mail-Entwürfe zu erstellen oder andere Apps Script-Funktionen auszuführen. Weitere Informationen finden Sie im Leitfaden Interaktive Karten erstellen.

  • Kartenaktion: Ein Menüelement in der Menüleiste des Add-on-Headers. Das Menü in der Kopfzeile kann auch Elemente enthalten, die als universelle Aktionen definiert sind. Diese werden auf jeder Karte angezeigt, die vom Add-on definiert wird.
  • Datum/Uhrzeit-Auswahl: Mit Widgets können Nutzer ein Datum, eine Uhrzeit oder beides auswählen. Weitere Informationen finden Sie unter Datumsauswahl und Zeitauswahl.
  • Bildschaltfläche: Eine Schaltfläche, für die anstelle von Text ein Bild verwendet wird. Verwenden Sie eines von mehreren vordefinierten Symbolen oder ein öffentlich gehostetes Bild.
  • Auswahleingabe: Ein Eingabefeld, das eine Sammlung von Optionen darstellt. Auswahleingabe-Widgets werden als Kästchen, Optionsfelder oder Drop-down-Auswahlfelder dargestellt.
  • Schalter: Ein Umschalt-Widget, das mit einem DecoratedText-Widget verwendet wird. Standardmäßig werden sie als Ein/Aus-Schalter angezeigt, Sie können sie aber auch als Kästchen anzeigen lassen.
  • Textschaltfläche: Eine Schaltfläche mit einem Textlabel. Geben Sie eine Hintergrundfarbe für Textschaltflächen an (die Standardeinstellung ist transparent). Sie können die Schaltfläche bei Bedarf auch deaktivieren.
  • Texteingabe: Ein Texteingabefeld. Das Widget kann Titeltext, Hinweistext und mehrzeiligen Text enthalten. Das Widget kann Aktionen auslösen, wenn sich der Textwert ändert.
  • Raster: Ein mehrspaltiges Layout. Stellen Sie Elemente mit einem Bild, einem Titel, einem Untertitel und Anpassungsoptionen wie Rahmen- und Zuschneidestilen dar.
Beispiel für ein Menü mit Kartenaktionen Beispiele für Widgets für Nutzerinteraktionen auf einer Karte

DecoratedText Kästchen

Sie können ein DecoratedText-Widget mit einem Kontrollkästchen anstelle einer Schaltfläche oder eines binären Schalters definieren. Ähnlich wie bei Kippschaltern wird der Wert des Kästchens in das Aktionsereignisobjekt aufgenommen, das von der setOnClickAction-Methode an die Action übergeben wird, die an diese DecoratedText angehängt ist.

Beispiel für ein Checkbox-Widget mit formatiertem Text

Der folgende Codeausschnitt zeigt, wie Sie ein DecoratedText-Widget für das Kontrollkästchen definieren, das einer Karte hinzugefügt werden soll:

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

Auswahlelemente für Datum und Uhrzeit

Definieren Sie Widgets, mit denen Nutzer eine Uhrzeit, ein Datum oder beides auswählen können. Verwenden Sie setOnChangeAction, um eine Widget-Handler-Funktion zuzuweisen, die ausgeführt werden soll, wenn sich der Wert der Auswahl ändert.

Beispiel für eine angepasste Übersichtskarte

Der folgende Codeausschnitt zeigt, wie Sie eine reine Datumsauswahl, eine reine Zeitauswahl und eine Datum-/Zeitauswahl definieren, die einer Karte hinzugefügt werden sollen:

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

Das Folgende ist ein Beispiel für eine Handler-Funktion für ein Datum/Uhrzeit-Auswahl-Widget. Dieser Handler formatiert und protokolliert einen String, der das vom Nutzer in einem Datum/Uhrzeit-Auswahl-Widget mit der ID myDateTimePickerWidgetID ausgewählte Datum/die ausgewählte Uhrzeit 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/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);
  }
}

 

Die folgende Tabelle zeigt Beispiele für die Benutzeroberflächen zur Auswahl auf Computern und Mobilgeräten. Wenn diese Option ausgewählt ist, wird in der Datumsauswahl eine kalenderbasierte Benutzeroberfläche geöffnet, in der der Nutzer ein neues Datum auswählen kann.

Wenn der Nutzer auf Desktopgeräten die Zeitauswahl auswählt, wird ein Drop-down-Menü mit einer Liste von Zeiten in 30-Minuten-Schritten geöffnet. Der Nutzer kann auch eine bestimmte Uhrzeit eingeben. Auf Mobilgeräten wird durch Auswahl einer Zeitachse die integrierte mobile Zeitachse „Uhr“ geöffnet.

Computer Mobilgeräte
Beispiel für die Auswahl in der Datumsauswahl Beispiel für die Auswahl in der Datumsauswahl auf Mobilgeräten
Beispiel für die Auswahl in der Zeitauswahl Beispiel für die Auswahl der Uhrzeit in der mobilen Zeitachse

Raster

Elemente in einem mehrspaltigen Layout mit dem Raster-Widget anzeigen Für jedes Element können ein Bild, ein Titel und ein Untertitel angezeigt werden. Mit zusätzlichen Konfigurationsoptionen können Sie die Positionierung von Text relativ zum Bild in einem Gridelement festlegen.

Konfigurieren Sie ein Grid-Element mit einer Kennung, die als Parameter an die im Grid definierte Aktion zurückgegeben wird.

Beispiel für ein Raster-Widget mit Kontaktdaten

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 grundlegende HTML-Formatierung von Text. Wenn Sie den Textinhalt dieser Widgets festlegen, fügen Sie 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>." Dieser Text ist fett.
Kursiv "This is <i>italics</i>." Das ist kursiv.
Unterstrichen "This is <u>underline</u>." Das ist unterstrichen.
Durchgestrichen "This is <s>strikethrough</s>." Dieser Text ist durchgestrichen.
Schriftfarbe "This is <font color=\"#FF0000\">red font</font>." Das ist rote Schrift.
Hyperlink "This is a <a href=\"https://www.google.com\">hyperlink</a>." Dies ist ein Hyperlink.
Zeit "This is a time format: <time>2023-02-16 15:00</time>." Dies ist ein Zeitformat: .
Zeilenvorschub "This is the first line. <br> This is a new line." Dies ist die erste Zeile.
Dies ist eine neue Zeile.