エディタ アドオンの UI スタイルガイド

エディタ用アドオンは、Apps Script の HTML サービスを使用してユーザー インターフェース(メニュー、サイドバー、ダイアログ)を作成します。インターフェースは HTML と CSS で開発されているため、高度なカスタマイズが可能です。ただし、アドオン インターフェースを作成する際は、優れたユーザー エクスペリエンスを提供するように設計する必要があります。

最適なアドオンは、使い慣れたコントロールと動作を使用して各エディタを自然に拡張します。新しいアドオンを作成する場合:

テキスト

アドオン名

アドオンは、公開するときに設定する必要があります。この名前は、アドオンストアやメニュー内など、さまざまな場所に表示されます。

  • 語頭を大文字にします。
  • ブランドに含まれる場合を除き、句読点(特に括弧)は使用しないでください。
  • 文字数は半角 30 文字(全角 15 文字)以内にしてください。長い名前は自動的に切り捨てられる場合があります。
  • アドオンの対象である Google プロダクトの名前は含めないでください(または、Google という単語を使用します)。
  • バージョン情報は省略します。
  • アドオンの公開名がスクリプト プロジェクトのファイル名と同じであることを確認します。承認ダイアログにプロジェクト名が表示されます。
悪い例 良い例
アドオン名が正しくありません 適切なアドオン名

文章のスタイル

それほど多くの記述は必要ありません。ほとんどのアクションは、アイコン画像、レイアウト、短いラベルで明確に表す必要があります。アドオンの一部に短いラベルでは説明しきれない詳細な説明が必要な場合は、アドオンとそのリンクについて説明する別のウェブページを作成することをおすすめします。

UI テキストを記述する場合:

  • 文頭を大文字にします(特にボタン、ラベル、メニュー項目の場合)。
  • 専門用語や頭字語を使わず、簡潔で簡潔な文章にしてください。
悪い例 良い例

インストール後のヒント

インストール後のヒントは、アドオンがインストールされた直後にポップアップし、[ヘルプ] にも表示されます。ユーザーがすぐに使い始められるように、簡単な文をしましょう。

  • アクションの単語から始めます。
  • アドオンを使用する最初のステップについて説明してください。
  • サイドバーなどのメイン UI がある場合は、その UI を開く方法について説明します。
  • インストール済みのアドオンをここで宣伝しないでください。
悪い例 良い例
インストール後の不適切なヒント インストール後の効果的なヒント

通常の Apps Script プロジェクトとは異なり、アドオンはスクリプト エディタやスクリプト マネージャーには表示されません。ユーザーはアドオン スクリプトを直接実行できません。代わりに、すべてのアドオンがアドオン メニューに追加されます。ユーザーはメニュー(ダイアログやサイドバー)でアドオンを操作できます。

  • メニューはユーザーがアドオンを制御する際の重要な部分であるため、メニューの構成と言い回しは慎重に設計してください。
  • アドオンの名前を繰り返すだけのメニュー項目は避けてください。代わりに、アクション ワードから始めます。
  • メインメニュー項目がワークフローの開始時に、その内容を表す単一の動詞がない場合は、「開始」と呼ぶことにします。このパターンは、ドキュメント アドオンのクイックスタートで使用されます。
  • メニューに 6 項目以上ある場合を除き、サブメニューを使用しないでください。慎重に選択しにくい場合もあります。
  • メニュー項目に表示される UI コンポーネントではなく、タスクを記述します。
悪い例 良い例
不適切なメニュー項目のラベル 適切なメニュー項目のラベル

エラーメッセージ

問題が発生した場合には、わかりやすい言葉を使うことが重要です。ユーザーの視点から問題を説明し、修正方法を提案します。

  • コードがスローした例外をユーザーが確認できないようにします。代わりに、try...catch ステートメントを使用して例外をインターセプトし、アドオン CSS パッケージの error クラスまたはアラート ダイアログのインライン テキストでユーザーが操作したエラー メッセージを表示します。
  • 公開する前に、アドオンによってデバッグ情報が JavaScript コンソールにログされないことを確認してください。代わりに、Stackdriver ロギングを使用してください。
悪い例 良い例
不適切なエラー メッセージ 適切なエラー メッセージ

ヘルプ コンテンツ

すべてのアドオンのメニューには、自動ヘルプ ダイアログがあります。公開時にヘルプの URL を指定すると、[詳細] ボタンがそのページにリンクされます。説明不要でない限り、使用方法を説明するページを提供してください。

  • 可能な場合は、箇条書きや番号付きリストで手順を示します。名前付きの UI 要素への明確な参照とともに、ユーザーに最終結果について説明します。
  • 手順では、特定の方法でのスプレッドシートの設定など、要件を明確に説明するようにしてください。
  • メインのユーザー インターフェースからもヘルプ コンテンツへのリンクを自由に設定してください。 アドオンによって新しいドキュメントが作成される場合は、ドキュメントの本文に手順を表示することもできます。

カスタム ユーザー インターフェース

一部のシンプルなエディタ アドオンはメニューで完全に制御できますが、ほとんどの場合、カスタム コンテンツを含むサイドバーまたはダイアログが表示されます。

  • サイドバーは、ドキュメントやスプレッドシートのコンテンツを参照する際に繰り返し使用する可能性が高い永続的なツールに最適です。
  • ダイアログは、使い捨てのツール、設定ページ、重要なメッセージに最適です。

UI テキスト

ダイアログやサイドバーにおいて、ユーザーはタイトルとボタンラベルのみを読むものと想定します。それでもユーザーにインターフェースの機能を理解してもらえ、よい選択ができるか。

  • 独立したタイトルとボタンラベルを使用します。
  • 説明を長文に区切らないでください。

ダイアログ

ダイアログは、一度使った後に次に進むツールに適しています。たとえば、アドオンでユーザーがグラフィックを挿入できる場合、挿入する内容の選択肢を示すダイアログを表示して、グラフィックの挿入時にダイアログを閉じることができます。ダイアログは、アドオンの設定を表示する場合や、重要なメッセージを伝達する場合にも便利です。

  • 別のダイアログからダイアログ(アラートやプロンプトを含む)を開かず、一度に 1 つずつ表示してください。
  • ダイアログのタイトルには、最も重要な単語で始まる単語または短いフレーズを使用します。
  • ボタンのラベルはダイアログのタイトルと関連している必要があります。
  • 2 つのボタン(通常はメインの操作と [キャンセル])を使用します。3 つ目のボタンが必要な特殊なケースでは、右下隅を考慮してください。
  • ボタンはダイアログの左下に配置します。青色のメインボタンを左側に、灰色のセカンダリ ボタンを右側に配置する必要があります。
悪い例 良い例
ダイアログのタイトルが正しくありません ダイアログのタイトルが適切

サイドバーを使用すると、選択する際にドキュメント、スプレッドシート、プレゼンテーション、フォームを参照できます。また、ユーザーがアドオンを繰り返し使用できるようになります。 新しいサイドバーが開くと、それより前に作成されたサイドバーは自動的に閉じます。これは、操作が完了したらユーザーが終了する一時的なモードに最適です。

  • 独自のサイドバーがある他のアドオンを利用できる場合もあります。2 つのアドオンが同時にサイドバーを開こうとした場合は、いずれか 1 つのみが表示されます。
  • ドキュメントを初めて開いたときにサイドバーやダイアログを表示しないようにします。
  • サイドバーやダイアログを開くことができるのは、AuthMode.FULL で動作しているアドオンのみです。メニュー項目を使用してサイドバーを開くことができます。これは、ユーザーに完全な承認を求めるプロンプトが表示されるためです。

操作

優れたアドオン UI は、コントロールに余裕を持たせています。適切なマージンとパディングがあれば大きな効果を発揮しますが、密なコントロールは煩雑に感じられるかもしれません。判断に迷う場合は、エディタ自体からレイアウトを借りることができます。たとえば、独自のダイアログを作成するときに、Google ドキュメントの既存のダイアログ([ファイル] > [ページ設定] など)を確認します。

アドオン CSS パッケージのドキュメントには、コントロール タイプごとにマークアップのサンプルが記載されています。

ボタン

ユーザー インターフェースのメイン アクションを制御するには、プレーンなリンクなどの要素ではなく、ボタンを使用します。

  • 青色、赤色、緑色の複数のボタンを同時に表示しないでください。灰色のボタンが繰り返し表示されることがあります。
  • ほとんどのボタンラベルは、文頭を大文字にして、動詞で始める必要があります。赤色のボタンは、通常は作成アクション用で、すべて大文字にする必要があります。
悪い例 良い例

チェックボックスとラジオボタン

ユーザーが複数の選択肢を選択できる場合、または選択肢がまったく選択できない場合は、チェックボックスを使用します。オプションを 1 つだけ選択する必要がある場合は、ラジオボタン(選択メニュー)を使用します。

  • チェックボックスの動作を変更してラジオボタンを模倣しないでください。
  • チェック後すぐには何もしないでください。ミスをすることもあります。ユーザーが選択内容を確認するボタンをクリックするまで待ちます。

メニューを選択

「選択」は、代替案の簡単なリストを提供するのに最適な方法です。

  • オプションをアルファベット順、またはすべてのユーザーが理解できる論理的なスキーム(日曜日から始まる曜日など)で並べ替えます。
  • リストが長すぎる場合は、別のコントロールの使用を検討してください。たとえば、スクロール可能なリストを表示して、メニューのスペースを広げ、移動しやすくすることができます。

テキスト エリア

複数の単語を入力する必要がある場合は、テキスト領域を使用します。

  • テキスト領域の高さを 2 行以上にして使いやすくし、テキスト フィールドのように見えないようにします。
  • ラベルを上に配置します。

テキスト フィールド

ユーザーが 1 ~ 2 語だけ入力する必要がある場合にテキスト フィールドを使用します。

  • テキスト フィールドの幅は、ユーザーが入力すると思われるフィールドの幅を反映したものにする必要があります。
  • プレースホルダ テキストをラベルとして使用しないでください。フォーカスされると非表示になります。プレースホルダ テキストは、例や追加情報を与えるのに役立ちます。
  • ラベルは上に配置しますが、短いテキスト フィールドは横に並べて配置しても構いません。

ブランディング

アドオン

ブランドを表示したい場合は、簡潔で明快なものにします。これにより、ユーザーは UI に集中できるようになり、アドオンがエディタの一部であるかのように感じられます。

  • アドオンのあらゆる面で、ブランディング ガイドラインに従う必要があります。
  • 「Google」という単語を含めないでください。また、Google サービスのアイコンを使用しないでください。
  • テキストは数単語以内にします。アドオン CSS パッケージの gray クラスでスタイルを設定します。
  • グラフィックは白い背景にし、200 x 60 ピクセルを超えないようにしてください。
  • ダイアログの場合、ブランディングは右下隅に配置する必要があります。
  • サイドバーの場合、ブランディングは上部または下部に配置できます。

ストア内

エディタのアドオンを公開するには、多数の画像アセットが必要です。これらのアセットを使用して、アドオンのストア掲載情報を作成します。

ユーザー補助

色の見分け方やスクリーン リーダーの使用など、さまざまなニーズがあるユーザーがアドオンを楽しめるようにしてください。ユーザー補助は幅広いトピックであり、このスタイルガイドではすべてを網羅することはできません。Google ユーザー補助のサイトも参考になります。利用を開始するためのヒントをいくつかご紹介します。

  • キーボードですべての UI コントロールに移動できることを確認します。カスタム コントロール(<div> で作成したものなど)に tabindex=0 を追加して、ユーザーが Tab キーで操作できるようにします。リストの矢印など、他のキーもサポートする必要があるかどうかを検討してください。
  • 一部のユーザーは、アドオンでスクリーン リーダーを使用できます。したがって、イメージには alt 属性を、カスタム コントロールには使用方法を説明する ARIA 属性が必要です。
  • 状態を伝える際に色だけに頼らないでください。アイコンとテキストも使用します。

このガイドの前半で説明したような標準のウェブ コントロールを使用すると、アドオンへのアクセスが容易になります。