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.
• Inviti all'azione come pulsanti, campi di immissione di testo o caselle di controllo.

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

Tipi di widget

I widget dei componenti aggiuntivi sono generalmente suddivisi 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: una singola scheda di contesto che contiene una o più sezioni di schede. Definisci il modo in cui gli utenti si spostano tra le schede configurando la navigazione tra le 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 utilizzate.
• Sezione della scheda: un gruppo di widget raccolti, separati dalle altre sezioni della scheda da una riga orizzontale e, facoltativamente, con un'intestazione di sezione. Ogni scheda deve avere almeno una sezione di schede. Non puoi aggiungere schede o intestazioni di schede a una sezione di schede.

Quando aggiungi un widget a uno dei contenitori, crei e aggiungi una copia di quel widget. Se modifichi il widget dopo averlo aggiunto, la modifica non viene visualizzata nell'interfaccia. Assicurati che il widget sia completo prima di aggiungerlo. Se devi modificare un widget dopo averlo aggiunto, ricrea l'intera sezione della scheda o la scheda. Per maggiori dettagli, consulta Creare 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 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 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("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 visualizzare una notifica della scheda di anteprima nella parte inferiore della barra laterale. Se un utente fa clic su Indietro arrow_back per tornare alla home page mentre è attivo un trigger 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, aggiungi .setDisplayStyle(CardService.DisplayStyle.PEEK) alla classe CardBuilder. Una scheda di anteprima viene visualizzata solo se viene restituito un singolo oggetto scheda con il trigger contestuale; in caso contrario, le schede restituite sostituiscono la scheda corrente.

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

In base alla guida rapida del componente aggiuntivo Cats di Google Workspace, il seguente codice notifica agli utenti i nuovi contenuti contestuali con una scheda di anteprima e personalizza l'intestazione della scheda di anteprima per visualizzare l'oggetto del thread di messaggi 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.
• DecoratedText I widget DecoratedText possono includere anche un Button o Switch widget. Gli switch aggiunti possono essere pulsanti di attivazione/disattivazione o caselle di controllo. Il testo dei contenuti può utilizzare la formattazione HTML; le etichette in alto e in basso devono utilizzare testo normale.
• Paragrafo di testo: un paragrafo di testo che può includere elementi formattati in HTML.

Widget di interazione utente

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

• Azione della scheda: una voce di menu inserita nel menu della barra delle intestazioni del componente aggiuntivo. Il menu della barra delle intestazioni può contenere anche elementi definiti come azioni universali, che vengono visualizzati su ogni scheda definita dal componente aggiuntivo.
• Selettori di data e ora: i widget consentono agli utenti di selezionare una data, un'ora o entrambi. Per maggiori informazioni, consulta Selettori di data e ora.
• Pulsante immagine: un pulsante che utilizza un'immagine anziché testo. Utilizza una delle diverse icone predefinite o un'immagine ospitata pubblicamente.
• Input di selezione: un campo di immissione che rappresenta una raccolta di opzioni. I widget di input di selezione vengono visualizzati come caselle di controllo, pulsanti di opzione o caselle di selezione a discesa.
• Switch: un widget di attivazione/disattivazione utilizzato con un widget DecoratedText. Per impostazione predefinita, questi vengono visualizzati come un interruttore di attivazione/disattivazione, ma puoi visualizzarli come una casella di controllo.
• Pulsante di testo: un pulsante con un'etichetta di testo. Specifica un riempimento del 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 immissione di testo. Il widget può avere testo del titolo, testo di suggerimento e testo su più righe. Il widget può attivare azioni quando il valore del testo cambia.
• Griglia: un layout a più colonne. Rappresenta gli elementi con un'immagine, un titolo, un sottotitolo e opzioni di personalizzazione come stili di bordo e ritaglio.

Caselle di controllo DecoratedText

Puoi definire un DecoratedText widget a cui è allegata una casella di controllo, anziché un pulsante o un interruttore di attivazione/disattivazione binario. Analogamente agli interruttori di attivazione/disattivazione, il valore della casella di controllo è incluso nell' oggetto evento azione passato all'oggetto Action collegato a questo DecoratedText dal metodo setOnClickAction.

Il seguente estratto di codice mostra come definire un widget DecoratedText della casella di controllo da 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

Definisci i widget che consentono agli utenti di selezionare un'ora, una data o entrambi. Utilizza setOnChangeAction per assegnare una funzione di gestione dei widget da eseguire quando il valore del selettore cambia.

Il seguente estratto di codice mostra come definire un selettore solo data, un selettore solo ora e un selettore di data e ora da 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 gestione dei 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 del 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 seguente tabella mostra esempi delle interfacce utente di selezione del selettore su computer desktop e dispositivi mobili. Quando è selezionato, il selettore di date apre un'interfaccia utente del calendario basata sul mese per consentire all'utente di selezionare una nuova data.

Quando l'utente seleziona il selettore di ore sui computer desktop, si apre un menu a discesa con un elenco di orari separati in incrementi di 30 minuti. L'utente può anche digitare un orario specifico. Sui dispositivi mobili, la selezione di un selettore di ore apre il selettore di ore "orologio" mobile integrato.

Desktop	Dispositivi mobili

Griglia

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

Configura 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 supportano la formattazione HTML di base del testo. Quando imposti i contenuti di testo di questi widget, includi i tag HTML corrispondenti.

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