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

Gli insiemi di widget aggiunti alle sezioni delle schede definiscono l'insieme l'interfaccia utente di un componente aggiuntivo. I widget hanno lo stesso aspetto e le stesse funzioni sia sul web che 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 classificati in tre gruppi: widget strutturali, widget informativi e widget per l'interazione degli utenti.

Widget strutturali

I widget strutturali forniscono i container e l'organizzazione degli altri widget utilizzata nell'interfaccia utente.

• Insieme di pulsanti: A raccolta di uno o più pulsanti di testo o immagine, raggruppati in un riga orizzontale.
• Scheda: un singolo contesto. scheda che contiene una o più sezioni della scheda. Sei tu a definire le modalità di spostamento degli utenti tra una scheda e l'altra configurando navigazione con schede.
• Intestazione scheda: l'elemento l'intestazione di una determinata scheda. Le intestazioni delle schede possono contenere titoli, sottotitoli e un dell'immagine. Azioni della scheda e le azioni universali sono visualizzate il l'intestazione della scheda se il componente aggiuntivo le utilizza.
• Sezione scheda: A gruppo raccolto di widget, diviso dalle altre sezioni della scheda per un orizzontale e, facoltativamente, avere un'intestazione di sezione. Ogni carta deve avere almeno una sezione di schede. Non puoi aggiungere schede o intestazioni di schede a una scheda .

In aggiunta a questi widget strutturali di base, in un Componente aggiuntivo di Google Workspace che puoi utilizzare Il servizio carta per creare strutture che si sovrappongano alla carta corrente: piè di pagina fissi e schede di anteprima:

Piè di pagina fisso

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

Le seguenti un 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 vengono creati nuovi contenuti contestuali viene attivato 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 nella parte inferiore della nella barra laterale. Se un utente fa clic su Indietro arrow_back per tornare alla home page, mentre dell'attivatore contestuale è attivo, viene visualizzata una scheda Anteprima per aiutare gli utenti a trovare contenuti contestuali.

Per mostrare una scheda di anteprima quando sono disponibili nuovi contenuti contestuali, anziché visualizzare immediatamente i nuovi contenuti contestuali, aggiungi .setDisplayStyle(CardService.DisplayStyle.PEEK) al tuo CardBuilder . Una scheda di visualizzazione viene visualizzata solo se un singolo oggetto della scheda viene restituito con il tuo trigger contestuale; altrimenti le carte restituite sostituiscono immediatamente carta corrente.

Per personalizzare l'intestazione della scheda Anteprima, aggiungi il metodo .setPeekCardHeader() con un 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 sul guida rapida del componente aggiuntivo Cats di Google Workspace, avvisa gli utenti dei nuovi contenuti contestuali con una scheda di anteprima e personalizza intestazione della scheda Peek per visualizzare il messaggio Gmail selezionato l'oggetto del thread.

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 indicato da un URL ospitato e accessibile pubblicamente che fornisci.
• DecoratedText: A testo stringa di contenuti che puoi accoppiare con altri elementi, come top e bottom etichette di testo e un'immagine o un'icona. I widget DecorText possono anche includere un Button o Cambia widget. Interruttori aggiunti Possono essere pulsanti di attivazione/disattivazione o caselle di controllo. Il testo dei contenuti del widget DecorText può utilizzare Formattazione HTML; i principali e le etichette in basso devono utilizzare testo normale.
• Paragrafo di testo: A paragrafo di testo, che può includere Elementi in formato HTML.

Widget per l'interazione degli utenti

I widget di interazione dell'utente consentono al componente aggiuntivo di rispondere alle azioni intraprese dal utenti. Puoi configurare questi widget con risposte di azioni a visualizzare schede diverse, aprire URL, mostrare notifiche, scrivere bozze di email, o eseguire altre funzioni di Apps Script. Consulta le Creazione di schede interattive per i dettagli.

• Azione della scheda: un menu posizionato nel menu della barra di intestazione del componente aggiuntivo. Il menu della barra dell'intestazione può anche Contengono elementi definiti come azioni universali, che vengono visualizzate su ogni scheda definita dal componente aggiuntivo.
• Selettori DateTime: widget che consentano agli utenti di selezionare una data, un'ora o entrambe. Consulta Selettori di data e ora di seguito per ulteriori informazioni.
• Pulsante immagine: A che utilizza un'immagine al posto del testo. Puoi utilizzare uno dei numerosi 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 input di selezione presenti come caselle di controllo, pulsanti di opzione o caselle di selezione a discesa.
• Cambia: un pulsante di attivazione/disattivazione. widget. Puoi utilizzare i sensori solo insieme a un Widget DecoratedText. Per impostazione predefinita come pulsante di attivazione/disattivazione, ma puoi una casella di controllo.
• Pulsante di testo: A pulsante con un'etichetta di testo. Puoi specificare un colore di riempimento dello sfondo per il testo (l'impostazione predefinita è trasparente). Puoi anche disattivare il pulsante necessaria.
• Input di testo: un testo campo di immissione. Il widget può includere testo del titolo, testo suggerimento e testo su più righe. Il widget può attivare azioni quando il valore del testo cambia.
• Griglia: una struttura a più colonne che rappresenta una raccolta di elementi. Puoi rappresentare gli elementi con un immagine, titolo, sottotitolo e una serie di opzioni di personalizzazione come bordo e gli stili di ritaglio.

DecoratedText caselle di controllo

Puoi definire un valore DecoratedText widget a cui è associata una casella di controllo anziché un pulsante o un pulsante di attivazione/disattivazione binario. . Come per le opzioni, il valore della casella di controllo è incluso nel parametro oggetto evento di azione che viene passato a Action allegato a DecoratedText dal setOnClickAction(action) .

Il seguente estratto di codice mostra come definire una casella di controllo DecoratedText che potrai 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 consentano agli utenti di selezionare un'ora, una data o entrambe. Puoi utilizzare setOnChangeAction() per assegnare una funzione di gestore di widget a vengono eseguiti quando cambia il valore del selettore.

Il seguente estratto di codice mostra come definire un selettore solo data, ovvero selezionato e un selettore di data e ora, che potrai 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 formati e registra una stringa che rappresenta la data e l'ora scelte dal l'utente in un widget di selezione della data e dell'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 UI per la selezione del selettore su computer e dispositivi mobili dispositivi mobili. Se selezioni questa opzione, il selettore della data apre un'interfaccia utente del calendario basata sul mese 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 che l'utente può selezionare da cui proviene. L'utente può anche digitare un'ora specifica. Sui dispositivi mobili, la selezione di il selettore dell'ora apre l'"orologio" mobile integrato selettore temporale.

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 le opzioni di configurazione aggiuntive imposta il posizionamento del testo rispetto all'immagine in un elemento della griglia.

Puoi configurare un elemento della griglia con un identificatore che viene 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. Durante l'impostazione i contenuti testuali di questi widget, includi solo i tag HTML corrispondenti.

I tag supportati e il loro scopo sono mostrati di seguito tabella: