Guida di stile dell'interfaccia utente per i componenti aggiuntivi dell'editor

I componenti aggiuntivi Editor consentono di creare interfacce utente (menu, barre laterali e finestre di dialogo) utilizzando il servizio HTML di Apps Script. Poiché sono sviluppate in HTML e CSS, sono altamente personalizzabili. Tuttavia, quando crei l'interfaccia del componente aggiuntivo, dovresti progettarla per offrire un'esperienza utente ottimale.

I migliori componenti aggiuntivi estendono naturalmente ciascun editor tramite i controlli e i comportamenti che già conosci. Quando crei un nuovo componente aggiuntivo:

Testo

Nome componente aggiuntivo

È necessario impostare il nome del componente aggiuntivo quando lo pubblichi. Il nome viene visualizzato in molte posizioni, ad esempio nello store dei componenti aggiuntivi e nei menu.

  • Usa la lettera maiuscola per il titolo.
  • Evita di utilizzare la punteggiatura, in particolare le parentesi, a meno che non facciano parte del brand.
  • Non dilungarlo: massimo 30 caratteri. I nomi lunghi potrebbero essere troncati automaticamente.
  • Non includere il nome del prodotto Google a cui è destinato il componente aggiuntivo (oppure utilizzare la parola Google).
  • Escludi le informazioni sulla versione.
  • Assicurati che il nome pubblicato del componente aggiuntivo sia uguale al nome del file del progetto di script. Il nome del progetto viene visualizzato nella finestra di dialogo dell'autorizzazione.
No Cosa fare
Nomi dei componenti aggiuntivi non validi Nomi dei componenti aggiuntivi validi

Stile di scrittura

Non c'è bisogno di scrivere molto. La maggior parte delle azioni deve essere resa chiara tramite iconografia, layout ed etichette brevi. Se ritieni che una parte del tuo componente aggiuntivo richieda una spiegazione più ampia di quella fornita dalle etichette brevi, ti consigliamo di creare una pagina web separata che descriva il componente aggiuntivo e il link al componente aggiuntivo.

Quando scrivi il testo dell'interfaccia utente:

  • Usa la lettera maiuscola a inizio frase, soprattutto per i pulsanti, le etichette e le voci di menu.
  • Preferisco un testo semplice e breve senza gergo o acronimi.
No Cosa fare

Suggerimento dopo l'installazione

Il suggerimento post-installazione viene visualizzato subito dopo l'installazione del componente aggiuntivo da parte dell'utente e viene visualizzato nella Guida. Hai un paio di frasi per aiutare gli utenti a iniziare rapidamente.

  • Inizia con un'azione.
  • Descrivi il primo passaggio per l'utilizzo del componente aggiuntivo.
  • Se hai un'interfaccia utente principale, ad esempio una barra laterale, spiega come aprirla.
  • Non promuovere il tuo componente aggiuntivo qui: è già installato.
No Cosa fare
Suggerimento per post-installazione non corretto Suggerimento valido dopo l'installazione

A differenza dei normali progetti Apps Script, i componenti aggiuntivi non vengono visualizzati nell'editor di script o in Gestione script. Gli utenti non possono eseguire script aggiuntivi direttamente. Invece, ogni componente aggiuntivo viene visualizzato nel menu dei componenti aggiuntivi. Il menu (ed eventualmente una finestra di dialogo o una barra laterale) consente agli utenti di interagire con il componente aggiuntivo.

  • Il menu è una parte fondamentale del modo in cui gli utenti controllano il tuo componente aggiuntivo, quindi progetta la struttura e il testo con attenzione.
  • Evita voci di menu che si ripetano semplicemente con il nome del componente aggiuntivo. Inizia invece con una parola di azione.
  • Se la voce di menu principale inizia un flusso di lavoro e non esiste un unico verbo che descriva l'azione, chiama "Inizia". Questo pattern è utilizzato nella guida rapida ai componenti aggiuntivi di Documenti.
  • A meno che il tuo menu non abbia più di sei voci, prova a non utilizzare sottomenu. Possono essere difficili e difficili da selezionare.
  • Descrivi l'attività, non il componente UI visualizzato.
No Cosa fare
Etichette voce di menu errate Buone voci di menu

Messaggi di errore

Quando si verifica un problema, è importante utilizzare un linguaggio semplice. Spiega il problema dal punto di vista dell'utente e suggerisci come risolverlo.

  • Non consentire all'utente di visualizzare eventuali eccezioni generate dal codice. Utilizza invece le istruzioni try...catch per intercettare le eccezioni, quindi visualizza un messaggio di errore eliminato dall'utente con testo incorporato in stile errorerror dal pacchetto CSS di componenti aggiuntivi o da una finestra di dialogo avviso.
  • Prima di pubblicare, verifica che il tuo componente aggiuntivo non registri le informazioni di debug nella console JavaScript; utilizza invece Stackdriver Logging.
No Cosa fare
Messaggio di errore errato Messaggio di errore valido

Contenuti Help

Il menu di ogni componente aggiuntivo include una finestra di dialogo automatica della Guida. Se fornisci un URL della guida al momento della pubblicazione, il pulsante "Scopri di più" rimanda alla pagina. A meno che il tuo componente aggiuntivo non sia autoesplicativo, fornisci una pagina che spieghi come utilizzarlo.

  • Se possibile, mostra le istruzioni in un elenco puntato o numerato. Guida gli utenti fino al risultato finale, con riferimenti chiari agli elementi dell'interfaccia utente con nome.
  • Assicurati che le istruzioni spieghino chiaramente eventuali requisiti, come impostare un determinato foglio di lavoro.
  • Non esitare a inserire un link ai tuoi contenuti di assistenza nell'interfaccia utente principale. Se il componente aggiuntivo crea un nuovo documento, puoi anche visualizzare le istruzioni nel corpo del documento.

Interfacce utente personalizzate

Alcuni semplici componenti aggiuntivi dell'editor possono essere controllati interamente dal loro menu, ma la maggior parte mostra una barra laterale o una finestra di dialogo con contenuti personalizzati.

  • Le barre laterali sono la soluzione migliore per gli strumenti persistenti che gli utenti possono utilizzare ripetutamente quando fanno riferimento ai contenuti del documento o del foglio di lavoro.
  • Le finestre di dialogo sono ideali per strumenti monouso, pagine di impostazioni e messaggi importanti.

Testo UI

In qualsiasi finestra di dialogo o barra laterale, supponiamo che le persone leggano solo le etichette dei titoli e dei pulsanti. Riescono comunque a capire l'attività dell'interfaccia e a scegliere di conseguenza?

  • Utilizzare un titolo e le etichette dei pulsanti indipendenti.
  • Evita blocchi lunghi del testo descrittivo.

Finestre di dialogo

Le finestre di dialogo sono ottime per gli strumenti che le persone utilizzano una sola volta per continuare. Ad esempio, se il componente aggiuntivo consente alle persone di inserire un'immagine, potresti visualizzare una finestra di dialogo con le scelte su cosa inserire, quindi chiudi la finestra di dialogo quando l'immagine è inserita. Le finestre di dialogo sono utili anche per visualizzare le impostazioni del componente aggiuntivo o per comunicare un messaggio importante.

  • Non aprire una finestra di dialogo (inclusi un avviso o un messaggio) da un'altra finestra di dialogo, visualizzandone solo una alla volta.
  • Per il titolo della finestra di dialogo, utilizza una parola o una breve frase, preceduta dalla parola più importante.
  • Le etichette dei pulsanti devono essere correlate al titolo della finestra di dialogo.
  • Preferisci due pulsanti, di solito un'azione principale e "Annulla". Per i casi particolari che richiedono un terzo pulsante, considera l'angolo in basso a destra.
  • Inserisci i pulsanti nell'angolo in basso a sinistra della finestra di dialogo. Il pulsante principale blu deve essere posizionato a sinistra, con gli eventuali pulsanti secondari grigi a destra.
No Cosa fare
Titolo della finestra di dialogo non valido Titolo della finestra di dialogo adatto

Le barre laterali consentono agli utenti di fare riferimento al proprio documento, foglio di lavoro, presentazione o modulo durante la scelta. Inoltre, consentono alle persone di utilizzare il tuo componente aggiuntivo ripetutamente. Ogni volta che viene aperta una nuova barra laterale, qualsiasi barra precedente viene chiusa automaticamente. Sono ideali per le modalità temporanee da cui l'utente esce.

  • Gli utenti potrebbero avere altri componenti aggiuntivi con le proprie barre laterali. Se due componenti aggiuntivi tentano di aprire barre laterali contemporaneamente, viene visualizzato solo uno.
  • Non visualizzare una barra laterale o una finestra di dialogo alla prima apertura di un documento.
  • Solo i componenti aggiuntivi che operano in AuthMode.FULL possono aprire barre laterali o finestre di dialogo. Puoi utilizzare una voce del menu per aprire una barra laterale in quanto richiede all'utente di fornire l'autorizzazione completa.

Impostazioni

Un'eccellente UI aggiuntiva lascia un po' di controllo. Margini e spaziatura interna adeguati sono molto utili, mentre i controlli densi possono sembrare impegnativi. In caso di dubbi, prendete in prestito un layout dall'editor stesso. Ad esempio, esamina le finestre di dialogo esistenti in Documenti Google, come File > Impostazione pagina, quando crei le tue finestre di dialogo.

La documentazione per il pacchetto CSS di componenti aggiuntivi fornisce il markup di esempio per ciascuno dei tipi di controlli riportati di seguito.

Pulsanti

Utilizza i pulsanti per controllare le azioni principali dell'interfaccia utente anziché i link normali o altri elementi.

  • Evita di mostrare più di un pulsante blu, rosso o verde alla volta. I pulsanti grigi potrebbero essere visualizzati più volte.
  • La maggior parte delle etichette dei pulsanti deve essere maiuscola e iniziare con un verbo. I pulsanti rossi, di solito per le azioni di creazione, devono utilizzare solo lettere maiuscole.
No Cosa fare

Caselle di controllo e pulsanti di opzione

Utilizza le caselle di controllo quando gli utenti possono selezionare più opzioni o non selezionare alcuna opzione. Utilizza i pulsanti di opzione (o un menu di selezione) quando devi selezionare esattamente un'opzione.

  • Non modificare le caselle di controllo per simulare i pulsanti di opzione.
  • Non intraprendere alcuna azione immediatamente dopo il controllo. Le persone commettono errori. Attendi finché gli utenti non faranno clic su un pulsante per confermare le loro scelte.

Seleziona i menu

Le selezioni sono un ottimo modo per offrire un breve elenco di alternative.

  • Ordina le opzioni in ordine alfabetico o in base a uno schema logico che tutti gli utenti possano comprendere (ad esempio, giorni della settimana, a partire da domenica).
  • Se l'elenco è troppo lungo, valuta la possibilità di utilizzare un altro controllo. Ad esempio, potresti visualizzare un elenco scorrevole per dare al menu più spazio e semplificare la navigazione.

Aree di testo

Se le persone devono digitare più di una parola, utilizza un'area di testo.

  • Crea aree di testo di almeno due righe in modo che siano più facili da utilizzare e non abbiano l'aspetto di campi di testo.
  • Posiziona le etichette in alto.

Campi di testo

Utilizza i campi di testo se gli utenti devono digitare soltanto una o due parole.

  • La larghezza di un campo di testo deve indicare il testo che ti aspetti sia digitato dagli utenti.
  • Evita di utilizzare testo segnaposto come etichetta, perché scompare sullo stato attivo. Il testo segnaposto è utile per fornire esempi o dettagli aggiuntivi.
  • Posiziona le etichette in alto, ma puoi tranquillamente affiancare brevi campi di testo.

Branding

Nel componente aggiuntivo

Se vuoi includere branding, il tuo messaggio deve essere breve e leggero. In questo modo, gli utenti si concentrano sulla tua UI e il tuo componente aggiuntivo risulta parte dell'editor.

  • Tutti gli aspetti del componente aggiuntivo devono seguire le linee guida per il branding.
  • Non includere la parola "Google" e non utilizzare le icone dei prodotti Google.
  • Il testo non deve essere composto da solo poche parole e deve essere inserito nella classe gray del pacchetto di componenti aggiuntivi CSS.
  • La grafica deve avere uno sfondo bianco e non può superare i 200 px × 60 px.
  • Per le finestre di dialogo, il branding deve essere nell'angolo in basso a destra.
  • Per le barre laterali, il branding può essere nella parte superiore o inferiore.

Nel negozio

Per pubblicare un componente aggiuntivo di Editor, devi disporre di un numero di asset immagine. Queste risorse vengono utilizzate per creare la scheda dello Store aggiuntiva.

Accessibilità

Tutti dovrebbero apprezzare il tuo componente aggiuntivo, sia che vedono i colori in modo diverso, che utilizzino uno screen reader o che abbiano altre esigenze. L'accessibilità è un argomento generale che non può essere trattato completamente in questa guida di stile. Una risorsa utile è il sito Accessibilità di Google. Ecco alcuni suggerimenti per iniziare:

  • Assicurati di poter accedere a tutti i controlli dell'interfaccia utente con la tastiera. Aggiungi tabindex=0 ai controlli personalizzati (come quelli creati con <div>) per consentire agli utenti di selezionarli. Valuta anche se dovrebbero essere supportate anche altre chiavi, ad esempio le frecce per un elenco.
  • Alcune persone potrebbero utilizzare uno screen reader con il tuo componente aggiuntivo. Pertanto, le immagini devono avere un attributo alt e i controlli personalizzati devono avere attributi ARIA per descriverne l'utilizzo.
  • Non fare affidamento esclusivamente sul colore per comunicare lo stato. Utilizza anche icone e testo.

Se utilizzi controlli web standard, come quelli descritti in precedenza in questa guida, rendere il tuo componente aggiuntivo accessibile è più semplice.