アドイン コマンドは、アクションを実行する指定された UI 要素を使用して、既定の Office ユーザー インターフェイス (UI) をカスタマイズする簡単な方法を提供します。 アドイン コマンドの概要については、「アドイン コマンド」を参照してください。
この記事では、アドイン コマンドを定義するように Microsoft 365 の統合マニフェスト を構成する方法と 、関数コマンドのコードを作成する方法について説明します。
注:
Microsoft 365 の統合マニフェストは、運用環境の Outlook アドインで使用できます。Excel、PowerPoint、Word アドインのプレビューとしてのみ使用できます。
ヒント
アドインのみのマニフェストを使用してアドイン コマンドを作成する手順については、「アドインのみのマニフェストを 使用してアドイン コマンドを作成する」を参照してください。
注:
Microsoft 365 の統合マニフェストを使用する Office アドインを 直接 サポートするクライアントとプラットフォームについては、「Office アドイン と Microsoft 365 用統合アプリ マニフェスト」を参照してください。
開始点と主要な手順
Office Yeoman ジェネレーター と Microsoft 365 Agents Toolkit という統合マニフェストを使用してアドイン プロジェクトを作成するツールはどちらも、1 つ以上のアドイン コマンドを使用してプロジェクトを作成します。 アドイン コマンドがまだない唯一の時間は、以前にアドインが存在しなかったアドインを更新している場合だけです。
2 つの決定
- 必要な 2 種類のアドイン コマンドを決定する: 作業ウィンドウまたは関数
- 必要な UI 要素の種類 (ボタンまたはメニュー項目) を決定します。 次に、決定に対応する以下のセクションとサブセクションの手順を実行します。
作業ウィンドウ コマンドを追加する
次のサブセクションでは、 アドインに作業ウィンドウ コマンド を含める方法について説明します。
作業ウィンドウ コマンドのランタイムを構成する
統合マニフェストを開き、
"extensions.runtimes"配列を見つけます。値が
"openPage"の"actions.type"プロパティを持つランタイム オブジェクトがあることを確認します。 この種類のランタイムによって作業ウィンドウが開きます。"requirements.capabilities"配列に、アドイン コマンドをサポートする要件セットを指定する オブジェクトが含まれていることを確認します。 Outlook の場合、アドイン コマンドの最小要件セットは Mailbox 1.3 です。 他の Office ホスト アプリケーションの場合、アドイン コマンドの最小要件セットは AddinCommands 1.1 です。ランタイム オブジェクトの
"id"に、"TaskPaneRuntime"などのわかりやすい名前があることを確認します。ランタイム オブジェクトの
"code.page"プロパティが、作業ウィンドウで開くページの URL ("https://localhost:3000/taskpane.html"など) に設定されていることを確認します。ランタイム オブジェクトの
"actions.view"に、前の手順で設定したページの内容を説明する名前 ("homepage"や"dashboard"など) があることを確認します。ランタイム オブジェクトの
"actions.id"に、ユーザーがアドイン コマンド ボタンまたはメニュー項目を選択したときに何が起こるかを示す"ShowTaskPane"などのわかりやすい名前があることを確認します。ランタイム オブジェクトの次の完成した例に示すように、ランタイム オブジェクトの他のプロパティとサブプロパティを設定します。
"type"プロパティと"lifetime"プロパティは、Outlook アドインで必要です。この例では、常に値が表示されます。"runtimes": [ { "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.3" } ] }, "id": "TaskPaneRuntime", "type": "general", "code": { "page": "https://localhost:3000/taskpane.html" }, "lifetime": "short", "actions": [ { "id": "ShowTaskPane", "type": "openPage", "view": "homepage" } ] } ]
作業ウィンドウ コマンドの UI を構成する
ランタイムを構成した拡張オブジェクトに、
"runtimes"配列のピアとして"ribbons"配列プロパティがあることを確認します。 通常、"extensions"配列には拡張オブジェクトが 1 つだけ存在します。次の例に示すように、配列に
"contexts"および"tabs"という名前の配列プロパティを持つオブジェクトがあることを確認します。"ribbons": [ { "contexts": [ // child objects omitted ], "tabs": [ // child objects omitted ] } ]"contexts"配列に、作業ウィンドウ コマンドの UI を表示するウィンドウまたはペインを指定する文字列があることを確認します。 たとえば、"mailRead"は、電子メール メッセージが開いているときに閲覧ウィンドウまたはメッセージ ウィンドウに表示されることを意味しますが、"mailCompose"は、新しいメッセージまたは返信が構成されているときに表示されることを意味します。 許容される値を次に示します。"mailRead""mailCompose""meetingDetailsOrganizer""meetingDetailsAttendee"
次に例を示します。
"contexts": [ "mailRead" ],"tabs"配列に、作業ウィンドウ コマンドを表示するリボン タブの ID に設定されている"builtInTabId"文字列プロパティを持つオブジェクトがあることを確認します。 また、少なくとも 1 つのオブジェクトを含む"groups"配列があることを確認します。 次に例を示します。"tabs": [ { "builtInTabID": "TabDefault", "groups": [ { // properties omitted } ] } ]注:
"builtInTabID"プロパティの使用可能な値の一覧については、「組み込みの Office リボン タブの ID を検索する」を参照してください。"groups"配列に、アドイン コマンド UI コントロールを保持するカスタム コントロール グループを定義するオブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。-
"id"は、マニフェスト内のすべてのリボン オブジェクト内のすべてのグループで一意である必要があります。 最大文字数は 64 文字です。 - リボンのグループに
"label"が表示されます。 最大長は 64 文字ですが、コントロール グループがリボンに正しく収まるようにするには、"label"を 16 文字に制限することをお勧めします。 - グループに表示される
"icons"の 1 つは、Office アプリケーション ウィンドウとリボンのサイズがユーザーによって小さすぎてグループ内のコントロールが表示されない場合のみです。 Office では、これらのアイコンのいずれかを使用するタイミングと、ウィンドウのサイズとデバイスの解像度に基づいて使用するアイコンを決定します。 これを制御することはできません。 16、32、80 ピクセルのイメージ ファイルを指定する必要があります。他の 5 つのサイズもサポートされています (20、24、40、48、64 ピクセル)。 すべての URL に Secure Sockets Layer (SSL) を使用する必要があります。
"groups": [ { "id": "msgReadGroup", "label": "Contoso Add-in", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "controls": [ { // properties omitted } ] } ]-
目的のボタンまたはカスタム メニューごとに、
"controls"配列にコントロール オブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。-
"id"、"label"、および"icons"プロパティは、グループ オブジェクトの対応するプロパティと同じ目的と同じ制限を持ちますが、グループ内の特定のボタンまたはメニューに適用される点が異なります。 -
"type"プロパティは"button"に設定されます。これは、コントロールがリボン ボタンであることを意味します。 メニュー項目から実行する作業ウィンドウ コマンドを構成することもできます。 メニュー項目とメニュー項目を参照してください。 -
"supertip.title"(最大長: 64 文字) と"supertip.description"(最大長: 128 文字) は、カーソルがボタンまたはメニューにカーソルを合わせたときに表示されます。 -
"actionId"は、「作業ウィンドウのランタイムを構成する」コマンドで設定した"runtimes.actions.id"と完全に一致している必要があります。
{ "id": "msgReadOpenPaneButton", "type": "button", "label": "Show Task Pane", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "supertip": { "title": "Show Contoso Task Pane", "description": "Opens the Contoso task pane." }, "actionId": "ShowTaskPane" }-
これで、アドインへの作業ウィンドウ コマンドの追加が完了しました。 サイドロードしてテストします。
関数コマンドを追加する
次のサブセクションでは、アドインに 関数コマンド を含める方法について説明します。
関数コマンドのコードを作成する
ソース コードに、関数コマンドで実行する関数を含む JavaScript または Typescript ファイルが含まれていることを確認します。 次に例を示します。 この記事ではアドイン コマンドの作成に関する記事であり、Office JavaScript ライブラリの指導に関するものではなく、最小限のコメントで提供しますが、次の点に注意してください。
- この記事では、ファイルの名前は commands.jsです。
- 関数を使用すると、開いている電子メール メッセージに小さな通知が表示され、"アクションが実行されました" というテキストが表示されます。
- Office JavaScript ライブラリの API を呼び出すすべてのコードと同様に、 ライブラリを初期化することから始める必要があります。 これは、
Office.onReadyを呼び出すことによって行います。 - コードが最後に呼び出すのは Office.actions.associate で、関数コマンドの UI が呼び出されたときにファイル内のどの関数を実行するかを Office に伝えます。 関数は、後の手順でマニフェストで構成したアクション ID に関数名をマップします。 同じファイル内に複数の関数コマンドを定義する場合、コードはそれぞれの
associateを呼び出す必要があります。 - 関数は、 Office.AddinCommands.Event 型のパラメーターを受け取る必要があります。 関数の最後の行で event.completed を呼び出す必要があります。
Office.onReady(function() { // Add any initialization code here. }); function setNotification(event) { const message = { type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage, message: "Performed action.", icon: "Icon.80x80", persistent: true, }; // Show a notification message. Office.context.mailbox.item.notificationMessages.replaceAsync("ActionPerformanceNotification", message); // Be sure to indicate when the add-in command function is complete. event.completed(); } // Map the function to the action ID in the manifest. Office.actions.associate("SetNotification", setNotification);ソース コードに、作成した関数ファイルを読み込むよう構成された HTML ファイルが含まれていることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。
この記事では、ファイルの名前は commands.htmlです。
ファイルに UI がないため、
<body>要素は空です。 その唯一の目的は、JavaScript ファイルを読み込むためです。前の手順で作成した Office JavaScript ライブラリと commands.js ファイルが明示的に読み込まれます。
注:
Office アドイン開発では、 webpack やそのプラグインなどのツールを使用して、ビルド時にタグ
<script>自動的に HTML ファイルに挿入するのが一般的です。 このようなツールを使用する場合は、ツールによって挿入される<script>タグをソース ファイルに含めてはいけません。
<!DOCTYPE html> <html> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <!-- Office JavaScript Library --> <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script> <!-- Function command file --> <script src="commands.js" type="text/javascript"></script> </head> <body> </body> </html>
関数コマンドのランタイムを構成する
統合マニフェストを開き、
"extensions.runtimes"配列を見つけます。値が
"executeFunction"の"actions.type"プロパティを持つランタイム オブジェクトがあることを確認します。"requirements.capabilities"配列に、API アドイン コマンドをサポートするために必要な要件セットを指定するオブジェクトが含まれていることを確認します。 Outlook の場合、アドイン コマンドの最小要件セットは Mailbox 1.3 です。 ただし、関数コマンドで、メールボックス 1.5 などの後のメールボックス要件セットの一部である API を呼び出す場合は、新しいバージョン ("1.5" など) を"minVersion"値として指定する必要があります。 他の Office ホスト アプリケーションの場合、アドイン コマンドの最小要件セットは AddinCommands 1.1 です。ランタイム オブジェクトの
"id"に、"CommandsRuntime" などのわかりやすい名前があることを確認します。ランタイム オブジェクトの
"code.page"プロパティが、"https://localhost:3000/commands.html"などの関数ファイルを読み込む UI レス HTML ページの URL に設定されていることを確認します。ランタイム オブジェクトの
"actions.id"に、ユーザーがアドイン コマンド ボタンまたはメニュー項目を選択したときに何が起こるかを示す "SetNotification" などのわかりやすい名前があることを確認します。重要
"actions.id"の値は、関数ファイル内のOffice.actions.associateへの呼び出しの最初のパラメーターと完全に一致している必要があります。ランタイム オブジェクトの次の完成した例に示すように、ランタイム オブジェクトの他のプロパティとサブプロパティを設定します。
"runtimes": [ { "id": "CommandsRuntime", "type": "general", "code": { "page": "https://localhost:3000/commands.html" }, "lifetime": "short", "actions": [ { "id": "SetNotification", "type": "executeFunction", } ] } ]
関数コマンドの UI を構成する
ランタイムを構成した拡張オブジェクトに、
"runtimes"配列のピアとして"ribbons"配列プロパティがあることを確認します。 通常、"extensions"配列には拡張オブジェクトが 1 つだけ存在します。次の例に示すように、配列に
"contexts"および"tabs"という名前の配列プロパティを持つオブジェクトがあることを確認します。"ribbons": [ { "contexts": [ // child objects omitted ], "tabs": [ // child objects omitted ] } ]"contexts"配列に、関数コマンドの UI を表示するウィンドウまたはウィンドウを指定する文字列があることを確認します。 たとえば、"mailRead"は、電子メール メッセージが開いているときに閲覧ウィンドウまたはメッセージ ウィンドウに表示されることを意味しますが、"mailCompose"は、新しいメッセージまたは返信が構成されているときに表示されることを意味します。 許容される値を次に示します。"mailRead""mailCompose""meetingDetailsOrganizer""meetingDetailsAttendee"
次に例を示します。
"contexts": [ "mailRead" ],"tabs"配列に、関数コマンドを表示するリボン タブの ID に設定された"builtInTabId"文字列プロパティを持つオブジェクトと、少なくとも 1 つのオブジェクトを含む"groups"配列があることを確認します。 次に例を示します。"tabs": [ { "builtInTabID": "TabDefault", "groups": [ { // properties omitted } ] } ]注:
"builtInTabID"プロパティの使用可能な値の一覧については、「組み込みの Office リボン タブの ID を検索する」を参照してください。"groups"配列に、アドイン コマンド UI コントロールを保持するカスタム コントロール グループを定義するオブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。-
"id"は、マニフェスト内のすべてのリボン オブジェクト内のすべてのグループで一意である必要があります。 最大文字数は 64 文字です。 - リボンのグループに
"label"が表示されます。 最大長は 64 文字ですが、コントロール グループがリボンに正しく収まるようにするには、"label"を 16 文字に制限することをお勧めします。 - グループに表示される
"icons"の 1 つは、Office アプリケーション ウィンドウとリボンのサイズがユーザーによって小さすぎてグループ内のコントロールが表示されない場合のみです。 Office では、これらのアイコンのいずれかを使用するタイミングと、ウィンドウのサイズとデバイスの解像度に基づいて使用するアイコンを決定します。 これを制御することはできません。 16、32、80 ピクセルのイメージ ファイルを指定する必要があります。他の 5 つのサイズもサポートされています (20、24、40、48、64 ピクセル)。 すべての URL に Secure Sockets Layer (SSL) を使用する必要があります。
"groups": [ { "id": "msgReadGroup", "label": "Contoso Add-in", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "controls": [ { // properties omitted } ] } ]-
目的のボタンまたはカスタム メニューごとに、
"controls"配列にコントロール オブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。-
"id"、"label"、および"icons"プロパティは、グループ オブジェクトの対応するプロパティと同じ目的と同じ制限を持ちますが、グループ内の特定のボタンまたはメニューに適用される点が異なります。 -
"type"プロパティは"button"に設定されます。これは、コントロールがリボン ボタンであることを意味します。 メニュー項目から実行する関数コマンドを構成することもできます。 メニュー項目とメニュー項目を参照してください。 -
"supertip.title"(最大長: 64 文字) と"supertip.description"(最大長: 128 文字) は、カーソルがボタンまたはメニューにカーソルを合わせたときに表示されます。 -
"actionId"は、「関数コマンドのランタイムを構成する」で設定した"runtime.actions.id"と完全に一致している必要があります。
{ "id": "msgReadSetNotificationButton", "type": "button", "label": "Set Notification", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "supertip": { "title": "Set Notification", "description": "Displays a notification message on the current message." }, "actionId": "SetNotification" }-
これで、アドインへの関数コマンドの追加が完了しました。 サイドロードしてテストします。
メニュー項目とメニュー項目
カスタム ボタンに加えて、カスタム ドロップダウン メニューを Office リボンに追加することもできます。 このセクションでは、2 つのメニュー項目で例を使用する方法について説明します。 作業ウィンドウ コマンドを呼び出します。 もう 1 つでは、関数コマンドが呼び出されます。
ランタイムとコードを構成する
次のセクションの手順を実行します。
メニューの UI を構成する
ランタイムを構成した拡張オブジェクトに、
"runtimes"配列のピアとして"ribbons"配列プロパティがあることを確認します。 通常、"extensions"配列には拡張オブジェクトが 1 つだけ存在します。次の例に示すように、配列に
"contexts"および"tabs"という名前の配列プロパティを持つオブジェクトがあることを確認します。"ribbons": [ { "contexts": [ // child objects omitted ], "tabs": [ // child objects omitted ] } ]"contexts"配列に、リボンにメニューを表示するウィンドウまたはウィンドウを指定する文字列があることを確認します。 たとえば、"mailRead"は、電子メール メッセージが開いているときに閲覧ウィンドウまたはメッセージ ウィンドウに表示されることを意味しますが、"mailCompose"は、新しいメッセージまたは返信が構成されているときに表示されることを意味します。 許容される値を次に示します。"mailRead""mailCompose""meetingDetailsOrganizer""meetingDetailsAttendee"
次に例を示します。
"contexts": [ "mailRead" ],"tabs"配列に、作業ウィンドウ コマンドを表示するリボン タブの ID に設定された"builtInTabId"文字列プロパティを持つオブジェクトと、少なくとも 1 つのオブジェクトを含む"groups"配列があることを確認します。 次に例を示します。"tabs": [ { "builtInTabID": "TabDefault", "groups": [ { // properties omitted } ] } ]注:
"builtInTabID"プロパティの使用可能な値の一覧については、「組み込みの Office リボン タブの ID を検索する」を参照してください。"groups"配列に、ドロップダウン メニュー コントロールを保持するカスタム コントロール グループを定義するオブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。-
"id"は、マニフェスト内のすべてのリボン オブジェクト内のすべてのグループで一意である必要があります。 最大文字数は 64 文字です。 - リボンのグループに
"label"が表示されます。 最大長は 64 文字ですが、コントロール グループがリボンに正しく収まるようにするには、"label"を 16 文字に制限することをお勧めします。 - グループに表示される
"icons"の 1 つは、Office アプリケーション ウィンドウとリボンのサイズがユーザーによって小さすぎてグループ内のコントロールが表示されない場合のみです。 Office では、これらのアイコンのいずれかを使用するタイミングと、ウィンドウのサイズとデバイスの解像度に基づいて使用するアイコンを決定します。 これを制御することはできません。 16、32、80 ピクセルのイメージ ファイルを指定する必要があります。他の 5 つのサイズもサポートされています (20、24、40、48、64 ピクセル)。 すべての URL に Secure Sockets Layer (SSL) を使用する必要があります。
"groups": [ { "id": "msgReadGroup", "label": "Contoso Add-in", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "controls": [ { // properties omitted } ] } ]-
"controls"配列にコントロール オブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。-
"id"、"label"、および"icons"プロパティは、グループ オブジェクトの対応するプロパティと同じ目的と同じ制限を持ちますが、グループ内のドロップダウン メニューに適用される点が異なっています。 -
"type"プロパティは"menu"に設定されます。これは、コントロールがドロップダウン メニューであることを意味します。 -
"supertip.title"(最大長: 64 文字) と"supertip.description"(最大長: 128 文字) は、カーソルがメニューの上に置くと表示されます。 -
"items"プロパティには、2 つのメニュー オプションの JSON が含まれています。 値は、後の手順で追加されます。
{ "id": "msgReadMenu", "type": "menu", "label": "Contoso Menu", "icons": [ { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" }, { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" }, { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" } ], "supertip": { "title": "Show Contoso Actions", "description": "Opens the Contoso menu." }, "items": [ { "id": "", "type": "", "label": "", "supertip": {}, "actionId": "" }, { "id": "", "type": "", "label": "", "supertip": {}, "actionId": "" } ] }-
最初の項目には作業ウィンドウが表示されます。 次に例を示します。 このコードについては、次の点に注意してください。
-
"id"、"label"、および"supertip"プロパティは、親メニュー オブジェクトの対応するプロパティと同じ目的と同じ制限を持ちますが、このメニュー オプションのみに適用されます。 -
"icons"プロパティは、メニュー項目の場合は省略可能であり、この例では省略可能です。 含める場合、親メニューの"icons"プロパティと同じ目的と制限があります。ただし、アイコンがラベルの横にあるメニュー項目に表示される点が異なります。 -
"type"プロパティは"menuItem"に設定されています。 -
"actionId"は、「作業ウィンドウのランタイムを構成する」コマンドで設定した"runtimes.actions.id"と完全に一致している必要があります。
{ "id": "msgReadOpenPaneMenuItem", "type": "menuItem", "label": "Show Task Pane", "supertip": { "title": "Show Contoso Task Pane", "description": "Opens the Contoso task pane." }, "actionId": "ShowTaskPane" },-
2 番目の項目では、関数コマンドが実行されます。 次に例を示します。 このコードについては、次の点に注意してください。
-
"actionId"は、「関数コマンドのランタイムを構成する」で設定した"runtimes.actions.id"と完全に一致している必要があります。
{ "id": "msgReadSetNotificationMenuItem", "type": "menuItem", "label": "Set Notification", "supertip": { "title": "Set Notification", "description": "Displays a notification message on the current message." }, "actionId": "SetNotification" }-
これで、アドインへのメニューの追加が完了しました。 サイドロードしてテストします。
関連項目
Office Add-ins