アドイン コマンド

  • [アーティクル]

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

注:

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

アドイン コマンドの種類

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

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

アドイン コマンドの場所

ユーザーがアドインをインストールする場合、そのコマンドの場所は、アプリケーション、プラットフォーム、コンテキストによって異なります。 アドイン コマンドは、リボン、既定またはカスタム タブ、またはアクション バーにあります (特定の Outlook プラットフォームにのみ適用されます)。 UI には、ボタンまたはドロップダウン メニューの項目として表示されます。

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

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

Excel、PowerPoint、および Word

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

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

Outlook

Outlook の場合、アドイン コマンドの既定の場所は、プラットフォームと現在の Outlook モードに基づいています。 ガイダンスについては、「 Outlook でアドインを使用する」を参照してください。

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

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

コマンドの機能

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

拡張点

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

コントロールの種類

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

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

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

注:

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

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

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

注:

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

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

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

注:

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

操作別タブ

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

注:

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

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

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

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

XML マニフェストでアドイン コマンドを指定する方法の詳細については、「xml マニフェストと VersionOverrides 参照コンテンツを使用したアドイン コマンドのCreate」を参照してください。

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