Widget

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

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

Gli insiemi di widget aggiunti alle sezioni delle schede definiscono l'interfaccia utente generale dei componenti aggiuntivi. I widget hanno lo stesso aspetto e lo stesso funzionamento sia sul web che sui dispositivi mobili. La documentazione di riferimento descrive diversi metodi per creare set di widget.

Tipi di widget

I widget aggiuntivi sono generalmente classificati in tre gruppi: widget strutturali, widget informativi e widget di interazione utente.

Widget strutturali

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

  • Set di pulsanti: una raccolta di uno o più pulsanti di testo o immagine, raggruppati in una riga orizzontale.
  • Scheda: un'unica scheda di contesto che contiene una o più sezioni della scheda. Puoi definire in che modo gli utenti possono spostarsi tra le schede configurando la navigazione schede.
  • Intestazione della 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 nell'intestazione della scheda se il componente aggiuntivo le utilizza.
  • Sezione della scheda: un gruppo di widget raccolti, suddivisi dalle altre sezioni della scheda da una riga orizzontale e facoltativamente con un'intestazione di sezione. Ogni scheda deve avere almeno una sezione. Non puoi aggiungere schede o intestazioni a una sezione di schede.

Widget strutturali

Oltre a questi widget strutturali di base, in un componente aggiuntivo di Google Workspace puoi utilizzare il Servizio delle schede per creare strutture che si sovrappongono alla scheda corrente: piè di pagina fissi e schede di anteprima:

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

Esempio di widget piè di pagina fisso

Il seguente estratto del 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

Esempio di scheda di anteprima

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

Per mostrare una scheda rapida quando sono disponibili nuovi contenuti contestuali, anziché mostrare subito i nuovi contenuti contestuali, aggiungi .setDisplayStyle(CardService.DisplayStyle.PEEK) al tuo corso CardBuilder. Una scheda appare solo se un singolo oggetto scheda viene restituito con l'attivatore contestuale; in caso contrario, le schede restituite sostituiscono immediatamente la scheda corrente.

Per personalizzare l'intestazione della scheda visualizzata, 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.

Esempio di scheda informativa personalizzata

Il codice seguente, basato sulla guida rapida per il componente aggiuntivo Cats per Google Workspace, informa gli utenti della presenza di nuovi contenuti contestuali con una scheda Peek e personalizza l'intestazione della scheda in modo che mostri l'oggetto del thread del messaggio di 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 indicata da un URL ospitato e accessibile pubblicamente che fornisci.
  • DecoratedText: una stringa di contenuti di testo che puoi accoppiare con altri elementi, come etichette di testo superiori e inferiori e un'immagine o un'icona. I widget decoratoText possono anche includere un widget Pulsante o Cambia. Le opzioni aggiunte possono essere pulsanti di attivazione/disattivazione o caselle di controllo. Il testo dei contenuti del widget decoratoText 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 informativi

Widget di interazione utente

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

  • Azione della scheda: una voce di menu posizionata nel menu della barra intestazione del componente aggiuntivo. Il menu della barra intestazione 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'ora o entrambe. Per saperne di più, consulta Selettori di data e ora di seguito.
  • Pulsante immagine: un pulsante che utilizza un'immagine anziché del testo. Puoi utilizzare una delle numerose icone predefinite o un'immagine ospitata pubblicamente indicata dal relativo URL.
  • Input di selezione: un campo di input che rappresenta una raccolta di opzioni. Widget di input di selezione presenti come caselle di controllo, pulsanti di opzione o caselle di selezione a discesa.
  • Cambia: un widget di attivazione/disattivazione. Puoi utilizzare i sensori solo in combinazione con un widget DecoratedText. Per impostazione predefinita, queste opzioni vengono visualizzate come interruttore di attivazione/disattivazione, ma puoi comunque impostarle come casella di controllo.
  • Pulsante Testo: un pulsante con un'etichetta di testo. Puoi specificare un colore di riempimento dello sfondo per i pulsanti di testo (l'impostazione predefinita è trasparente). Puoi anche disattivare il pulsante se necessario.
  • Input di testo: un campo di immissione di testo. Il widget può avere testo del titolo, testo del suggerimento e testo su più righe. Il widget può attivare azioni quando il valore di testo cambia.
  • Griglia: un layout a 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 bordi e stili di ritaglio.
Widget delle azioni della scheda Widget di interazione utente

DecoratedText caselle di controllo

Puoi definire un widget DecoratedText a cui è allegata una casella di controllo anziché un pulsante o un'opzione di attivazione/disattivazione del programma binario. Come per le opzioni, il valore della casella di controllo è incluso nell'oggetto evento azione che viene passato a Action associato a questo DecoratedText dal metodo setOnClickAction(action).

Esempio di widget della casella di controllo con testo decorato

Il seguente estratto di codice mostra come definire un widget della casella di controllo DecoratedText, che puoi 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'ora, una data o entrambe. Puoi utilizzare setOnChangeAction() per assegnare una funzione di gestore widget da eseguire quando il valore del selettore cambia.

Esempio di scheda informativa personalizzata

Il seguente estratto di codice mostra come definire un selettore solo per data, uno solo per data e un selettore per data e ora, che potrai 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 selettore di data e ora. Questo gestore formatta e registra una stringa che rappresenta la data e l'ora scelta dall'utente in un widget del selettore di data e ora con l'ID "myDateTime PickerWidgetID":

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

 

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

Sui dispositivi desktop, quando l'utente seleziona il selettore dell'ora, si apre un menu a discesa con un elenco di intervalli di tempo separati per intervalli di 30 minuti. L'utente può anche digitare un orario specifico. Sui dispositivi mobili, se selezioni un selettore dell'ora, si apre il selettore dell'ora "orologio" integrato.

Computer Dispositivo mobile
Esempio di selezione del selettore della data Esempio di selezione del selettore della data su dispositivo mobile
Esempio di selezione del selettore di ora esempio di selezione del selettore di ora del dispositivo mobile

Griglia

Visualizza 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 in relazione all'immagine in un elemento della griglia.

Puoi configurare un elemento della griglia con un identificatore che viene restituito come parametro per l'azione definita nella griglia.

Esempio di widget 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 i contenuti testuali di questi widget, includi solo i tag HTML corrispondenti.

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

Formato Esempio Risultato visualizzato
Grassetto "This is <b>bold</b>." È in grassetto.
Corsivo "This is <i>italics</i>." Questo è il corsivo.
Sottolineato "This is <u>underline</u>." Questo è un sottolineato.
Barrato "This is <s>strikethrough</s>." Si tratta di barrato.
Colore carattere "This is <font color=\"#FF0000\">red font</font>." Questo è un carattere rosso.
Link ipertestuale "This is a <a href=\"https://www.google.com\">hyperlink</a>." Questo è un link ipertestuale.
Tempo "This is a time format: <time>2023-02-16 15:00</time>." Questo è un formato dell'ora: .
Nuova riga "This is the first line. <br> This is a new line. Questa è la prima riga.
Questa è una nuova riga.