Diese Seite wurde von der Cloud Translation API übersetzt.

Widgets

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

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.

Gruppen von Widgets, die den Kartenbereichen hinzugefügt werden, definieren die gesamte Add-on-UI. Das Aussehen und die Funktion der Widgets sind auf Web- und Mobilgeräten identisch. In der Referenzdokumentation werden mehrere Methoden zum Erstellen von Widget-Sets beschrieben.

Add-on-Widgets werden im Allgemeinen in drei Gruppen unterteilt: Struktur-Widgets, Informations-Widgets und Nutzerinteraktions-Widgets.

Strukturelle Widgets

Struktur-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 gruppiert 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.
Kartenkopf: Der Header für eine bestimmte Karte. Kartenheader können Titel, Untertitel und ein Bild enthalten. Kartenaktionen und universelle Aktionen werden im Kartenheader angezeigt, wenn sie vom Add-on verwendet werden.
Kartenbereich: Eine gesammelte Gruppe von Widgets, die durch eine horizontale Regel von den anderen Kartenabschnitten getrennt sind und optional eine Abschnittsüberschrift haben. Jede Karte muss mindestens einen Kartenabschnitt haben. Sie können einem Kartenabschnitt keine Karten oder Kopfzeilen hinzufügen.

Strukturelle Widgets

Zusätzlich zu diesen grundlegenden Struktur-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 Peek-Karten:

Korrigierte Fußzeile

Sie können jetzt am unteren Rand Ihrer Karte eine feste Reihe von Schaltflächen hinzufügen. Diese Zeile bewegt oder scrollt nicht mit dem Rest des Karteninhalts. 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();

Beispiel für ein Widget mit fester Fußzeile

Karte kurz anzeigen

Beispiel für Karte „Peek“

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

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

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.

Der folgende Code basiert auf der Kurzanleitung zum Cats Google Workspace-Add-on. Er informiert Nutzer über neue kontextbezogene Inhalte mit einer Peek-Karte und passt den Header der Peek-Karte so an, dass der Betreff der 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);

Beispiel für eine benutzerdefinierte Karte

Informations-Widgets

Informations-Widgets präsentieren dem Nutzer Informationen.

Bild: Ein Bild, das durch eine von Ihnen bereitgestellte gehostete und öffentlich zugängliche URL gekennzeichnet ist.
DecoratedText: Ein Textinhaltsstring, den Sie mit anderen Elementen wie Textlabels oben und unten sowie einem Bild oder Symbol kombinieren können. „DekorierteText“-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 dekoriertenText-Widgets kann die HTML-Formatierung verwendet werden. Für die Labels oben und unten muss reiner Text verwendet werden.
Textabsatz: Ein Textabsatz, der HTML-formatierte Elemente enthalten kann.

Informations-Widgets

Widgets für Nutzerinteraktionen

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, auf der statt Text ein Bild verwendet wird. Sie können eines von mehreren vordefinierten Symbolen oder ein öffentlich gehostetes Bild verwenden, das durch seine URL angegeben wird.
Auswahleingabe: Ein Eingabefeld, das eine Sammlung von Optionen darstellt. Auswahl-Widgets werden als Kästchen, Optionsfelder oder Drop-down-Auswahlfelder angezeigt.
Wechseln: Ein Ein-/Aus-Schaltflächen-Widget. Sie können Schalter nur in Verbindung mit einem DecoratedText-Widget verwenden. Standardmäßig werden diese Optionen als Ein-/Aus-Schaltfläche angezeigt. Sie können sie aber auch als Kästchen einblenden lassen.
Textschaltfläche: Eine Schaltfläche mit einem Textlabel. Für Textschaltflächen kannst du eine Hintergrundfarbe festlegen. Die Standardeinstellung ist "Transparent". Sie können die Schaltfläche auch nach Bedarf 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, das eine Sammlung von Elementen darstellt. Sie können Elemente mit einem Bild, einem Titel, einem Untertitel und einer Reihe von Anpassungsoptionen wie Rahmen- und Zuschnittsstilen darstellen.

`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 in dem Aktionsereignisobjekt enthalten, das von der Methode setOnClickAction(action) an die Action übergeben wird, die an diese DecoratedText angehängt ist.

Der folgende Codeauszug zeigt, wie ein Kästchen DecoratedText-Widget 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));

Beispiel für ein Widget für ein Kästchen mit dekoriertem Text

Datums- und Uhrzeitauswahl

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

Der folgende Codeauszug zeigt, wie Sie eine Nur-Datumsauswahl, eine Nur-Uhrzeitauswahl und 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 einfach 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 zeigt Beispiele für Auswahl-UIs auf Computern und Mobilgeräten. Bei Auswahl dieser Option öffnet die Datumsauswahl eine monatsbasierte Kalender-UI, in der der Nutzer schnell ein neues Datum auswählen kann.

Wenn der Nutzer auf Desktop-Geräten die Zeitauswahl auswählt, wird ein Drop-down-Menü mit einer in 30-Minuten-Schritten getrennten Liste geöffnet, aus der der Nutzer auswählen kann. Der Nutzer kann auch eine bestimmte Uhrzeit eingeben. Auf Mobilgeräten wird durch Auswahl einer Zeitauswahl die integrierte Zeitauswahl für die Uhr geöffnet.

Computer	Mobilgeräte

Raster

Zeigt Elemente mit dem Raster-Widget in einem mehrspaltigen Layout an. Für jedes Element können ein Bild, ein Titel und ein Untertitel 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.

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 Text-HTML-Formatierung. Fügen Sie beim Festlegen des Textinhalts dieser Widgets 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>."`	Diese ist kursiv.
Unterstreichen	`"This is <u>underline</u>."`	Dieser Text ist unterstrichen.
Durchstreichen	`"This is <s>strikethrough</s>."`	Dies ist ~~durchgestrichen~~.
Schriftfarbe	`"This is <font color=\"#FF0000\">red font</font>."`	Dies ist eine 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: 2023-02-16 15:00.
Zeilenvorschub	`"This is the first line. <br> This is a new line.`“	Das ist die erste Zeile. Dies ist eine neue Zeile.

Widgets

Widget-Typen

Strukturelle Widgets

Korrigierte Fußzeile

Karte kurz anzeigen

Informations-Widgets

Widgets für Nutzerinteraktionen

DecoratedText Kästchen

Datums- und Uhrzeitauswahl

Raster

Textformatierung

`DecoratedText` Kästchen