アドイン コマンド

アドイン コマンドは、Office UI を拡張し、アドインでアクションを開始する UI 要素です。 アドイン コマンドを使用すると、リボン上のボタンやアイテムをコンテキスト メニューに追加できます。 ユーザーがアドイン コマンドを選択すると、JavaScript コードの実行や、作業ウィンドウでのアドインのページの表示といったアクションを開始します。 アドイン コマンドは、ユーザーがアドインを検索して使用するのに役立ちます。これにより、アドインの導入と再利用を促進し、顧客維持率を向上させることができます。

アドイン コマンドの種類

コマンドがトリガーするアクションの種類に基づいて、2 種類のアドイン コマンドがあります。

• 作業ウィンドウ コマンド: ボタンまたはメニュー項目によってアドインの 作業ウィンドウが開きます。 この種のアドイン コマンドをマニフェスト内のマークアップと共に追加します。 コマンドの "分離コード" は Office に指定されます。

• 関数コマンド: ボタンまたはメニュー項目は任意の JavaScript を実行します。 ほとんどの場合、このコードは Office JavaScript ライブラリで API を呼び出しますが、そうする必要はありません。 この種類のアドインでは、通常、ボタンまたはメニュー項目自体以外の UI は表示されません。 関数コマンドについては、次の点に注意してください。

  • 関数コマンドを実行するランタイムは、 ブラウザー ベースの完全なランタイムです。 HTML をレンダリングし、インターネットに呼び出してデータを送信または取得できます。

  • ランタイムは、関数が完了するか、または 5 分が経過したときに閉じます。どちらか早い方です。

  • トリガーされる関数は 、displayDialogAsync メソッドを呼び出してダイアログを表示できます。 これは、エラーを表示したり、進行状況を表示したり、ユーザーに入力を求めたりするのに適した方法です。

    注:

    5 分間のタイムアウトのため、ユーザーが対話を完了し、5 分以内に閉じるようにダイアログを設計する必要があります。 アドインでは、長い対話のために作業ウィンドウを使用する必要があります。

  • アドインが共有ランタイムを使用するように構成されている場合、関数は showAsTaskpane メソッドを呼び出すこともできます。

  ヒント

  関数コマンドは、アドインで任意の JavaScript を実行する唯一の方法ではありません。 アドインには、次の機能も含めることができます。

  • Outlook で新しいメッセージ ウィンドウを開くユーザーなど、特定のイベントのカスタム ハンドラー。
  • アドインのユーザーからの自然言語要求に応答してアクションを実行するカスタム Copilot エージェント 。

アドイン コマンドの場所

ユーザーがアドインをインストールすると、アドインのコマンドがリボン、組み込みの Office タブ、またはマニフェストで指定されたカスタム タブに表示されます。 (アドイン コードが実行時に定義する カスタム コンテキスト タブ にアドイン コマンドを配置することもできます)。UI には、ボタンまたはドロップダウン メニューの項目として表示されます。

リボンまたはアクション バーが混雑すると、オーバーフロー メニューにアドイン コマンドが表示されます。 通常、同じアドインのコマンドはグループ化されます。

Office on the webで、1 行または簡略化されたリボン レイアウトを使用している場合、アドイン名はリボンに表示されません。 アドインのコマンド アイコンのみが表示されます。

Excel、PowerPoint、および Word

Excel リボンの [ データ ] タブのカスタム グループ内のアドイン コマンドの例を次に示します。

Outlook

Outlook の場合、独自のリボン タブを作成するのではなく、組み込みのリボン タブにアドイン コマンドを作成する場合、プラットフォームと現在の Outlook モードに基づいて既定のタブにコマンドが表示されます。 ガイダンスについては、「 Outlook でアドインを使用する」を参照してください。

ドロップダウン メニュー

ドロップダウン メニュー アドイン コマンドは、項目の静的リストを定義します。 メニューには、機能を実行する項目や作業ウィンドウを開く項目を自由に組み合わせて含めることができます。 サブメニューはサポートされていません。

リボンのグループ化されたアドイン コマンド

リボンでは、複数のアドイン コマンドをグループ化できます。 グループには、ボタンまたはドロップダウン メニューの形式で、少なくとも 1 つのアドイン コマンドが含まれている必要があります。 Office on Windows と Mac では、通常、グループ内のアドイン コマンドにボタンまたはドロップダウン メニューのラベルとアイコンが表示されます。 ただし、アイコンのサイズとラベルの表示は、スペースを制約する次の要因によって異なる場合があります。

• グループ内のアドイン コマンドの数。
• Office クライアント ウィンドウのサイズ。

クライアント ウィンドウが最大化され、1 つのグループに 3 つ以上のコントロールがある場合、各コントロールのラベルが表示されますが、そのアイコンのサイズは異なる場合があります (一部は 16 x 16 ピクセルとして表示され、他のコントロールは 32 x 32 ピクセルとして表示されます)。

グループに 2 つ以上のアドイン コマンドがあり、スペースが制限される場合は、アドイン コマンドの表示方法に対して次の調整が行われます。 これらの変更は、次のシーケンスでリボン全体で右から左にアドイン コマンドのグループに適用されます。

1. グループ内のアドイン コマンドごとに、小さなアイコン (16 x 16 ピクセル) とラベルが表示されます。
2. 小さいアイコンのみが表示されます。
3. グループは、リボンに個々のアドイン コマンドを表示するのではなく、ドロップダウン メニューとして表示されます。 リボンをスクロールできるように、スクロール スライダー アイコンもリボンに表示されます。

Office on the webでは、ブラウザー ウィンドウのサイズが変更されると、グループ内のコントロールのアイコン サイズとラベルの表示設定は変更されません。 スクロール スライダー アイコンがリボンに表示されます。

コマンドの機能

現在は、次のコマンド機能がサポートされています。

拡張点

• リボン タブ - 組み込みのタブを拡張するか、新しいカスタム コア タブを作成します。アドインには、1 つのカスタム コア タブのみを含めることができます(アドイン コマンドを カスタム コンテキスト タブに配置することもできます)。

  注:

  Outlook の場合、カスタム タブは従来の Outlook on Windows でのみサポートされます。 Outlook on the web、Mac、および新しい Outlook on Windows では、代わりに組み込みのリボン タブのいずれかにコントロールのカスタム グループを配置できます。

• コンテキスト メニュー: 選択されたコンテキスト メニューを拡張します。

コントロールの種類

• 単純なボタン: 特定のアクションをトリガーします。
• メニュー: アクションをトリガーするボタン付きの単純なメニューのドロップダウン。

既定の可用性状態

アドインの起動時にコマンドを使用できるかどうかを指定し、プログラムで設定を変更できます。

リボン上の位置

「ホームタブのすぐ右側」など、Office アプリケーションのリボンのどこにカスタム タブを表示するかを指定できます。

組み込みの Office ボタンの統合

組み込みの Office リボン ボタンはカスタム コマンド グループとカスタム リボン タブに挿入できます。

操作別タブ

カスタム コンテキスト タブを指定できます。つまり、Excel でグラフが選択されている場合など、特定のコンテキストでのみリボンに表示されるタブです。

サポートされるプラットフォーム

現在アドイン コマンドは、以前にコマンドの機能のサブ セクションで指定された制限を除いて、次のプラットフォームでサポートされています。

• Office on the web
• Microsoft 365 サブスクリプションに接続されている Windows 上の Office
• Microsoft 365 サブスクリプションに接続されている Office on Mac
• Windows または Mac の永続的なOffice 2021以降

デバッグ

アドイン コマンドをデバッグするには、Office on the webで実行する必要があります。 詳細については、「Office on the web でアドインをデバッグする」を参照してください。

ベスト プラクティス

アドイン コマンドを開発するときは、次のベスト プラクティスを適用します。

• ユーザーに対して、特定のアクションとともにアクションの結果を明確かつ具体的に表すコマンドを使用します。 1 つのボタンに複数のアクションを組み合わせないでください。
• アドイン内の一般的なタスクをより効率的に実行できるように、アクションは細分化して提供します。 1 つのアクションを完了するまでのステップ数は最小限に抑えます。
• すべてのアイコンについては、アイコン デザインのガイドラインに従ってください。
• コマンドをサポートしていない Office アプリケーションまたはプラットフォーム (iPad など) で動作するアドインのバージョンを指定します。 これらのバージョンでは、1 つのアドイン マニフェストを使用できます。

リボン上のアドイン コマンドのベスト プラクティス

次の表は、Office アプリ リボン上のオブジェクトに推奨される制限の概要を示しています。

推奨されるオブジェクトの制限に加えて、リボンでアドイン コマンドを構成する場合は、次の点に注意してください。

• 指定した機能がそこに収まる場合は、[挿入] タブや [レビュー] タブなどの既存のタブにコマンドを配置します。 たとえば、アドインでユーザーがメディアを挿入できる場合は、[挿入] タブにグループを追加します。すべての Office バージョンですべてのタブを使用できるわけではないことに注意してください。 詳細については、「 Office アドイン マニフェスト」を参照してください。
• 別のタブに機能が適応せず、トップ レベル コマンドが 6 個未満の場合は、[ホーム] タブにコマンドを配置します。 また、アドインが Office のバージョン (Office on the webやデスクトップなど) 全体で動作する必要があり、タブがすべてのバージョンで使用できない場合は、[ホーム] タブにコマンドを追加することもできます。
• 6 個以上のトップ レベル コマンドがある場合は、コマンドをカスタム タブに配置します。
• グループに、アドインの名前と一致する名前を指定します。 グループが複数ある場合は、そのグループのコマンドが提供する機能に基づいた名前を各グループに付けます。
• Office アプリ ウィンドウのサイズが変更されたときに、グループが正常に折りたたまれていることを確認します。 リボンには動的なサイズ変更が用意 されていますが (リボンのグループ化されたアドイン コマンドを参照)、アドインのグループの組み合わせを定義する必要もあります。
• 不要なボタンを追加してアドインの不動産を増やさないでください。
• ユーザーがドキュメントを操作する主な方法がアドインでない限り、カスタム タブを [ホーム] タブの左側に配置したり、ドキュメントが開いたときに既定でフォーカスを設定したりしないでください。 アドインの不便さを過度に目立たせ、ユーザーや管理者を悩ませます。
• アドインがユーザーがドキュメントを操作する主な方法であり、カスタム リボン タブがある場合は、ユーザーが頻繁に必要とする Office 機能のボタンをタブに統合することを検討してください。
• カスタム タブで提供される機能を特定のコンテキストでのみ使用できる場合は、 カスタム コンテキスト タブを使用します。 カスタム コンテキスト タブを使用する場合は、カスタム コンテキスト タブをサポートしていないプラットフォームでアドインを実行する場合のフォールバック エクスペリエンスを実装します。
• ダイアログを実装して、ユーザーに高度なオプションを提供します。 これにより、使用頻度の高いコマンドを使用して、アドインでリボンがオーバーロードされるのを防ぐことができます。 ダイアログを実装する方法については、「 Office アドインで Office ダイアログ API を使用する」を参照してください。

次の手順

アドイン コマンドの使用を開始するために最適な方法は、GitHub の「Office-Add-in-Commands-Samples」を参照することです。

アドインのみのマニフェストでアドイン コマンドを指定する方法の詳細については、「アドイン 専用マニフェストを使用してアドイン コマンドを作成 する」および 「VersionOverrides リファレンス コンテンツ」を参照してください。

Microsoft 365 の統合マニフェストでアドイン コマンドを指定する方法の詳細については、「Microsoft 365 の統合マニフェストを使用してアドイン コマンドを作成する」を参照してください。