エディタ アドオンは、Apps Script の HTML サービスを使用してユーザー インターフェース（メニュー、サイドバー、ダイアログ）を作成します。インターフェースは HTML と CSS で開発されているため、高度にカスタマイズできます。ただし、アドオン インターフェースを作成する際は、優れたユーザー エクスペリエンスを提供するように設計する必要があります。
最良のアドオンは、使い慣れたコントロールと動作を使用して、各エディタを自然に拡張します。新しいアドオンをビルドする際は、次の点にご注意ください。
- HTML サービスページで、アドオン CSS パッケージを使用します。
- デザインに疑問がある場合は、エディタで同様のダイアログやサイドバーを見つけてマッチングするか、アドオン クイックスタートをご覧ください。
- シームレスなスタイルを実現するには、このスタイルガイドを参考にしてください。
Text
アドオン名
アドオンの名前は、公開するときに設定する必要があります。名前は、アドオン ストアやメニューなど、さまざまな場所に表示されます。
- 語頭を大文字にします（アルファベットの場合）。
- 句読点の一部（かっこを除く）は使用しません。
- 半角 30 文字（全角 15 文字）以内で短くしてください。長い名前は自動的に切り詰められる場合があります。
- アドオンの対象となる Google プロダクトの名前を含めないでください（または Google という単語を使用します）。
- バージョン情報を省略します。
- アドオンの公開名はスクリプト プロジェクトのファイル名と同じにしてください。プロジェクト名が承認ダイアログに表示されます。
| してはいけないこと | 推奨事項 |
|---|---|
 |
 |
文章のスタイル
それほど多くのドキュメントを書く必要はありません。ほとんどのアクションは、アイコン、レイアウト、短いラベルで明確にする必要があります。アドオンの一部で、短いラベルよりも広範な説明が必要な場合は、アドオンを説明するウェブページを別途作成し、リンクすることをおすすめします。
UI テキストを記述する場合:
- 文頭を大文字にします（特に、ボタン、ラベル、メニュー項目の場合）。
- 専門用語や頭字語を使わない、シンプルで簡潔なテキストを優先します。
| してはいけないこと | 推奨事項 |
|---|---|
|
|
|
インストール後のヒント
ユーザーがインストールした後のヒントは、ユーザーがアドオンをインストールするとすぐにポップアップで表示されます。また、ヘルプにも表示されます。ユーザーがすぐに使い始めることができるように、簡潔に説明します。
- アクション ワードから始めます。
- アドオンを使用する最初のステップについて説明します。
- サイドバーなどのメインの UI がある場合は、それを開く方法を説明します。
- ここでインストール済みのアドオンは宣伝しないでください。すでにインストールされています。
| してはいけないこと | 推奨事項 |
|---|---|
 |
 |
メニュー アイテム
通常の Apps Script プロジェクトとは異なり、アドオンはスクリプト エディタやスクリプト マネージャーには表示されません。ユーザーはアドオン スクリプトを直接実行することはできません。すべてのアドオンが [アドオン] メニューに表示されます。メニュー（場合によってはダイアログまたはサイドバー）を使用すると、ユーザーはアドオンを操作できます。
- メニューは、ユーザーがアドオンを制御する方法の重要な部分であるため、その構造と表現を慎重に設計する必要があります。
- アドオンの名前を繰り返すだけのメニュー項目は避ける。代わりに、アクション ワードで始めます。
- メインメニュー アイテムでワークフローが開始され、その処理を説明する動詞が 1 つもない場合は、「開始」と言います。このパターンは、ドキュメント アドオンのクイックスタートで使用されます。
- メニューに 6 個を超える項目がある場合を除き、サブメニューは使用しないでください。これらは、細くて選択しにくい場合があります。
- メニュー項目に表示される UI コンポーネントではなく、タスクを記述します。
| してはいけないこと | 推奨事項 |
|---|---|
 |
 |
エラー メッセージ
問題が発生した場合は、簡単な言葉を使うことが重要です。お客様の視点から問題を説明し、修正方法を提案する。
- コードがスローした例外をユーザーが確認できないようにします。代わりに、
try...catchステートメントを使用して例外をインターセプトし、アドオン CSS パッケージまたはアラート ダイアログから、errorクラスでスタイル設定されたインライン テキストを使用してユーザー指定のエラー メッセージを表示します。 - 公開する前に、アドオンが JavaScript コンソールにデバッグ情報をロギングしていないことを確認します。代わりに Stackdriver Logging を使用してください。
| してはいけないこと | 推奨事項 |
|---|---|
 |
 |
ヘルプ コンテンツ
すべてのアドオン メニューには自動ヘルプ ダイアログが含まれています。公開時にヘルプ URL を指定すると、[詳細] ボタンがそのページにリンクされます。アドオンが自明でない限り、その使用方法を説明するページを提供してください。
- 可能な限り、箇条書きや番号付きリストに手順を示します。名前付き UI 要素を明確に参照して、ユーザーを最終結果まで導きます。
- 指示に、要件（スプレッドシートの設定など）が明確に示されていることを確認してください。
- メインのユーザー インターフェースからヘルプ コンテンツにアクセスすることもできます。アドオンで新しいドキュメントが作成された場合は、ドキュメントの本文に手順を表示することもできます。
カスタム ユーザー インターフェース
シンプルなエディタのアドオンのすべてはメニューで完全に制御できますが、ほとんどの場合、カスタム コンテンツ付きのサイドバーまたはダイアログが表示されます。
- サイドバーは、ドキュメントやスプレッドシートのコンテンツを参照しながら、ユーザーが繰り返し使用することがある永続ツールに最適です。
- ダイアログは、使い捨てのツール、設定ページ、重要なメッセージに最適です。
UI テキスト
どのようなダイアログやサイドバーでも、タイトルやボタンのラベルのみが読み上げられることを想定してください。それでも、インターフェースの役割を理解して、適切な選択をしてもらうことはできますか？
- タイトルとボタンのラベルは単体で使用しましょう。
- 長い説明文は使わないようにします。
ダイアログ
ダイアログは、1 回使用し、先に進む場合に適しています。たとえば、アドオンでグラフィックの挿入が許可されている場合、挿入する項目を選択できるダイアログを表示し、グラフィックの挿入時にダイアログを閉じることができます。ダイアログは、アドオンの設定を表示する場合や、重要なメッセージを伝達する場合にも役立ちます。
- 別のダイアログからのダイアログ（アラートやプロンプトを含む）は開かないでください。ダイアログは一度に 1 つだけ表示します。
- ダイアログのタイトルには、最も重要な単語で始まる単語または短いフレーズを使用します。
- ボタンのラベルはダイアログのタイトルに関連付ける必要があります。
- 通常はメイン アクションと [キャンセル] の 2 つのボタンを選択します。3 つ目のボタンが必要な特殊なケースでは、右下隅を検討してください。
- ダイアログの左下にボタンを配置します。左側のメインのプライマリ ボタンを、右側に灰色のセカンダリ ボタンを配置します。
| してはいけないこと | 推奨事項 |
|---|---|
 |
 |
サイドバー
サイドバーを使用すると、ドキュメント、スプレッドシート、プレゼンテーション、フォームを後で参照しながら選択できます。また、ユーザーはアドオンを繰り返し使用できます。新しいサイドバーを開くたびに、以前のサイドバーは自動的に閉じます。 これは、ユーザーが操作を完了したときに終了する一時モードに最適です。
- ユーザー自身のサイドバーで他のアドオンを使用することもあります。2 つのアドオンが同時にサイドバーを開こうとすると、1 つのアドオンのみが表示されます。
- ドキュメントを初めて開いたときに、サイドバーやダイアログを表示しない。
- サイドバーまたはダイアログを開けるのは、
AuthMode.FULLで動作するアドオンのみです。メニュー項目を使用してサイドバーを開くことができます。これにより、ユーザーに完全な承認を求めるプロンプトが表示されます。
制御
優れたアドオン UI は、いくらかコントロールをコントロールします。適切なマージンとパディングは大きな役割を果たしますが、高密度コントロールは煩雑な印象を与える可能性があります。判断に迷う場合は、エディタ自体からレイアウトを借ります。たとえば、[ファイル] > [ページの設定] など、Google ドキュメントの既存のダイアログを独自に作成するときに確認します。
アドオン CSS パッケージのドキュメントに、以下の各コントロール タイプのサンプル マークアップが記載されています。
ボタン
プレーン リンクやその他の要素ではなく、ボタンを使用してユーザー インターフェースの主なアクションを制御します。
- 同時に複数の青、赤、または緑のボタンを表示することは避けてください。灰色のボタンが繰り返し表示されることもある。
- ほとんどのボタンラベルは文頭で、動詞で始める必要があります。赤いボタン（通常は作成アクション用）にはすべて大文字を使用する必要があります。
| してはいけないこと | 推奨事項 |
|---|---|
|
|
|
チェックボックスとラジオボタン
複数のオプションを選択できる場合、またはオプションがまったくない場合は、チェックボックスを使用します。オプションを 1 つだけ選択する必要がある場合は、ラジオボタン（または選択メニュー）を使用します。
- チェックボックスの動作を、ラジオボタンを模倣しないでください。
- 確認しても何もしません。人は間違いを犯します。ユーザーがボタンをクリックして選択を確定するまで待ちます。
メニューを選択
選択は、代替候補の短いリストを提供するのに優れた方法です。
- オプションをアルファベット順か、すべてのユーザーが理解できる論理的スキーム（日曜日から始まる曜日など）で並べ替えます。
- リストが長すぎる場合は、別のコントロールを使用することを検討してください。たとえば、メニューにスペースを持たせ、操作を容易にするために、スクロール可能なリストを表示できます。
テキスト エリア
数語以上入力する必要がある場合は、テキスト領域を使用します。
- テキスト エリアは、テキスト フィールドよりも読みやすく、読みやすくするために 2 行以上にします。
- ラベルを上部に配置します。
テキスト フィールド
ユーザーが 1 ～ 2 語入力するだけの場合は、テキスト フィールドを使用します。
- テキスト フィールドの幅は、予想される入力内容を示しなければなりません。
- プレースホルダ テキストはフォーカスされた状態で表示されないため、ラベルとして使用しないでください。 プレースホルダ テキストは、例や詳細情報を提供します。
- ラベルは上部に配置し、テキスト フィールドは並べて配置してかまいません。
ブランディング
アドオンの場合
ブランディングも入れたい場合は、簡潔で簡潔にします。これにより、ユーザーは UI に集中でき、アドオンがエディタの一部であるかのように感じられます。
- アドオンの要素は、ブランディング ガイドラインを遵守している必要があります。
- 「Google」という言葉や Google サービスのアイコンを使用しないでください。
- テキストは数語以内で、アドオン CSS パッケージの
grayクラスでスタイルを設定する必要があります。 - グラフィックは白色で、200 × 60 ピクセル以下にする必要があります。
- ダイアログの場合、ブランディングは右下に配置する必要があります。
- サイドバーの場合、ブランディングは上部または下部に配置できます。
店舗
エディタのアドオンを公開するには、多数の画像アセットが必要です。これらのアセットは、アドオンのストア掲載情報の作成に使用されます。
- ストアの掲載情報は、ブランディング ガイドラインをすべて遵守する必要があります。
- 提供する必要がある画像の詳細については、画像のガイドラインをご覧ください。
ユーザー補助
色の違いやスクリーン リーダーの使用など、あらゆる場面でアドオンを体験できます。ユーザー補助については、このスタイルガイドでは十分に説明できない広範なトピックがあります。Google ユーザー補助機能サイトをご覧ください。ただし、最初にお試しいただけるヒントをいくつかご紹介します。
- キーボードを使ってすべての UI コントロールに移動できることを確認します。ユーザーが操作できるように、カスタム コントロール（
<div>で作成したものなど）にtabindex=0を追加します。リストの矢印など、他のキーもサポートする必要があるかどうかを検討します。 - アドオンを使用してスクリーン リーダーを使用するユーザーがいる可能性があります。そのため、画像には
alt属性を、カスタム コントロールには用途を表す ARIA 属性を含める必要があります。 - 状態だけを色で表現しないでください。アイコンやテキストも使用する。
このガイドの前半で説明したように、標準のウェブ コントロールを使用すると、アドオンに簡単にアクセスできます。