アドイン コマンド

  • [アーティクル]

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

注:

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

アドイン コマンドの種類

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

  • 作業ウィンドウ コマンド: ボタンまたはメニュー項目によってアドインの 作業ウィンドウが開きます。 この種のアドイン コマンドをマニフェスト内のマークアップと共に追加します。 コマンドの "分離コード" は Office に指定されます。
  • 関数コマンド: ボタンまたはメニュー項目は任意の JavaScript を実行します。 ほとんどの場合、このコードは Office JavaScript ライブラリで API を呼び出しますが、そうする必要はありません。 この種類のアドインでは、通常、ボタンまたはメニュー項目自体以外の UI は表示されません。 関数コマンドについては、次の点に注意してください。
    • トリガーされる関数は displayDialogAsync メソッドを呼び出してダイアログを表示できます。これは、エラーの表示、進行状況の表示、またはユーザーからの入力を求める適切な方法です。 アドインが共有ランタイムを使用するように構成されている場合、関数は showAsTaskpane メソッドを呼び出すこともできます。
    • 関数コマンドを実行するランタイムは、 ブラウザー ベースの完全なランタイムです。 HTML をレンダリングし、インターネットに呼び出してデータを送信または取得できます。

アドイン コマンドの表示方法

アドイン コマンドは、リボンにボタンまたはドロップダウン メニューの項目として表示されます。 ユーザーがアドインをインストールすると、そのコマンドはボタンのグループとして UI に表示されます。 これは、リボンの既定のタブまたはカスタム タブのいずれかです。簡略化されたリボン レイアウトを使用している場合、アドイン名はアプリ バーから削除されます。 リボンには、アドイン コマンド ボタンだけが表示されます。

リボンがいっぱいになると、アドイン コマンドがオーバーフロー メニューに表示されます。 通常、アドインのアドイン コマンドはグループ化されています。

リボンとオーバーフロー メニューのアドイン コマンド ボタン。

Excel、PowerPoint、および Word

既定のタブは、アプリケーションとコンテキストによって異なります。 Excel、PowerPoint、Wordの場合、既定のタブは [ホーム] です。

Excel リボンで強調表示されているサンプル アドイン コマンド。

Outlook

Outlook の場合、既定のアドイン コマンドの場所は現在の Outlook モードに基づいています。

シナリオ タブの場所
メッセージの閲覧 [ホーム ] タブ
メッセージの作成 [メッセージ ] タブ
開催者として予定または会議を作成または表示する [会議]、[ 会議の発生]、[ 会議のシリーズ]、または [ 予定 ] タブ。1
出席者として会議を表示する [会議]、[ 会議の発生]、または [ 会議シリーズ] タブ。1
モジュール拡張機能の使用 拡張機能のカスタム タブ。

1 ユーザーが予定表のアイテムを選択してもポップアウトを開かない場合、アドインのリボン グループはリボンに表示されません。

モダン Outlook on the web

Outlook on the web では、アドイン名はオーバーフロー メニューに表示されます。 アドインに複数のアドイン コマンドがある場合、アドイン メニューを展開して、アドイン名のラベルが付いたボタンのグループを表示できます。

アドイン コマンド ボタンが見つかるオーバーフロー メニュー。

アドイン コマンド ボタンを表示しているオーバーフロー メニュー。

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

Outlook リボンのドロップダウン メニューを表示するボタン。

コマンドの機能

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

拡張点

  • リボン タブ - 組み込みタブを拡張するか、新しいカスタム タブを作成します。アドインには、カスタム タブを 1 つだけ含めることができます。
  • コンテキスト メニュー: 選択されたコンテキスト メニューを拡張します。

コントロールの種類

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

既定で有効または無効になっている状態

アドイン起動時にコマンドを有効にするか無効にするかを指定したり、プログラムによって設定を変更したりできます。

注:

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

リボンの位置 (プレビュー)

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

注:

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

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

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

注:

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

操作別タブ

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

注:

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

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

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

  • Windows 上の Office (ビルド 16.0.6769 以降、Microsoft 365 サブスクリプションに接続済み)
  • Mac 上の Office (ビルド 15.33 以降、Microsoft 365 サブスクリプションに接続済み)
  • Office on the web
  • 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」を参照することです。

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

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