アドイン コマンド

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

注:

• SharePoint カタログでは、アドイン コマンドはサポートされていません。 統合アプリまたは AppSource でアドイン コマンドを展開するか、サイドロードを使用してテスト用のアドイン コマンドを展開できます。
• 現在、コンテンツ アドインは、アドイン コマンドをサポートしていません。

アドイン コマンドの種類

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

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

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

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

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

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

    注:

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

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

  ヒント

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

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

アドイン コマンドの場所

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

注:

特定の Outlook プラットフォームでは、コマンドはリボンではなくアクション バーにあります。

リボンに表示されるアドイン コマンドの場合、簡略化されたリボン レイアウトを使用している場合、アドイン名はアプリ バーから削除されます。 リボンには、アドイン コマンド ボタンだけが表示されます。

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

Excel、PowerPoint、および Word

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

Outlook

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

ドロップダウン メニュー

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

コマンドの機能

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

拡張点

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

  注:

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

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

コントロールの種類

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

既定の可用性状態

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

注:

この機能は、すべての Office アプリケーションまたはシナリオでサポートされているわけではありません。 詳細については、「 アドイン コマンドの可用性を変更する」を参照してください。

リボン上の位置

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

注:

この機能は、すべての Office アプリケーションまたはシナリオでサポートされているわけではありません。 詳細については、「リボンにカスタムタブを配置する」を参照してください。

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

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

注:

この機能は、すべての Office アプリケーションまたはシナリオでサポートされているわけではありません。 詳細については、「組み込みの Office ボタンをカスタム タブに統合する」を参照してください。

操作別タブ

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

注:

この機能は、すべての Office アプリケーションまたはシナリオでサポートされているわけではありません。 詳細については、「Office アドインでカスタム コンテキスト タブを作成する (プレビュー)」を参照してください。

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

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

• Office on the web
• Office on Windows (バージョン 1604 (ビルド 6769.2000) 以降(Microsoft 365 サブスクリプションに接続)
• Office on Mac (バージョン 15.33 (17040900) 以降、Microsoft 365 サブスクリプションに接続)
• Windows または Mac の永続的な Office 2019 以降

注:

Outlook でのサポートの詳細については、「 Outlook サポート ノート」を参照してください。

デバッグ

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

ベスト プラクティス

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

• ユーザーに対して、特定のアクションとともにアクションの結果を明確かつ具体的に表すコマンドを使用します。 1 つのボタンに複数のアクションを組み合わせないでください。

• アドイン内の一般的なタスクをより効率的に実行できるように、アクションは細分化して提供します。 1 つのアクションを完了するまでのステップ数は最小限に抑えます。

• Office アプリ リボンにコマンドを配置するために。

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

  注:

  占有領域が大きすぎるアドインは AppSource 検証を通過しない場合があります。

• すべてのアイコンについては、アイコン デザインのガイドラインに従ってください。

• コマンドをサポートしていない Office アプリケーションまたはプラットフォーム (iPad など) で動作するアドインのバージョンを指定します。 これらのバージョンでは、1 つのアドイン マニフェストを使用できます。

次の手順

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

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

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