Excel、PowerPoint、Word のアドイン コマンド
アドイン コマンドは、Office UI を拡張し、アドインでアクションを開始する UI 要素です。 アドイン コマンドを使用すると、リボン上のボタンやアイテムをコンテキスト メニューに追加できます。 ユーザーがアドイン コマンドを選択すると、JavaScript コードの実行や、作業ウィンドウでのアドインのページの表示といったアクションを開始します。 アドイン コマンドは、ユーザーがアドインを検索して使用するのに役立ちます。これにより、アドインの導入と再利用を促進し、顧客維持率を向上させることができます。
注:
重要
アドイン コマンドは、Outlook でもサポートされています。 詳細については、「Outlook のアドイン コマンド」を参照してください。
図 1. Excel デスクトップで実行するコマンドを含むアドイン
図 2. Excel on the webで実行されているコマンドを含むアドイン
アドイン コマンドの種類
コマンドがトリガーするアクションの種類に基づいて、2 種類のアドイン コマンドがあります。
作業ウィンドウ コマンド: ボタンまたはメニュー項目によって、アドインの作業ウィンドウが開きます。 この種のアドイン コマンドをマニフェスト内のマークアップと共に追加します。 コマンドの "分離コード" は Office に指定されます。
関数コマンド: ボタンまたはメニュー項目は任意の JavaScript を実行します。 ほとんどの場合、このコードは Office JavaScript ライブラリで API を呼び出しますが、そうする必要はありません。 この種類のアドインでは、通常、ボタンまたはメニュー項目自体以外の UI は表示されません。 関数コマンドについては、次の点に注意してください。
- トリガーされる関数は displayDialogAsync メソッドを呼び出してダイアログを表示できます。これは、エラーの表示、進行状況の表示、またはユーザーからの入力を求める適切な方法です。 アドインが共有ランタイムを使用するように構成されている場合、関数は showAsTaskpane メソッドを呼び出すこともできます。
- 関数コマンドを実行するランタイムは、 ブラウザー ベースの完全なランタイムです。 HTML をレンダリングし、インターネットに呼び出してデータを送信または取得できます。
コマンドの機能
現在は、次のコマンド機能がサポートされています。
拡張点
- リボン タブ - 組み込みタブを拡張するか、新しいカスタム タブを作成します。アドインには、カスタム タブを 1 つだけ含めることができます。
- コンテキスト メニュー: 選択されたコンテキスト メニューを拡張します。
コントロールの種類
- 単純なボタン: 特定のアクションをトリガーします。
- メニュー: アクションをトリガーするボタン付きの単純なメニューのドロップダウン。
既定で有効または無効になっている状態
アドイン起動時にコマンドを有効にするか無効にするかを指定したり、プログラムによって設定を変更したりできます。
注:
この機能はすべての Office アプリケーションまたはシナリオでサポートされてはいません。 詳細については、「アドイン コマンドを有効または無効にする」を参照してください。
リボンの位置 (プレビュー)
「ホームタブのすぐ右側」など、Office アプリケーションのリボンのどこにカスタム タブを表示するかを指定できます。
注:
この機能はすべての Office アプリケーションまたはシナリオでサポートされてはいません。 詳細については、「リボンにカスタムタブを配置する」を参照してください。
組み込みの Office ボタンの統合
組み込みの Office リボン ボタンはカスタム コマンド グループとカスタム リボン タブに挿入できます。
注:
この機能はすべての Office アプリケーションまたはシナリオでサポートされてはいません。 詳細については、「組み込みの Office ボタンをカスタム タブに統合する」を参照してください。
操作別タブ
Excel でグラフが選択されている場合など、特定のコンテキストでのみタブがリボンに表示されるように指定できます。
注:
この機能はすべての Office アプリケーションまたはシナリオでサポートされてはいません。 詳細については、「Office アドインでカスタム コンテキスト タブを作成する (プレビュー)」を参照してください。
サポートされるプラットフォーム
現在アドイン コマンドは、以前にコマンドの機能のサブ セクションで指定された制限を除いて、次のプラットフォームでサポートされています。
- Windows 上の Office (ビルド 16.0.6769 以降、Microsoft 365 サブスクリプションに接続済み)
- Windows での Office 2019 以降
- Mac 上の Office (ビルド 15.33 以降、Microsoft 365 サブスクリプションに接続済み)
- Mac での Office 2019 以降
- Office on the web
注:
Outlook でのサポートについては、「Outlook のアドイン コマンド」をご覧ください。
デバッグ
アドイン コマンドをデバッグするには、Office on the web で実行する必要があります。 詳細については、「Office on the web でアドインをデバッグする」を参照してください。
ベスト プラクティス
アドイン コマンドを開発するときは、次のベスト プラクティスを適用します。
ユーザーに対して、特定のアクションとともにアクションの結果を明確かつ具体的に表すコマンドを使用します。 複数のアクションを 1 つのボタンにまとめないでください。
アドイン内の一般的なタスクをより効率的に実行できるように、アクションは細分化して提供します。 1 つのアクションを完了するまでのステップ数は最小限に抑えます。
Office アプリ リボンにコマンドを配置するために。
- 指定した機能がそこに収まる場合は、既存のタブ (挿入、レビューなど) にコマンドを配置します。 たとえば、アドインでユーザーがメディアを挿入できる場合は、[挿入] タブにグループを追加します。すべての Office バージョンですべてのタブを使用できるわけではないことに注意してください。 詳細については、「Office アドインの XML マニフェスト」をご覧ください。
- 別のタブに機能が適応せず、トップ レベル コマンドが 6 個未満の場合は、[ホーム] タブにコマンドを配置します。 また、アドインが Office のバージョン (Office on the webやデスクトップなど) で動作する必要があり、タブがすべてのバージョンで使用できない場合 (たとえば、[デザイン] タブがOffice on the webに存在しない) 場合は、[ホーム] タブにコマンドを追加することもできます。
- 6 個以上のトップ レベル コマンドがある場合は、コマンドをカスタム タブに配置します。
- グループに、アドインの名前と一致する名前を指定します。 グループが複数ある場合は、そのグループのコマンドが提供する機能に基づいた名前を各グループに付けます。
- アドインの使用スペースを増やす余分なボタンを追加しないでください。
- ユーザーがドキュメントを操作する主な方法がアドインである場合を除き、カスタムタブを [ホーム] タブの左側に配置したり、ドキュメントを開いたときに既定でフォーカスを設定したりしないでください。 アドインの不便さを過度に目立たせ、ユーザーや管理者を悩ませます。
- アドインがユーザーがドキュメントを操作する主な方法であり、カスタム リボン タブがある場合は、ユーザーが頻繁に必要とする Office 機能のボタンをタブに統合することを検討してください。
- カスタム タブで提供される機能を特定のコンテキストでのみ使用できるようにする必要がある場合は、カスタム コンテキスト タブを使用します。 カスタム コンテキスト タブを使用する場合は、カスタム コンテキスト タブをサポートしていないプラットフォームでアドインを実行する場合のフォールバック エクスペリエンスを実装します。
注:
占有領域が大きすぎるアドインは AppSource 検証を通過しない場合があります。
すべてのアイコンについては、アイコン デザインのガイドラインに従ってください。
コマンドをサポートしていない Office アプリケーションでも動作するアドインのバージョンを提供します。 1 つのアドインのマニフェストは、コマンド対応 (コマンドを使用) アプリケーションとコマンド非対応 (作業ウィンドウとして) アプリケーションの両方で動作します。
図 3. Office 2013 の作業ウィンドウのアドインと、Office 2016 のアドイン コマンドを使用する同じアドイン
次の手順
アドイン コマンドの使用を開始するために最適な方法は、GitHub の「Office-Add-in-Commands-Samples」を参照することです。
マニフェストでのアドイン コマンドの指定の詳細については、「マニフェストでアドイン コマンドを作成する」と「VersionOverrides 要素」のリファレンス資料をご覧ください。