エディタ アドオンは、Apps Script の HTML Service を使用してユーザー インターフェース（メニュー、サイドバー、ダイアログ）を構築します。インターフェースは HTML と CSS で開発されているため、高度なカスタマイズが可能です。ただし、アドオン インターフェースを作成する場合は、優れたユーザー エクスペリエンスを提供するように設計する必要があります。
優れたアドオンは、使い慣れたコントロールと動作を使用して、各エディターを自然に拡張します。新しいアドオンをビルドする場合:
- HTML サービス ページで アドオンの CSS パッケージを使用します。
- デザインに迷う場合は、エディタで類似のダイアログまたはサイドバーを見つけて一致させるか、アドオンのクイックスタートを参照してください。
- シームレスなエクスペリエンスを実現するには、このスタイルガイドに沿って作成してください。
テキスト
アドオン名
アドオンの公開時に、アドオンの名前を設定する必要があります。この名前は、アドオン ストアやメニューなど、さまざまな場所に表示されます。
- 語頭を大文字にします（アルファベットの場合）。
- 句読点（特にかっこ）は、ブランドの一部でない限り使用しないでください。
- 30 文字以下にしてください。長い名前は自動的に切り捨てられる場合があります。
- アドオンが対象とする Google サービスの名前（または「Google」という単語）は含めないでください。
- バージョン情報は省略します。
- アドオンのパブリッシュ名がスクリプト プロジェクトのファイル名と同じであることを確認します。プロジェクト名が承認ダイアログに表示されます。
| 悪い例 | すべきこと |
|---|---|
 |
 |
文章のスタイル
書き込みはあまり必要ありません。ほとんどの操作は、アイコン、レイアウト、短いラベルで明確にする必要があります。アドオンの一部について、短いラベルでは説明が不十分な場合は、アドオンの説明を記載した別のウェブページを作成してリンクを設定することをおすすめします。
UI テキストを作成する際は、次の点に注意してください。
- 先頭を大文字にします（特にボタン、ラベル、メニュー項目の場合）。
- 専門用語や頭字語を使用せず、短くシンプルなテキストを作成します。
| 悪い例 | すべきこと |
|---|---|
|
|
|
インストール後のヒント
インストール後のヒントは、ユーザーがアドオンをインストールした直後にポップアップ表示され、ヘルプにも表示されます。ユーザーがすぐに使い始められるように、いくつかの文を用意します。
- 動詞で始める。
- アドオンの使用に関する最初の手順を説明します。
- サイドバーなどのメイン UI がある場合は、開く方法を説明します。
- アドオンを宣伝しないでください。アドオンはすでにインストールされています。
| 悪い例 | すべきこと |
|---|---|
 |
 |
メニュー項目
通常の Apps Script プロジェクトとは異なり、アドオンはスクリプト エディタやスクリプト マネージャーには表示されません。また、ユーザーはアドオン スクリプトを直接実行できません。代わりに、すべてのアドオンが [アドオン メニュー] に表示されます。メニュー（および必要に応じてダイアログまたはサイドバー）を使用すると、ユーザーはアドオンを操作できます。
- メニューはユーザーがアドオンを操作するうえで重要な部分であるため、その構造と文言を慎重に設計してください。
- アドオンの名前を繰り返すだけのメニュー項目は避けてください。代わりに、動詞から始めます。
- メインメニュー項目がワークフローを開始し、その動作を説明する動詞が 1 つもない場合は、「開始」という名前を付けます。このパターンは、ドキュメント アドオンのクイックスタートで使用されています。
- メニューに 6 つ以上の項目がある場合を除き、サブメニューを使用しないでください。選択が難しい場合がある。
- メニュー項目に表示される UI コンポーネントではなく、タスクを説明します。
| 悪い例 | すべきこと |
|---|---|
 |
 |
エラー メッセージ
問題が発生した場合は、わかりやすい言葉を使うことが重要です。お客様の立場から問題を説明し、解決方法を提案します。
- コードがスローした例外をユーザーに表示しないでください。代わりに、
try...catchステートメントを使用して例外をインターセプトし、アドオンの CSS パッケージのerrorクラスのスタイル設定されたインライン テキストを含むユーザー フレンドリーなエラー メッセージを表示するか、アラート ダイアログを表示します。 - 公開する前に、アドオンが JavaScript コンソールにデバッグ情報をログに記録していないことを確認します。代わりに Stackdriver Logging を使用してください。
| 悪い例 | すべきこと |
|---|---|
 |
 |
ヘルプ コンテンツ
すべてのアドオンのメニューには、自動ヘルプ ダイアログが含まれています。公開時にヘルプ URL を指定すると、[詳細] ボタンがそのページにリンクされます。アドオンが自明である場合を除き、使用方法を説明するページを用意してください。
- 可能であれば、手順を箇条書きまたは番号付きリストで表示します。名前付き UI 要素を明確に参照しながら、最終的な結果までユーザーを案内します。
- スプレッドシートを特定の方法で設定するなど、要件を明確に説明してください。
- メインのユーザー インターフェースからヘルプ コンテンツにリンクすることもできます。アドオンで新しいドキュメントを作成する場合は、ドキュメントの本文に手順を表示することもできます。
カスタム ユーザー インターフェース
シンプルなエディタ アドオンはメニューですべて制御できますが、ほとんどのアドオンはカスタム コンテンツを含むサイドバーまたはダイアログを表示します。
- サイドバーは、ユーザーがドキュメントやスプレッドシートのコンテンツを参照しながら繰り返し使用する可能性が高い永続的なツールに最適です。
- ダイアログは、1 回限りのツール、設定ページ、重要なメッセージに最適です。
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を追加します。リストの矢印など、他のキーもサポートする必要があるかどうかを検討します。 - ユーザーがアドオンでスクリーン リーダーを使用する場合があります。そのため、画像には
alt属性を、カスタム コントロールには使用方法を説明する ARIA 属性を指定する必要があります。 - 状態を伝えるうえで、色だけに頼らないでください。アイコンとテキストも使用します。
このガイドの前半で説明したような標準のウェブ コントロールを使用すると、アドオンをアクセス可能にするのが簡単になります。