Guide de style pour les modules complémentaires Editor

Les modules complémentaires d'éditeurs créent des interfaces utilisateur (menus, barres latérales et boîtes de dialogue) à l'aide du service HTML d'Apps Script. Les interfaces étant développées en HTML et en CSS, elles sont hautement personnalisables. Toutefois, lorsque vous créez votre interface complémentaire, vous devez la concevoir pour offrir une expérience utilisateur optimale.

Les meilleurs modules complémentaires étendent naturellement chaque éditeur à l'aide de commandes et de comportements familiers. Lorsque vous créez un module complémentaire:

Texte

Nom du module complémentaire

Vous devez définir le nom de votre module complémentaire lorsque vous le publiez. Il apparaît à de nombreux endroits, par exemple dans la boutique de modules complémentaires et dans les menus.

  • Utilisez une casse de titre.
  • Évitez les signes de ponctuation, en particulier les parenthèses, sauf s'ils font partie de votre marque.
  • Soyez concis : mieux vaut ne pas dépasser 30 caractères. Les noms longs peuvent être tronqués automatiquement.
  • N'incluez pas le nom du produit Google auquel le module complémentaire est destiné (ou utilisez le mot Google).
  • N'indiquez pas les informations de version.
  • Assurez-vous que le nom publié du module complémentaire est identique à celui du projet de script. Le nom du projet apparaît dans la boîte de dialogue d'autorisation.
À éviter À faire
Noms de modules complémentaires incorrects Noms de modules complémentaires corrects

Style de rédaction

Vous ne devriez pas avoir besoin d'écrire beaucoup. La plupart des actions doivent être claires grâce à l'iconographie, à la mise en page et aux libellés courts. Si vous pensez qu'une partie de votre module complémentaire nécessite des explications plus détaillées que celles fournies par les libellés courts, il est recommandé de créer une page Web distincte décrivant votre module complémentaire et un lien vers celui-ci.

Lors de la rédaction d'un texte d'interface utilisateur:

  • Seule la première lettre doit être en majuscule (en particulier pour les boutons, les libellés et les éléments de menu).
  • Préférez le texte simple et court sans jargon ni acronyme.
À éviter À faire

Conseil post-installation

Votre conseil de post-installation s'affiche dès qu'un utilisateur installe votre module complémentaire et apparaît dans l'aide. Voici quelques phrases pour aider les utilisateurs à démarrer rapidement.

  • Commencez par un mot d'action.
  • Décrivez la première étape d'utilisation de votre module complémentaire.
  • Si vous disposez d'une interface utilisateur principale, telle qu'une barre latérale, expliquez comment l'ouvrir.
  • Ne faites pas la promotion de votre module complémentaire ici, car il est déjà installé.
À éviter À faire
Conseil post-installation incorrect Bon conseil après l'installation

Contrairement aux projets Apps Script standards, les modules complémentaires n'apparaissent pas dans l'éditeur ni dans le gestionnaire de scripts. Les utilisateurs ne peuvent pas exécuter de scripts de modules complémentaires directement. Au lieu de cela, chaque module complémentaire s'affiche dans le menu des modules complémentaires. Le menu (et éventuellement une boîte de dialogue ou une barre latérale) permet aux utilisateurs d'interagir avec le module complémentaire.

  • Le menu est un élément clé de la manière dont les utilisateurs contrôlent votre module complémentaire. Par conséquent, concevez sa structure et ses termes avec soin.
  • Évitez les éléments de menu qui se contentent de répéter le nom de votre module complémentaire. Commencez par un mot d'action.
  • Si votre élément de menu principal démarre un workflow et qu'aucun verbe ne décrit ce qu'il fait, appelez-le "Démarrer". Ce schéma est utilisé dans le guide de démarrage rapide du module complémentaire Docs.
  • À moins que votre menu ne comporte plus de six éléments, essayez de ne pas utiliser de sous-menus. Ils peuvent être difficiles à sélectionner.
  • Décrivez la tâche, et non le composant d'UI affiché par l'élément de menu.
À éviter À faire
Libellés d'élément de menu incorrects Étiquettes de menu efficaces

Messages d'erreur

Lorsqu'un problème survient, il est important d'utiliser un langage simple. Expliquez le problème du point de vue de l'utilisateur et suggérez une solution.

  • Ne pas autoriser l'utilisateur à voir les exceptions que votre code génère. À la place, utilisez des instructions try...catch pour intercepter les exceptions, puis affichez un message d'erreur généré par l'utilisateur avec un texte intégré stylisé dans la classe error du package CSS des modules complémentaires ou une boîte de dialogue d'alerte.
  • Avant la publication, vérifiez que votre module complémentaire n'enregistre pas les informations de débogage dans la console JavaScript. Utilisez Stackdriver Logging à la place.
À éviter À faire
Message d'erreur incorrect Message d'erreur correct

Les contenus d'aide

Le menu de chaque module complémentaire inclut une boîte de dialogue d'aide automatique. Si vous indiquez une URL d'aide lors de la publication, le bouton "En savoir plus" renvoie vers cette page. Sauf indication contraire de votre part, veuillez fournir une page expliquant comment l'utiliser.

  • Si possible, affichez les instructions sous forme de liste à puces ou de liste numérotée. Guidez les utilisateurs jusqu'au résultat final, avec des références claires aux éléments d'interface utilisateur nommés.
  • Assurez-vous que vos instructions expliquent clairement les conditions requises, par exemple pour configurer une feuille de calcul d'une certaine manière.
  • N'hésitez pas à inclure également un lien vers le contenu d'aide dans votre interface utilisateur principale. Si votre module complémentaire crée un document actualisé, vous pouvez également afficher des instructions dans le corps du document.

Interfaces utilisateur personnalisées

Certains modules complémentaires simples d'éditeurs peuvent être contrôlés entièrement via leur menu, mais la plupart affichent une barre latérale ou une boîte de dialogue avec du contenu personnalisé.

  • Les barres latérales sont idéales pour les outils persistants que les utilisateurs sont susceptibles d'utiliser à plusieurs reprises lorsqu'ils font référence au contenu de leur document ou feuille de calcul.
  • Les boîtes de dialogue sont idéales pour les outils à usage unique, les pages de paramètres et les messages importants.

Texte de l'UI

Dans une boîte de dialogue ou une barre latérale, partez du principe que les utilisateurs ne lisent que le titre et les boutons. Peuvent-ils toujours comprendre les fonctionnalités de votre interface et faire un bon choix ?

  • Utilisez un titre et des libellés de bouton qui restent seuls.
  • Évitez les longs blocs de texte descriptif.

Boîtes de dialogue

Les boîtes de dialogue sont idéales pour utiliser les outils une fois, puis passer à autre chose. Par exemple, si votre module complémentaire permet aux utilisateurs d'insérer un graphique, vous pouvez afficher une boîte de dialogue avec des options à insérer, puis fermer la boîte de dialogue une fois le graphique inséré. Les boîtes de dialogue sont également utiles pour afficher les paramètres de votre module complémentaire ou pour communiquer un message important.

  • N'ouvrez pas une boîte de dialogue (y compris une alerte ou une invite) provenant d'une autre boîte de dialogue. Affichez-en une seule à la fois.
  • Pour le titre de la boîte de dialogue, utilisez un mot ou une phrase courte, commençant par le mot le plus important.
  • Les libellés des boutons doivent être en rapport avec le titre de la boîte de dialogue.
  • Privilégiez deux boutons, qui correspondent généralement à une action principale et à une annulation. Dans les cas particuliers nécessitant un troisième bouton, tenez compte de l'angle inférieur droit.
  • Placez les boutons en bas à gauche de la boîte de dialogue. Le bouton principal bleu doit se trouver à gauche, et les boutons secondaires gris à droite.
À éviter À faire
Titre de la boîte de dialogue incorrect Titre correct de la boîte de dialogue

Les barres latérales permettent aux utilisateurs de consulter leur document, feuille de calcul, présentation ou formulaire tout en faisant des choix. Elles permettent également aux utilisateurs d'utiliser votre module complémentaire à plusieurs reprises. Lorsqu'une nouvelle barre latérale est ouverte, toutes les barres latérales précédentes se ferment automatiquement. Ils conviennent mieux aux modes temporaires que l'utilisateur quitte lorsqu'il a terminé.

  • Les utilisateurs peuvent disposer d'autres modules complémentaires dotés de leurs propres barres latérales. Si deux modules complémentaires tentent d'ouvrir les barres latérales simultanément, un seul s'affiche.
  • Ne pas afficher de barre latérale ni de boîte de dialogue lorsqu'un document s'ouvre pour la première fois.
  • Seuls les modules complémentaires opérant dans AuthMode.FULL peuvent ouvrir les barres latérales ou les boîtes de dialogue. Vous pouvez utiliser un élément de menu pour ouvrir une barre latérale, car cela invite l'utilisateur à fournir une autorisation complète.

Commandes

Des interfaces utilisateur très performantes laissent une certaine marge de manœuvre à leurs commandes. Les marges et la marge intérieure adéquates peuvent faire une grande différence, alors que les contrôles denses peuvent sembler insurmontables. En cas de doute, empruntez une mise en page à l'éditeur lui-même. Par exemple, examinez les boîtes de dialogue existantes dans Google Docs, telles que Fichier > Configuration de la page, lorsque vous créez la vôtre.

La documentation du package CSS de modules complémentaires fournit un exemple de balisage pour chacun des types de commandes ci-dessous.

Boutons

Utilisez des boutons pour contrôler les actions principales de votre interface utilisateur plutôt que des liens simples ou d'autres éléments.

  • Évitez d'afficher plusieurs boutons bleus, rouges ou verts à la fois. Des boutons gris peuvent apparaître à plusieurs reprises.
  • La plupart des libellés des boutons doivent être en majuscules et commencer par un verbe. Les boutons rouges, généralement pour les actions de création, doivent être en majuscules.
À éviter À faire

Cases à cocher et cases d'option

Utilisez les cases à cocher lorsque les utilisateurs peuvent sélectionner plusieurs options ou n'en sélectionner aucune. Utilisez les cases d'option (ou un menu de sélection) lorsqu'une seule option doit être sélectionnée.

  • Ne modifiez pas le comportement des cases à cocher pour imiter les cases d'option.
  • Ne faites rien immédiatement lorsqu'ils sont cochés. Les gens font des erreurs. Attendez que vos utilisateurs cliquent sur un bouton pour confirmer leurs choix.

Sélectionner des menus

Les sélections constituent un excellent moyen de proposer une courte sélection d'alternatives.

  • Triez les options par ordre alphabétique ou selon un schéma logique que tous les utilisateurs peuvent comprendre (par exemple, les jours de la semaine à partir du dimanche).
  • Si la liste s'allonge, envisagez d'utiliser une autre commande. Par exemple, vous pouvez afficher une liste déroulante pour donner plus d'espace au menu et faciliter la navigation.

Les zones de texte

Si les utilisateurs doivent saisir plusieurs mots, utilisez une zone de texte.

  • Créez des zones de texte d'au moins deux lignes de haut, pour qu'elles soient plus faciles à utiliser et ne ressemblent pas à des champs de texte.
  • Placez les libellés sur le dessus.

Champs de texte

Utilisez des champs de texte si les utilisateurs doivent seulement saisir un ou deux mots.

  • La largeur d'un champ de texte doit indiquer ce que les utilisateurs sont susceptibles de saisir.
  • Évitez d'utiliser un espace réservé pour le libellé, car il disparaît. Le texte d'espace réservé permet de donner des exemples ou des détails supplémentaires.
  • Placez les étiquettes au-dessus, mais n'hésitez pas à disposer les champs de texte courts côte à côte.

Branding

Dans votre module complémentaire

Si vous souhaitez inclure un branding, soyez concis. Cela permet aux utilisateurs de se concentrer sur votre interface utilisateur et donne à votre module complémentaire l'impression de faire partie de l'éditeur.

  • Tous les aspects de votre module complémentaire doivent respecter les consignes relatives à la marque.
  • N'incluez pas le mot "Google" ni les icônes de produit Google.
  • Le texte ne doit pas dépasser quelques mots et doit être stylisé dans la classe gray du package CSS de modules complémentaires.
  • L'arrière-plan des images doit être de 200 x 60 pixels maximum.
  • Pour les boîtes de dialogue, le branding doit apparaître en bas à droite.
  • Pour les barres latérales, le branding peut se trouver en haut ou en bas.

En magasin

Pour publier un module complémentaire Editor, vous avez besoin d'un nombre d'assets image. Ces éléments permettent de créer la fiche Play Store du module complémentaire.

Accessibilité

Tout le monde doit pouvoir profiter de votre module complémentaire, que les couleurs soient différentes, utiliser un lecteur d'écran ou avoir d'autres besoins. L'accessibilité est un thème général qui ne peut pas être entièrement traité dans ce guide de style. Le site Google Accessibilité constitue une ressource utile. Voici quelques conseils pour commencer:

  • Assurez-vous que vous pouvez accéder à toutes les commandes de l'interface utilisateur à l'aide du clavier. Ajoutez tabindex=0 aux commandes personnalisées (comme celles créées avec <div>) afin que les utilisateurs puissent y accéder. Déterminez si d'autres clés doivent également être acceptées, comme les flèches pour une liste.
  • Certaines personnes peuvent utiliser un lecteur d'écran avec votre module complémentaire. Ainsi, les images doivent comporter un attribut alt, et les commandes personnalisées doivent comporter des attributs ARIA pour décrire leur utilisation.
  • Ne vous fiez pas seulement à la couleur pour communiquer l'état. Utilisez également des icônes et du texte.

Si vous utilisez des commandes Web standards, comme celles décrites précédemment dans ce guide, il est plus facile d'accéder à votre module complémentaire.