Widget

Un widget è un elemento dell'interfaccia utente che fornisce uno o più dei seguenti elementi:

• Struttura per altri widget, come schede e sezioni,
• Informazioni per l'utente, come testo e immagini, oppure
• Opportunità di azione, come pulsanti, campi di immissione di testo o caselle di controllo.

Gli insiemi di widget aggiunti alle sezioni delle schede definiscono l'interfaccia utente complessiva del componente aggiuntivo. I widget hanno lo stesso aspetto e la stessa funzionalità sia sui dispositivi web che su quelli mobili. La documentazione di riferimento descrive diversi metodi per creare set di widget.

Tipi di widget

I widget dei componenti aggiuntivi sono generalmente classificati in tre gruppi: widget strutturali, widget informativi e widget di interazione con l'utente.

Widget strutturali

I widget di struttura forniscono contenitori e organizzazione per gli altri widget utilizzati nell'interfaccia utente.

• Serie di pulsanti: un insieme di uno o più pulsanti di testo o immagine raggruppati in una riga orizzontale.
• Scheda: una singola scheda di contesto che contiene una o più sezioni della scheda. Puoi definire in che modo gli utenti possono muoversi tra le schede configurando la navigazione tra le schede.
• Intestazione scheda: l'intestazione di una determinata scheda. Le intestazioni delle schede possono avere titoli, sottotitoli e un'immagine. Le azioni della scheda e le azioni universali vengono visualizzate nella intestazione della scheda se il componente aggiuntivo le utilizza.
• Sezione della scheda: un gruppo raccolto di widget, separato dalle altre sezioni della scheda da una barra orizzontale e, facoltativamente, con un'intestazione della sezione. Ogni scheda deve avere almeno una sezione. Non puoi aggiungere schede o intestazioni di schede a una sezione di schede.

Oltre a questi widget di base, in un plug-in di Google Workspace puoi utilizzare il servizio Scheda per creare strutture che si sovrappongono alla scheda corrente: piè di pagina fissi e schede di anteprima:

Piè di pagina fisso

Puoi aggiungere una riga fissa di pulsanti nella parte inferiore della scheda. Questa riga non si sposta né scorre con il resto dei contenuti della scheda.

Il seguente excerpt di codice mostra come definire un piè di pagina fisso di esempio e aggiungerlo a una scheda:

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

Visualizza scheda

Quando i nuovi contenuti contestuali vengono attivati da un'azione dell'utente, ad esempio l'apertura di un messaggio di Gmail, puoi visualizzare immediatamente i nuovi contenuti contestuali (comportamento predefinito) o una notifica della scheda di anteprima nella parte inferiore della barra laterale. Se un utente fa clic su Indietro arrow_back per tornare alla tua home page mentre è attivo un attivatore contestuale, viene visualizzata una scheda di anteprima per aiutare gli utenti a trovare di nuovo i contenuti contestuali.

Per visualizzare una scheda di anteprima quando sono disponibili nuovi contenuti contestuali, anziché visualizzarli immediatamente, aggiungi .setDisplayStyle(CardService.DisplayStyle.PEEK) alla tua classe CardBuilder. Una scheda di anteprima viene visualizzata solo se viene restituito un singolo oggetto scheda con l'attivatore contestuale. In caso contrario, le schede restituite sostituiscono immediatamente la scheda corrente.

Per personalizzare l'intestazione della scheda di anteprima, aggiungi il metodo .setPeekCardHeader() con un oggetto CardHeader standard durante la creazione della scheda contestuale. Per impostazione predefinita, l'intestazione di una scheda Peek contiene solo il nome del componente aggiuntivo.

Il seguente codice, basato sulla guida introduttiva al componente aggiuntivo Cats per Google Workspace, informa gli utenti sui nuovi contenuti contestuali con una scheda Peek e personalizza l'intestazione della scheda Peek per visualizzare l'oggetto del thread di messaggi Gmail selezionato.

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

Widget informativi

I widget informativi presentano informazioni all'utente.

• Immagine: un'immagine indicada da un URL ospitato e pubblicamente accessibile fornito da te.
• DecoratedText: una stringa di contenuti di testo che puoi accoppiare ad altri elementi, come le etichette di testo superiore e inferiore e un'immagine o un'icona. I widget di testo decorato possono includere anche un widget Pulsante o Switch. Gli switch aggiunti possono essere pulsanti di attivazione/disattivazione o caselle di controllo. Il testo dei contenuti del widget DecoratedText può utilizzare la formattazione HTML; le etichette superiore e inferiore devono utilizzare testo normale.
• Paragrafo di testo: un paragrafo di testo che può includere elementi in formato HTML.

Widget di interazione utente

I widget di interazione con l'utente consentono al componente aggiuntivo di rispondere alle azioni intraprese dagli utenti. Puoi configurare questi widget con risposte di azioni per visualizzare schede diverse, aprire URL, mostrare notifiche, scrivere bozze di email o eseguire altre funzioni di Apps Script. Per maggiori dettagli, consulta la guida Creare schede interattive.

• Azione scheda: un elemento del menu inserito nel menu della barra delle intestazioni del componente aggiuntivo. Il menu della barra delle intestazioni può anche contenere elementi definiti come azioni universali, che vengono visualizzati in ogni scheda definita dal componente aggiuntivo.
• Selettori DateTime: widget che consentono agli utenti di selezionare una data, un orario o entrambi. Per saperne di più, consulta la sezione Selettori data e ora di seguito.
• Pulsante immagine: un pulsante che utilizza un'immagine anziché del testo. Puoi utilizzare una delle diverse icone predefinite o un'immagine ospitata pubblicamente indicata dal relativo URL.
• Input di selezione: un campo di immissione che rappresenta una raccolta di opzioni. Widget di input di selezione presentati come caselle di controllo, pulsanti di opzione o menu a discesa.
• Switch: un widget di attivazione/disattivazione. Puoi utilizzare gli switch solo in combinazione con un widget DecoratedText. Per impostazione predefinita, vengono visualizzati come pulsanti di attivazione/disattivazione, ma puoi impostarli in modo che vengano visualizzati come caselle di controllo.
• Pulsante di testo: un pulsante con un'etichetta di testo. Puoi specificare un colore di sfondo per i pulsanti di testo (il valore predefinito è trasparente). Puoi anche disattivare il pulsante se necessario.
• Input di testo: un campo di input di testo. Il widget può avere testo del titolo, testo di suggerimento e testo multilinea. Il widget può attivare azioni quando il valore del testo cambia.
• Griglia: un layout con più colonne che rappresenta una raccolta di elementi. Puoi rappresentare gli elementi con un'immagine, un titolo, un sottotitolo e una serie di opzioni di personalizzazione, come stili di bordo e ritaglio.

DecoratedText caselle di controllo

Puoi definire un widget DecoratedText con una casella di controllo anziché un pulsante o un pulsante di attivazione/disattivazione binario. Come per gli switch, il valore della casella di controllo è incluso nell'oggetto evento di azione che viene passato all'Action associato a questo DecoratedText tramite il metodo setOnClickAction(action).

Il seguente estratto di codice mostra come definire un widget di casella di controllo DecoratedText che puoi poi aggiungere a una scheda:

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

Selettori di data e ora

Puoi definire widget che consentono agli utenti di selezionare un orario, una data o entrambi. Puoi utilizzare setOnChangeAction() per assegnare una funzione di gestore del widget da eseguire quando il valore del selettore cambia.

Il seguente estratto di codice mostra come definire un selettore solo per data, un selettore solo per ora e un selettore data/ora, che puoi poi aggiungere a una scheda:

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

Di seguito è riportato un esempio di funzione di gestore del widget del selettore di data e ora. Questo gestore formatta e registra una stringa che rappresenta la data e l'ora scelte dall'utente in un widget selettore di data e ora con l'ID "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/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);
  }
}

La tabella seguente mostra esempi di interfacce utente di selezione del selettore su computer e dispositivi mobili. Se selezionato, il selettore della data apre un'interfaccia utente del calendario basata su mesi per consentire all'utente di selezionare rapidamente una nuova data.

Quando l'utente seleziona il selettore dell'ora sui computer, si apre un menu a discesa con un elenco di orari separati in incrementi di 30 minuti tra cui l'utente può scegliere. L'utente può anche digitare un'ora specifica. Sui dispositivi mobili, la selezione di un selettore dell'ora apre il selettore dell'ora "orologio" integrato del dispositivo.

Desktop	Dispositivi mobili

Griglia

Mostra gli elementi in un layout a più colonne con il widget griglia. Ogni elemento può mostrare un'immagine, un titolo e un sottotitolo. Utilizza opzioni di configurazione aggiuntive per impostare il posizionamento del testo rispetto all'immagine in un elemento della griglia.

Puoi configurare un elemento della griglia con un identificatore restituito come parametro all'azione definita nella griglia.

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

Formattazione del testo

Alcuni widget basati su testo possono supportare la formattazione HTML di testo semplice. Quando imposti il contenuto di testo di questi widget, includi semplicemente i tag HTML corrispondenti.

I tag supportati e il loro scopo sono riportati nella tabella seguente: