Styleguide für UI-Editoren

Mit Editor-Add-ons erstellen Sie Benutzeroberflächen (Menüs, Seitenleisten und Dialogfelder) mit dem HTML-Dienst von Apps Script. Da die Schnittstellen in HTML und CSS entwickelt werden, sind sie bestens anpassbar. Wenn Sie Ihre Add-on-Oberfläche erstellen, sollten Sie sie jedoch so gestalten, dass sie besonders nutzerfreundlich ist.

Die besten Add-ons erweitern jeden Editor auf natürliche Weise durch vertraute Steuerelemente und Verhaltensweisen. Beim Erstellen eines neuen Add-ons:

  • Verwenden Sie das CSS-Paket für Add-ons auf Ihren HTML-Dienstseiten.
  • Wenn Sie sich bezüglich des Designs nicht sicher sind, suchen Sie im Editor ein ähnliches Dialogfeld oder eine ähnliche Seitenleiste oder rufen Sie die Kurzanleitung für Add-ons auf.
  • Befolgen Sie diesen Styleguide, um eine nahtlose Erfahrung zu schaffen.

Text

Add-on-Name

Sie müssen den Namen des Add-ons festlegen, wenn Sie es veröffentlichen. Der Name erscheint an vielen Stellen, z. B. im Add-on-Store und in Menüs.

  • Achten Sie auf die korrekte Groß- und Kleinschreibung.
  • Vermeiden Sie Satzzeichen, insbesondere Klammern, sofern sie nicht zu Ihrem Unternehmen gehören.
  • Fasse dich kurz – 30 oder weniger Zeichen sind am besten. Lange Namen werden möglicherweise automatisch abgeschnitten.
  • Geben Sie nicht den Namen des Google-Produkts an, für das das Add-on bestimmt ist, und verwenden Sie nicht das Wort „Google“.
  • Lassen Sie die Versionsinformationen weg.
  • Der veröffentlichte Name des Add-ons muss mit dem Dateinamen des Skriptprojekts übereinstimmen. Der Projektname wird im Dialogfeld für die Autorisierung angezeigt.
Das sollten Sie lassen: Dos
Ungültige Add-on-Namen Gute Add-on-Namen

Schreibstil

Sie müssen nicht viel schreiben. Die meisten Aktionen sollten durch Symbole, Layouts und kurze Beschriftungen verdeutlicht werden. Wenn Sie feststellen, dass ein Teil Ihres Add-ons ausführlicher erklärt werden muss, als es mit kurzen Labels möglich ist, empfiehlt es sich, eine separate Webseite zu erstellen, die das Add-on beschreibt, und einen Link zu ihm zu erstellen.

Beim Schreiben von UI-Text:

  • Verwenden Sie die im Deutschen übliche Groß- und Kleinschreibung (insbesondere bei Schaltflächen, Beschriftungen und Menüelementen).
  • Ich bevorzuge einen kurzen, einfachen Text ohne Fachjargon oder Akronyme.
Das sollten Sie lassen: Dos

Tipp nach der Installation

Der Tipp nach der Installation wird direkt nach der Installation Ihres Add-ons angezeigt und ist auch in der Hilfe zu sehen. Sie haben ein paar Sätze, um Nutzenden einen schnellen Einstieg zu erleichtern.

  • Beginnen Sie mit einem Aktionswort.
  • Beschreiben Sie den ersten Schritt zur Verwendung des Add-ons.
  • Erläutern Sie, wie Sie eine Haupt-UI wie z. B. eine Seitenleiste öffnen.
  • Werben Sie hier nicht für Ihr Add-on, da es bereits installiert ist.
Das sollten Sie lassen: Dos
Schlechter Tipp nach der Installation Guter Tipp nach der Installation

Im Gegensatz zu normalen Apps Script-Projekten werden Add-ons nicht im Skripteditor oder im Skriptmanager angezeigt. Nutzer können Add-on-Skripts nicht direkt ausführen. Stattdessen erhält jedes Add-on einen Platz im Add-on-Menü. Über das Menü (und möglicherweise ein Dialogfeld oder eine Seitenleiste) können Nutzer mit dem Add-on interagieren.

  • Das Menü ist ein wichtiger Bestandteil dafür, wie Nutzer Ihr Add-on steuern. Gestalten Sie daher die Struktur und den Wortlaut sorgfältig.
  • Vermeiden Sie Menüpunkte, in denen nur der Name Ihres Add-ons wiederholt wird. Beginnen Sie stattdessen mit einem Wort.
  • Wenn Ihr Hauptmenüpunkt einen Workflow startet und es kein einzelnes Verb gibt, das seine Funktion beschreibt, nennen Sie es "Start". Es wird in der Kurzanleitung zum Add-on für Docs verwendet.
  • Verwenden Sie keine Untermenüs, es sei denn, Ihre Speisekarte enthält mehr als sechs Elemente. Sie können knifflig und schwer auszuwählen sein.
  • Beschreiben Sie die Aufgabe, nicht die UI-Komponente, die im Menüelement angezeigt wird.
Das sollten Sie lassen: Dos
Ungültige Labels für Menüelemente Gute Labels für Speisekartenartikel

Fehlermeldungen

Wenn etwas schiefgeht, ist es wichtig, einfache Formulierungen zu verwenden. Erklären Sie das Problem aus Sicht der Nutzenden und schlagen Sie vor, wie es behoben werden kann.

  • Der Nutzer darf keine Ausnahmen sehen, die von Ihrem Code ausgelöst werden. Verwenden Sie stattdessen try...catch-Anweisungen, um Ausnahmen abzufangen. Zeigen Sie dann eine vom Nutzer unkomplizierte Fehlermeldung mit Inline-Text in der Klasse error aus dem Add-on-CSS-Paket oder einem Benachrichtigungsdialogfeld an.
  • Achten Sie vor der Veröffentlichung darauf, dass das Add-on keine Informationen zur Fehlerbehebung in der JavaScript-Konsole protokolliert. Verwenden Sie stattdessen Stackdriver Logging.
Das sollten Sie lassen: Dos
Ungültige Fehlermeldung Gute Fehlermeldung

Hilfeinhalte

Das Menü jedes Add-ons enthält einen automatischen Hilfedialog. Wenn Sie bei der Veröffentlichung eine Hilfe-URL angeben, verweist die Schaltfläche „Weitere Informationen“ auf diese Seite. Sofern Ihr Add-on nicht selbsterklärend ist, geben Sie bitte eine Seite an, auf der die Verwendung erklärt wird.

  • Zeigen Sie die Anleitung nach Möglichkeit als Aufzählung oder nummerierte Liste. Gehen Sie die Nutzer bis zum Endergebnis mit eindeutigen Verweisen auf benannte UI-Elemente vor.
  • Achten Sie darauf, dass in Ihrer Anleitung alle Anforderungen, z. B. das Einrichten einer Tabelle, klar erläutert werden.
  • Sie können auch von Ihrer Hauptbenutzeroberfläche aus Links zu Ihren Hilfeinhalten einfügen. Wenn Ihr Add-on ein neues Dokument erstellt, können Sie auch eine Anleitung im Textkörper des Dokuments anzeigen lassen.

Benutzerdefinierte Benutzeroberflächen

Einige einfache Editor-Add-ons können vollständig über ihr Menü gesteuert werden. Die meisten zeigen jedoch eine Seitenleiste oder ein Dialogfeld mit benutzerdefiniertem Inhalt an.

  • Seitenleisten eignen sich am besten für langlebige Tools, die Nutzer häufig mehrmals verwenden, wenn sie auf den Inhalt eines Dokuments oder einer Tabelle verweisen.
  • Dialogfelder eignen sich am besten für Tools zur einmaligen Verwendung, auf Einstellungsseiten und für wichtige Nachrichten.

UI-Text

Gehen Sie in jedem Dialogfeld oder in der Seitenleiste davon aus, dass nur der Titel und die Schaltflächenlabels gelesen werden. Können sie trotzdem herausfinden, was Ihre Benutzeroberfläche bietet, und eine gute Wahl treffen?

  • Verwenden Sie für sich eigenständige Titel und Schaltflächen.
  • Vermeiden Sie lange Blöcke mit beschreibendem Text.

Dialogfelder

Dialoge eignen sich hervorragend für Tools, die Nutzer einmal verwenden und dann später weitermachen. Wenn Ihr Add-on beispielsweise Nutzern das Einfügen einer Grafik ermöglicht, können Sie ein Dialogfeld mit der Auswahlmöglichkeit, was eingefügt werden soll, anzeigen und das Dialogfeld schließen, wenn die Grafik eingefügt wird. Dialogfelder sind auch hilfreich, um die Einstellungen Ihres Add-ons anzuzeigen oder eine wichtige Nachricht zu übermitteln.

  • Öffnen Sie keine Dialoge (einschließlich Warnungen oder Aufforderungen) in einem anderen Dialogfeld, sondern zeigen Sie jeweils nur ein Dialogfeld an.
  • Verwenden Sie als Titel des Dialogfelds ein Wort oder eine kurze Wortgruppe, die mit dem wichtigsten Wort beginnt.
  • Schaltflächenbeschriftungen sollten sich auf den Titel des Dialogfelds beziehen.
  • Bevorzugen Sie zwei Schaltflächen, in der Regel eine primäre Aktion und „Abbrechen“. Für Sonderfälle, in denen eine dritte Schaltfläche erforderlich ist, empfiehlt sich die untere rechte Ecke.
  • Platzieren Sie Schaltflächen in die linke untere Ecke des Dialogfelds. Die blaue Hauptschaltfläche sollte sich links befinden, die grauen sekundären Schaltflächen rechts.
Das sollten Sie lassen: Dos
Ungültiger Dialogtitel Guter Dialogtitel

Über Seitenleisten können Nutzende auf ihr Dokument, ihre Tabelle, ihre Präsentation oder ihr Formular zurückgreifen, während sie eine Auswahl treffen. Außerdem können Nutzer Ihr Add-on dadurch wiederholt verwenden. Immer wenn eine neue Seitenleiste geöffnet wird, wird die vorherige wird automatisch geschlossen. Sie eignen sich am besten für temporäre Modi, die der Nutzer nach Abschluss des Vorgangs beendet.

  • Nutzer haben möglicherweise andere Add-ons mit eigenen Seitenleisten. Wenn zwei Add-ons versuchen, Seitenleisten gleichzeitig zu öffnen, wird nur eine angezeigt.
  • Beim ersten Öffnen eines Dokuments keine Seitenleiste und kein Dialogfeld anzeigen.
  • Nur Add-ons, die in AuthMode.FULL ausgeführt werden, können Seitenleisten oder Dialogfelder öffnen. Sie können einen Menüpunkt verwenden, um eine Seitenleiste zu öffnen, da der Nutzer dadurch zur vollständigen Autorisierung aufgefordert wird.

Steuerung

Tolle Add-on-UIs lassen ihren Steuerungen etwas Spielraum. Angemessene Ränder und Innenabstände helfen, während dichte Steuerelemente überwältigend erscheinen können. Wenn Sie sich nicht sicher sind, nehmen Sie ein Layout vom Editor selbst. Prüfen Sie beispielsweise die vorhandenen Dialogfelder in Google Docs (z. B. Datei > Seiteneinrichtung), wenn Sie ein eigenes Dialogfeld erstellen.

Die Dokumentation zum CSS-Paket für Add-ons enthält Beispiel-Markup für die folgenden Arten von Steuerelementen.

Schaltflächen

Verwenden Sie Schaltflächen anstelle von einfachen Links oder anderen Elementen, um die Hauptaktionen Ihrer Benutzeroberfläche zu steuern.

  • Vermeiden Sie es, mehr als eine blaue, rote oder grüne Schaltfläche gleichzeitig anzuzeigen. Graue Schaltflächen können wiederholt erscheinen.
  • Bei den meisten Schaltflächenbeschriftungen wird die Groß-/Kleinschreibung des Satzes beachtet und die Wörter müssen mit einem Verb beginnen. Bei roten Schaltflächen, die normalerweise zum Erstellen von Aktionen verwendet werden, sollten ausschließlich Großbuchstaben verwendet werden.
Das sollten Sie lassen: Dos

Kästchen und Optionsfelder

Verwenden Sie Kontrollkästchen, wenn Nutzer mehrere oder gar keine Optionen auswählen können. Verwenden Sie Optionsfelder (oder ein Auswahlmenü), wenn genau eine Option ausgewählt werden muss.

  • Ändern Sie das Verhalten von Kästchen nicht, um Optionsfelder zu imitieren.
  • Tun Sie nicht sofort etwas, nachdem sie überprüft wurden. Menschen machen Fehler. Warten Sie, bis Ihre Nutzer auf eine Schaltfläche klicken, um ihre Auswahl zu bestätigen.

Menüs auswählen

Mit Selecten kannst du eine kurze Liste von Alternativen anbieten.

  • Sortieren Sie die Optionen alphabetisch oder nach einem logischen Schema, das alle Nutzer verstehen können (z. B. Wochentage, beginnend mit Sonntag).
  • Wenn die Liste zu lang wird, sollten Sie ein anderes Steuerelement verwenden. Sie können beispielsweise eine scrollbare Liste anzeigen lassen, um dem Menü mehr Platz zu geben und die Navigation zu vereinfachen.

Textbereiche

Wenn Nutzer mehr als ein paar Wörter eingeben müssen, verwenden Sie einen Textfeld.

  • Textfelder sollten mindestens zwei Zeilen hoch sein, damit sie einfacher zu verwenden sind und nicht wie Textfelder aussehen.
  • Platzieren Sie Labels oben.

Textfelder

Verwenden Sie Textfelder, wenn Nutzer nur ein oder zwei Wörter eingeben müssen.

  • Die Breite eines Textfelds sollte Aufschluss darüber geben, was die Nutzer voraussichtlich eingeben werden.
  • Verwenden Sie keinen Platzhaltertext als Beschriftung, da er im Fokus verschwindet. Platzhaltertexte sind nützlich, um Beispiele oder zusätzliche Details anzugeben.
  • Platzieren Sie Labels oben, aber legen Sie auch kurze Textfelder nebeneinander an.

Branding

Im Add-on

Wenn du Branding einbeziehen möchtest, halte es kurz und bündig. So können sich die Nutzer auf die Benutzeroberfläche konzentrieren und das Add-on fühlt sich wie ein Teil des Editors an.

  • Alle Aspekte Ihres Add-ons müssen den Branding-Richtlinien entsprechen.
  • Verwenden Sie nicht das Wort „Google“ und verwenden Sie keine Google-Produktsymbole.
  • Der Text sollte nur wenige Wörter enthalten und in der Klasse gray aus dem CSS-Paket für Add-ons formatiert sein.
  • Die Grafiken sollten auf einem weißen Hintergrund und nicht größer als 200 × 60 Pixel sein.
  • Bei Dialogen sollte das Branding in der unteren rechten Ecke angezeigt werden.
  • Bei Seitenleisten kann das Branding oben oder unten platziert werden.

Im Geschäft

Sie benötigen eine Reihe von Bild-Assets, um ein Editor-Add-on zu veröffentlichen. Aus diesen Assets wird der Store-Eintrag für das Add-on erstellt.

Barrierefreiheit

Das Add-on sollte für alle interessant sein, unabhängig davon, ob sie Farben anders sehen, einen Screenreader verwenden oder andere Anforderungen haben. Barrierefreiheit ist ein breites Thema, das in diesem Styleguide nicht vollständig behandelt wird. Eine hilfreiche Ressource ist die Website Google Barrierefreiheit im Internet. Hier sind jedoch ein paar Tipps für den Einstieg:

  • Prüfen Sie, ob Sie mit der Tastatur zu allen UI-Steuerelementen wechseln können. Fügen Sie benutzerdefinierten Steuerelementen (z. B. mit <div>) tabindex=0 hinzu, damit Nutzer mit der Tabulatortaste darauf zugreifen können. Überlegen Sie, ob auch andere Schlüssel unterstützt werden sollen, z. B. Pfeile für eine Liste.
  • Einige Nutzer verwenden möglicherweise einen Screenreader mit Ihrem Add-on. Daher sollten Bilder ein alt-Attribut und benutzerdefinierte Steuerelemente ARIA-Attribute haben, um ihre Verwendung zu beschreiben.
  • Verlassen Sie sich bei der Kommunikation des Zustands nicht nur auf Farbe. Verwenden Sie auch Symbole und Text.

Wenn Sie Standard-Websteuerelemente wie die weiter oben in diesem Leitfaden beschriebenen verwenden, ist es einfacher, auf Ihr Add-on zuzugreifen.