Questa pagina è stata tradotta dall'API Cloud Translation.

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

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

I migliori componenti aggiuntivi estendono ogni editor in modo naturale utilizzando controlli e comportamenti familiari. Quando crei un nuovo componente aggiuntivo:

Utilizza il pacchetto CSS dei componenti aggiuntivi nelle pagine del servizio HTML.
In caso di dubbi sul design, trova una finestra di dialogo o una barra laterale simile nell'editor e abbinala o consulta la guida introduttiva ai componenti aggiuntivi.
Segui questa guida di stile per creare un'esperienza senza interruzioni.

Testo

Nome del componente aggiuntivo

Devi impostare il nome del componente aggiuntivo quando lo pubblichi. Il nome viene visualizzato in molti punti, ad esempio nel negozio di componenti aggiuntivi e nei menu.

Usa le lettere maiuscole.
Evita la punteggiatura, in particolare le parentesi, a meno che non facciano parte del tuo brand.
Mantieni breve la descrizione: è preferibile che contenga al massimo 30 caratteri. I nomi lunghi potrebbero essere troncati automaticamente.
Non includere il nome del prodotto Google a cui si riferisce il componente aggiuntivo (o la parola Google).
Ometti le informazioni sulla versione.
Assicurati che il nome pubblicato del componente aggiuntivo corrisponda al nome del file del progetto di script. Il nome del progetto viene visualizzato nella finestra di dialogo di autorizzazione.

Cosa non fare	Cosa fare

Stile di scrittura

Non dovresti dover 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 necessiti di una spiegazione più ampia di quella che possono fornire le etichette brevi, è buona prassi creare una pagina web separata che descriva il componente aggiuntivo e creare un link a questa pagina.

Quando scrivi il testo dell'interfaccia utente:

Usa le lettere maiuscole (soprattutto per pulsanti, etichette e voci di menu).
Preferisci un testo breve e semplice, senza gergo o acronimi.

Cosa non fare	Cosa fare

Suggerimento post-installazione

Il suggerimento post-installazione viene visualizzato subito dopo che un utente ha installato il componente aggiuntivo e viene visualizzato anche nella Guida. Hai un paio di frasi per aiutare gli utenti a iniziare rapidamente.

Inizia con un verbo d'azione.
Descrivi il primo passaggio per utilizzare il 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.

Cosa non fare	Cosa fare

Voci del menu

A differenza dei normali progetti Apps Script, i componenti aggiuntivi non vengono visualizzati nell'editor di script o nel gestore di script. Gli utenti non possono eseguire direttamente gli script dei componenti aggiuntivi. Invece, ogni componente aggiuntivo ha un proprio spazio nel menu dei componenti aggiuntivi. Il menu (e possibilmente una finestra di dialogo o una barra laterale) consente agli utenti di interagire con il componente aggiuntivo.

Il menu è un elemento chiave per il controllo del tuo componente aggiuntivo da parte degli utenti, quindi progettane attentamente la struttura e la formulazione.
Evita voci di menu che ripetono semplicemente il nome del componente aggiuntivo. Inizia invece con un verbo.
Se l'elemento del menu principale inizia un flusso di lavoro e non esiste un singolo verbo che descriva la sua azione, chiamalo "Inizia". Questo pattern viene utilizzato nella guida rapida al componente aggiuntivo di Documenti.
A meno che il menu non contenga più di sei elementi, cerca di non utilizzare sottomenu. Possono essere difficili da selezionare.
Descrivi l'attività, non il componente dell'interfaccia utente visualizzato dalla voce di menu.

Cosa non fare	Cosa fare

Messaggi di errore

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

Non consentire all'utente di vedere le eccezioni generate dal codice. Utilizza invece le istruzioni try...catch per intercettare le eccezioni, poi visualizza un messaggio di errore intuitivo con testo in linea stilizzato nella classe error del pacchetto CSS dei componenti aggiuntivi o una finestra di dialogo di avviso.
Prima di pubblicare, verifica che il componente aggiuntivo non registri le informazioni di debug nella console JavaScript. Utilizza invece Stackdriver Logging.

Cosa non fare	Cosa fare

Contenuti Help

Il menu di ogni componente aggiuntivo include una finestra di dialogo Guida automatica. Se fornisci un URL di guida durante la pubblicazione, il pulsante "Scopri di più" rimanda a quella pagina. A meno che il plug-in 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 denominati.
Assicurati che le istruzioni spieghino chiaramente eventuali requisiti, ad esempio la configurazione di un foglio di lavoro in un determinato modo.
Non esitare a inserire un link ai tuoi contenuti di assistenza anche dall'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 di Editor possono essere controllati interamente dal menu, ma la maggior parte visualizza una barra laterale o una finestra di dialogo con contenuti personalizzati.

Le barre laterali sono ideali per gli strumenti permanenti che gli utenti potrebbero utilizzare ripetutamente facendo 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 dell'interfaccia utente

In qualsiasi finestra di dialogo o barra laterale, presupponi che le persone leggano solo il titolo e le etichette dei pulsanti. Riesce comunque a capire cosa fa la tua interfaccia e a fare una buona scelta?

Utilizza un titolo e etichette dei pulsanti indipendenti.
Evita blocchi di testo descrittivo lunghi.

Finestre di dialogo

Le finestre di dialogo sono ottime per gli strumenti che le persone utilizzano una volta e poi passano ad altro. Ad esempio, se il tuo componente aggiuntivo consente agli utenti di inserire un'immagine, puoi mostrare una finestra di dialogo con le opzioni di inserimento e poi chiuderla quando l'immagine è stata 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 (incluso un avviso o un prompt) da un'altra finestra di dialogo: visualizzane solo una alla volta.
Per il titolo della finestra di dialogo, utilizza una parola o una breve frase, iniziando con la 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, prendi in considerazione l'angolo in basso a destra.
Inserisci i pulsanti nell'angolo in basso a sinistra della finestra di dialogo. Il pulsante principale blu dovrebbe essere a sinistra, con eventuali pulsanti secondari grigi a destra.

Cosa non fare	Cosa fare

Barre laterali

Le barre laterali consentono agli utenti di fare riferimento al documento, al foglio di lavoro, alla presentazione o al modulo mentre fanno delle scelte. Inoltre, consentono agli utenti di utilizzare il tuo componente aggiuntivo più volte. Ogni volta che viene aperta una nuova barra laterale, quella precedente si chiude automaticamente. Sono ideali per le modalità temporanee da cui l'utente esce al termine.

Gli utenti potrebbero avere altri componenti aggiuntivi con le proprie barre laterali. Se due componenti aggiuntivi tentano di aprire contemporaneamente le barre laterali, ne viene visualizzata solo una.
Non mostrare una barra laterale o una finestra di dialogo quando un documento viene aperto per la prima volta.
Solo i componenti aggiuntivi che operano in AuthMode.FULL possono aprire barre laterali o finestre di dialogo. Puoi utilizzare un elemento di menu per aprire una barra laterale, poiché l'utente viene invitato a fornire l'autorizzazione completa.

Controlli

Le UI dei componenti aggiuntivi di alta qualità lasciano ai controlli un po' di spazio. Margini e spaziatura adeguati fanno molto, mentre i controlli fitti possono sembrare opprimenti. In caso di dubbi, prendi in prestito un layout dall'editor stesso. Ad esempio, quando crei una finestra di dialogo personalizzata, puoi esaminare quelle esistenti in Documenti Google, ad esempio File > Impostazione pagina.

La documentazione del pacchetto CSS dei 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é semplici link o altri elementi.

Evita di mostrare più di un pulsante blu, rosso o verde alla volta. I pulsanti grigi potrebbero essere visualizzati ripetutamente.
La maggior parte delle etichette dei pulsanti deve essere scritta in maiuscolo e iniziare con un verbo. I pulsanti rossi, in genere per creare azioni, devono essere in maiuscolo.

Cosa non fare	Cosa fare

Caselle di controllo e pulsanti di opzione

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

Non modificare il comportamento delle caselle di controllo in modo che assomigli a quello dei pulsanti di opzione.
Non fare nulla immediatamente dopo la loro attivazione. Le persone commettono errori. Attendi fino a quando gli utenti non fanno clic su un pulsante per confermare le loro scelte.

Seleziona i menu

I selettori sono un ottimo modo per offrire un breve elenco di alternative.

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

Aree di testo

Se gli utenti devono digitare più di qualche parola, utilizza un'area di testo.

Crea aree di testo di almeno due righe di altezza in modo che siano più facili da usare e non assomiglino a campi di testo.
Posiziona le etichette in alto.

Campi di testo

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

La larghezza di un campo di testo deve suggerire cosa ti aspetti che gli utenti digitino al suo interno.
Evita di utilizzare il testo segnaposto come etichetta, perché scompare quando l'elemento è attivo. Il testo segnaposto è utile per fornire esempi o dettagli aggiuntivi.
Posiziona le etichette in alto, ma non esitare a disporre i campi di testo brevi uno accanto all'altro.

Branding

Nel componente aggiuntivo

Se vuoi includere il branding, mantienilo breve e leggero. In questo modo, gli utenti si concentreranno sulla tua UI e il tuo componente aggiuntivo sembrerà parte dell'editor.

Tutti gli aspetti del tuo componente aggiuntivo devono rispettare le linee guida per il branding.
Non includere la parola "Google" o utilizzare le icone dei prodotti Google.
Il testo deve essere composto da poche parole e avere lo stile della classe gray del pacchetto CSS di componenti aggiuntivi.
Le immagini devono avere uno sfondo bianco e non devono superare le dimensioni di 200 x 60 px.
Per le finestre di dialogo, il branding deve trovarsi nell'angolo in basso a destra.
Per le barre laterali, il branding può essere posizionato in alto o in basso.

In negozio

Per pubblicare un componente aggiuntivo di Editor, devi disporre di un numero di asset immagine. Questi asset vengono utilizzati per creare la scheda dello Store del componente aggiuntivo.

Tutti gli aspetti della scheda dello Store devono rispettare le linee guida per il branding.
Per maggiori dettagli sulle immagini da fornire, consulta le linee guida per le immagini.

Accessibilità

Tutti dovrebbero poter utilizzare il tuo componente aggiuntivo, indipendentemente dal fatto che vedano i colori in modo diverso, utilizzino uno screen reader o abbiano altre esigenze. L'accessibilità è un argomento ampio 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>) in modo che gli utenti possano effettuare il passaggio con i tasti Tab. Valuta se supportare 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 descrivere il loro utilizzo.
Non fare affidamento solo sul colore per comunicare lo stato. Utilizza anche icone e testo.

Se utilizzi controlli web standard, come quelli descritti in precedenza in questa guida, l'accessibilità del tuo componente aggiuntivo è più semplice.