Widget

Un widget è un semplice elemento UI che fornisce uno o più dei seguenti elementi:

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

Un insieme di widget aggiunti alle sezioni di schede definisce l'interfaccia utente complessiva del componente aggiuntivo. I widget hanno lo stesso aspetto e la stessa funzione sia sul Web che sui dispositivi mobili. La documentazione di riferimento descrive i diversi metodi per la creazione di set di widget.

Utilizzare il kit di design dei componenti aggiuntivi di Google Workspace

Per risparmiare tempo nella progettazione di widget di componenti aggiuntivi, i designer possono utilizzare il kit di progettazione dell'interfaccia utente di Google Workspace dei componenti aggiuntivi disponibile su Figma. Puoi creare un account Figma o richiedere una licenza all'amministratore della tua organizzazione.

Sfoglia i componenti e utilizza i modelli integrati per creare e visualizzare widget.

Scarica il kit per il design

Tipi di widget

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

Widget strutturali

I widget strutturali forniscono container e organizzazione agli altri widget utilizzati nell'AI.

Widget strutturali

  • Set di pulsanti: una raccolta di uno o più pulsanti di testo o immagine, raggruppati in una riga orizzontale.
  • Scheda: una singola scheda di contesto contenente una o più sezioni di schede. Puoi definire il modo in cui gli utenti possono spostarsi tra le schede configurando la navigazione.
  • Intestazione scheda: l'intestazione di una determinata scheda. Le intestazioni della scheda possono avere titoli, sottotitoli e un'immagine. Le azioni scheda e le azioni universali vengono visualizzate nell'intestazione della scheda se il componente aggiuntivo le utilizza.
  • Sezione scheda: un gruppo di widget raccolto, diviso dalle altre sezioni della scheda per una regola orizzontale e, facoltativamente, con un'intestazione di sezione. Ogni scheda deve avere almeno una sezione. Non puoi aggiungere schede o intestazioni di scheda a una sezione di schede.

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

Ora puoi aggiungere una riga fissa di pulsanti nella parte inferiore della scheda. Questa riga non si sposta o scorre con il resto dei contenuti della scheda. Il seguente estratto 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("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();
      

 

Esempio di widget a piè di pagina fisso

Visualizza scheda

Esempio di scheda Peek

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

Per visualizzare una scheda riepilogativa quando sono disponibili nuovi contenuti contestuali, anziché visualizzare immediatamente i nuovi contenuti contestuali, aggiungi .setDisplayStyle(CardService.DisplayStyle.PEEK) alla classe CardBuilder. Una scheda riepilogativa viene visualizzata solo se viene restituito un singolo oggetto scheda con il tuo attivatore contestuale; in caso contrario, le schede restituite sostituiscono immediatamente la scheda corrente.

Per personalizzare l'intestazione della scheda riepilogativa, aggiungi il metodo .setPeekCardHeader() con un oggetto CardHeader standard quando crei la scheda contestuale. Per impostazione predefinita, un'intestazione della scheda Peek contiene solo il nome del componente aggiuntivo.

Il seguente codice, basato sulla guida rapida al componente aggiuntivo di Google Workspace per Gatti, informa gli utenti dei 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);
      

 

Esempio di scheda informativa personalizzata

Widget informativi

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 associare ad altri elementi come le etichette di testo in alto e in basso e un'immagine o un'icona. I widget DecorText possono includere anche un widget Pulsante o Cambia. I sensori aggiunti possono essere semplici pulsanti di attivazione/disattivazione o caselle di controllo. Il testo dei contenuti del widget DecorText può utilizzare la formattazione HTML; le etichette superiore e inferiore devono utilizzare testo normale.
  • Paragrafo di testo: un semplice paragrafo di testo che può includere elementi in formato HTML.




Widget Interazione utente

Widget azione scheda

I widget Interazioni degli utenti consentono al componente aggiuntivo di rispondere alle azioni eseguite dagli utenti. Puoi configurare questi widget con risposte alle azioni per visualizzare schede diverse, aprire URL, mostrare notifiche, scrivere bozze di email o eseguire altre funzioni di Apps Script. Per informazioni dettagliate, consulta la guida alla creazione di schede interattive.

Widget Interazione utente

  • Azione della scheda: una voce di menu inserita nel menu della barra delle intestazioni aggiuntiva. Il menu della barra delle intestazioni può contenere anche elementi definiti come azioni universali, visualizzati in tutte le schede definite dal componente aggiuntivo.
  • Selettori di DateTime: widget che consentono agli utenti di selezionare una data, un'ora o entrambe le cose. Per ulteriori informazioni, consulta la sezione Selettori di data e ora di seguito.
  • Pulsante immagine: un pulsante che utilizza un'immagine invece di testo. Puoi utilizzare una delle numerose icone predefinite o un'immagine ospitata pubblicamente indicata dal relativo URL.
  • Input di selezione: un campo di immissione che rappresenta una raccolta di opzioni. I widget di immissione di selezione sono visualizzati come caselle di controllo, pulsanti di opzione o caselle di selezione dei menu a discesa.
  • Cambia: un widget di attivazione/disattivazione. Puoi utilizzare i sensori solo insieme a un widget DecoratedText. Per impostazione predefinita, vengono visualizzati come pulsante di attivazione/disattivazione, ma puoi invece impostarli come una casella di controllo.
  • Pulsante di testo: un pulsante con un'etichetta di testo. Puoi specificare un riempimento colore di sfondo per i pulsanti di testo (l'impostazione predefinita è trasparente). Puoi anche disattivare il pulsante in base alle tue esigenze.
  • Input di testo: un campo di immissione di testo. Il widget può contenere testo del titolo, testo del suggerimento e testo su più righe. Il widget può attivare le azioni quando il valore del 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 gli stili del bordo e del ritaglio.

Caselle di testo DecorText

Puoi definire un widget DecoratedText a cui è associata una casella di controllo, anziché un pulsante o un interruttore binario. Come per i sensori, il valore della casella di controllo è incluso nell'oggetto evento azione che viene passato alla Action allegata a questo DecoratedText dal metodo setOnClickAction(action).

Il seguente estratto di codice mostra come definire un widget DecoratedText di casella di controllo, che puoi quindi 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));
      

 

Esempio di widget della casella di controllo con testo decorato

Selettori di data e ora

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

Il seguente estratto di codice mostra come definire un selettore solo per la data, un selettore solo per l'ora e un selettore di data e ora, che puoi quindi aggiungere a una scheda:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter the 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 the 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 the date and time in EDT 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"));
      

 

Esempio di scheda informativa personalizzata

Di seguito è riportato un esempio di una funzione di gestione del widget del selettore della data e dell'ora. Questo gestore semplicemente 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/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 tabella seguente mostra alcuni esempi delle interfacce utente della selezione del selettore sui computer desktop e sui dispositivi mobili. Quando è selezionato, il selettore della data apre un'interfaccia utente di calendario mensile per consentire all'utente di selezionare rapidamente una nuova data.

Quando l'utente seleziona il selettore dell'ora sui dispositivi desktop, si apre un menu a discesa con un elenco di orari separati in incrementi di 30 minuti da cui può selezionare l'utente. L'utente può anche digitare in un orario specifico. Sui dispositivi mobili che selezionano un selettore dell'ora, si apre il selettore integrato "Orologio" integrato.

Desktop Dispositivi mobili
esempio di selezione del selettore della data esempio di selezione del selettore di date per dispositivi mobili
esempio di selezione del selettore di ora esempio di selezione del selettore di orario per dispositivi mobili

GRid

Visualizza gli elementi in un layout a più colonne con il widget griglia. Ogni elemento può visualizzare un'immagine, un titolo e un sottotitolo. Utilizza opzioni di configurazione aggiuntive per impostare il posizionamento del testo relativo 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.

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.SQUARE);

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));
      

 

Esempio di widget griglia

Formattazione del testo

Alcuni widget basati sul testo supportano una semplice formattazione HTML del testo. Quando imposti il contenuto testuale di questi widget, includi solo i tag HTML corrispondenti. Sono supportati i seguenti formati:

Formato Esempio Risultato sottoposto a rendering
Grassetto <b>test</b> test
Corsivo <i>test</i> test
Sottolineato <u>test</u> test
Barrato <s>test</s> test
Colore del carattere <font color="#ea9999">test</font> test
Link ipertestuale <a href="http://www.google.com">google</a> Google
Ora <time>2020-02-16 15:00</time> 2020-02-16 15:00
Nuova riga test <br> test prova
prova