Microsoft 365 の統合マニフェストを使用してアドイン コマンドをCreateする
アドイン コマンドは、アクションを実行する指定された UI 要素を使用して、既定の Office ユーザー インターフェイス (UI) をカスタマイズする簡単な方法を提供します。 アドイン コマンドの概要については、「アドイン コマンド」を参照してください。
この記事では、 Microsoft 365 (プレビュー) 用の統合マニフェスト を構成してアドイン コマンドを定義する方法と 、関数コマンドのコードを作成する方法について説明します。
ヒント
XML マニフェストを使用してアドイン コマンドを作成する手順は、xml マニフェストを使用Createアドイン コマンドにあります。
注:
統合マニフェストは現在、Windows 上の Outlook アドインでのみサポートされています。 プレビュー段階であり、運用環境のアドインではまだサポートされていません。
開始点と主要な手順
Office Yeoman ジェネレーター と Teams 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" に、前の手順で設定したページの内容を説明する名前 ("ホームページ" や "ダッシュボード" など) があることを確認します。
ランタイム オブジェクトの "actions.id" に、ユーザーがアドイン コマンド ボタンまたはメニュー項目を選択したときに何が起こるかを示す "ShowTaskPane" などのわかりやすい名前があることを確認します。
ランタイム オブジェクトの次の完成した例に示すように、ランタイム オブジェクトの他のプロパティとサブプロパティを設定します。 "型" プロパティと "有効期間" プロパティは必須であり、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" 配列のピアとしての "リボン" 配列プロパティがあることを確認します。 通常、"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" プロパティに使用できる値は "TabDefault" のみです。Outlook では、[ ホーム]、[ メッセージ]、または [ 会議 ] タブのいずれかです。統合マニフェストのサポートが他の Office ホスト アプリケーションに追加されると、他にも可能な値が存在します。
"groups" 配列に、アドイン コマンド UI コントロールを保持するカスタム コントロール グループを定義するオブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。
- "id" は、マニフェスト内のすべてのリボン オブジェクト内のすべてのグループで一意である必要があります。 最大文字数は 64 文字です。
- リボンのグループに "ラベル" が表示されます。 最大文字数は 64 文字です。
- "アイコン" の 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" }
これで、アドインへの作業ウィンドウ コマンドの追加が完了しました。 サイドロードしてテストします。
関数コマンドを追加する
次のサブセクションでは、アドインに 関数コマンド を含める方法について説明します。
関数コマンドのコードをCreateする
ソース コードに、関数コマンドで実行する関数を含む 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です。
ファイルに
<body>
UI がないため、要素は空です。 その唯一の目的は、JavaScript ファイルを読み込むためです。前の手順で作成した Office JavaScript ライブラリと commands.js ファイルが明示的に読み込まれます。
注:
Office アドイン開発では、 Webpack やそのプラグインなどのツールを使用して、ビルド時にタグを HTML ファイルに自動的に挿入
<script>
するのが一般的です。 このようなツールを使用する場合は、ツールによって挿入されるタグをソース ファイルに含<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.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
の最初のパラメーターと完全に一致している必要があります。ランタイム オブジェクトの次の完成した例に示すように、ランタイム オブジェクトの他のプロパティとサブプロパティを設定します。 "type" プロパティと "lifetime" プロパティは必須であり、常に Outlook アドインに表示される値を持ちます。これは、現在統合マニフェストをサポートしている唯一のホストです。
"runtimes": [ { "id": "CommandsRuntime", "type": "general", "code": { "page": "https://localhost:3000/commands.html" }, "lifetime": "short", "actions": [ { "id": "SetNotification", "type": "executeFunction", } ] } ]
関数コマンドの UI を構成する
ランタイムを構成した拡張オブジェクトに、"runtimes" 配列のピアとしての "リボン" 配列プロパティがあることを確認します。 通常、"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 と、少なくとも 1 つのオブジェクトを含む "groups" 配列に設定された "builtInTabId" 文字列プロパティを持つオブジェクトがあることを確認します。 次に例を示します。
"tabs": [ { "builtInTabID": "TabDefault", "groups": [ { // properties omitted } ] } ]
注:
"builtInTabID" プロパティに使用できる値は "TabDefault" のみです。Outlook では、[ ホーム]、[ メッセージ]、または [ 会議 ] タブのいずれかです。統合マニフェストのサポートが他の Office ホスト アプリケーションに追加されると、他にも可能な値が存在します。
"groups" 配列に、アドイン コマンド UI コントロールを保持するカスタム コントロール グループを定義するオブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。
- "id" は、マニフェスト内のすべてのリボン オブジェクト内のすべてのグループで一意である必要があります。 最大文字数は 64 文字です。
- リボンのグループに "ラベル" が表示されます。 最大文字数は 64 文字です。
- "アイコン" の 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" 配列のピアとしての "リボン" 配列プロパティがあることを確認します。 通常、"extensions" 配列には拡張オブジェクトが 1 つだけ存在します。
次の例に示すように、配列に "contexts" と "tabs" という名前の配列プロパティを持つオブジェクトがあることを確認します。
"ribbons": [ { "contexts": [ // child objects omitted ], "tabs": [ // child objects omitted ] } ]
"contexts" 配列に、リボンにメニューを表示するウィンドウまたはペインを指定する文字列があることを確認します。 たとえば、"mailRead" は、メール メッセージが開いているときに閲覧ウィンドウまたはメッセージ ウィンドウに表示されることを意味しますが、"mailCompose" は、新しいメッセージまたは返信が構成されているときに表示されることを意味します。 許容される値を次に示します。
- mailRead
- mailCompose
- meetingDetailsOrganizer
- meetingDetailsAttendee
次に例を示します。
"contexts": [ "mailRead" ],
"tabs" 配列に、作業ウィンドウ コマンドを表示するリボン タブの ID と、少なくとも 1 つのオブジェクトを含む "groups" 配列に設定された "builtInTabId" 文字列プロパティを持つオブジェクトがあることを確認します。 次に例を示します。
"tabs": [ { "builtInTabID": "TabDefault", "groups": [ { // properties omitted } ] } ]
注:
"builtInTabID" プロパティに使用できる値は "TabDefault" のみです。Outlook では、[ ホーム]、[ メッセージ]、または [ 会議 ] タブのいずれかです。統合マニフェストのサポートが他の Office ホスト アプリケーションに追加されると、他にも可能な値が存在します。
"groups" 配列に、ドロップダウン メニュー コントロールを保持するカスタム コントロール グループを定義するオブジェクトがあることを確認します。 次に例を示します。 この JSON については、次の点に注意してください。
- "id" は、マニフェスト内のすべてのリボン オブジェクト内のすべてのグループで一意である必要があります。 最大文字数は 64 文字です。
- リボンのグループに "ラベル" が表示されます。 最大文字数は 64 文字です。
- "アイコン" の 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
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示