イベントを使用してアドインをアクティブ化する

イベントベースのアクティベーションを使用すると、イベントに応答してアドインを自動的に起動できるため、ユーザーが直接操作しなくても、重要なコンテンツを検証、挿入、または更新できます。ユーザーが混乱しないように、アドインがバックグラウンドでアクティブ化されます。イベントベースのアクティベーションを作業ウィンドウおよび関数コマンドと統合することもできます。

概要

イベントベースの機能をアドインに追加する特定の手順は、プラットフォームやマニフェストの種類によって異なりますが、一般的なフローは次のとおりです。

イベントを処理するアクションを割り当てるようにマニフェストを更新します。
JavaScript 関数を作成し、必ず event.completed メソッドを呼び出します。
Office.actions.associate メソッドを使用して、関数をマニフェストで指定されたアクションにマップします。

イベントベースのライセンス認証を試す

イベントベースのアクティベーションを使用してワークフローを効率化し、ユーザーエクスペリエンスを向上させる方法をご覧ください。サンプルを試して、機能の動作を確認してください。

Outlook のサンプル

Word サンプル

文書が開いたときにヘッダーを追加する

サポートされるイベント

次の表に、現在利用可能なイベントと、各イベントでサポートされているクライアントを示します。イベントが発生すると、ハンドラーはイベントの種類に固有の詳細を含む可能性のある event オブジェクトを受け取ります。 [ 説明 ] 列には、該当する場合は関連オブジェクトへのリンクが含まれます。

Excel、PowerPoint、Word イベント

イベントの正規名およびアドインのみのマニフェスト名	Microsoft 365 の統合マニフェスト名前	説明	サポートされるクライアントとチャネル
`OnDocumentOpened`	まだサポートされていません`	ユーザーがドキュメントを開いたとき、または新しいドキュメント、スプレッドシート、またはプレゼンテーションを作成したときに発生します。	Office on the web Windows での Office Office on Mac は今後利用可能になります

このイベントでアクティブ化されるアドインの例については、「 word-add-label-on-open」を参照してください。

ヒント

OnDocumentOpened イベントを使用すると、ドキュメントが開かれたときにコードを実行するようにマニフェスト内のアドインを構成できます。この機能は、 Office アプリケーションスコープです。 Microsoft 365 テナントの管理ポータルで Microsoft 365 管理者によってアドインがインストールされると、アドインがサポートするようにマニフェストで構成されている Office アプリケーションで開かれているすべての Office ドキュメントに対してコードが起動して実行されます。この機能は、次の 3 つの同様の機能とは異なります。

アドインは、ドキュメントを開いたときにコードを実行するようにプログラムで構成できます。この手法には ドキュメントスコープがあり、各ドキュメントに個別に適用する必要があります。詳細については、「ドキュメントを開くときにコードを実行するように構成する」を参照してください。
アドインは、ドキュメントが開いたときに自動的にアドインの作業ウィンドウを開くようにプログラムでドキュメントを構成できます。また、この機能は各ドキュメントに個別に適用する必要があります。詳細については、「ドキュメントを含む作業ウィンドウを自動的に開く」を参照してください。
アドインは、エンドユーザーがインストールした ときに 作業ウィンドウを開くようにマニフェストで構成できます。この機能のスコープは 1 つのドキュメント (アドインのインストール時に開かれているドキュメント) に限定されます。詳細については、「アドインのインストール時に作業ウィンドウを自動的に開く」を参照してください。

Outlook イベント

Outlook でのこの機能のサポートは要件セット 1.10 で導入され、以降の要件セットで追加のイベントを使用できるようになりました。次の表に、各イベントの最小要件セットと、それをサポートするクライアントとプラットフォームを示します。 Outlook クライアントとそれらがサポートする要件セットの詳細については、「 Exchange サーバーおよび Outlook クライアントでサポートされている要件セット」を参照してください。

イベントの正規名およびアドインのみのマニフェスト名	Microsoft 365 の統合マニフェスト名前	説明	最小要件セットとサポートされるクライアント
`OnNewMessageCompose`	newMessageComposeCreated	新しいメッセージの作成時 ([全員に返信]、[全員に返信]、[転送] を含む) が、編集時 (下書きなど) 時には使用しません。	1.10 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI² Android²³ iOS²³
`OnNewAppointmentOrganizer`	newAppointmentOrganizerCreated	新しい予定を作成する際は行うが、既存の予定を編集する時は行わない。	1.10 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnMessageAttachmentsChanged`	messageAttachmentsChanged	メッセージの作成中に添付ファイルを追加または削除するとき。イベント固有のデータオブジェクト: AttachmentsChangedEventArgs	1.11 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnAppointmentAttachmentsChanged`	appointmentAttachmentsChanged	予定の作成中に添付ファイルを追加または削除する場合。イベント固有のデータオブジェクト: AttachmentsChangedEventArgs	1.11 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnMessageRecipientsChanged`	messageRecipientsChanged	メッセージの作成中に受信者を追加または削除するとき。イベント固有のデータオブジェクト: RecipientsChangedEventArgs	1.11 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI² Android²³ iOS²³
`OnAppointmentAttendeesChanged`	appointmentAttendeesChanged	予定の作成中に出席者を追加または削除するとき。イベント固有のデータオブジェクト: RecipientsChangedEventArgs	1.11 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnAppointmentTimeChanged`	appointmentTimeChanged	予定の作成中に日付/時刻を変更する場合。イベント固有のデータオブジェクト: AppointmentTimeChangedEventArgs 重要: 予定を予定表上の別の日付/時間枠にドラッグアンドドロップしても、 `OnAppointmentTimeChanged` イベントは発生しません。日時が予定から直接変更された場合にのみ発生します。	1.11 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnAppointmentRecurrenceChanged`	appointmentRecurrenceChanged	予定の作成中に定期的な詳細を追加、変更、または削除する場合。日時が変更されると、 `OnAppointmentTimeChanged` イベントも発生します。イベント固有のデータオブジェクト: RecurrenceChangedEventArgs	1.11 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnInfoBarDismissClicked`	infoBarDismissClicked	メッセージまたは予定アイテムの作成中に通知を閉じるとき。通知を追加したアドインのみが通知されます。イベント固有のデータオブジェクト: InfobarClickedEventArgs	1.11 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnMessageSend`	messageSending	メッセージアイテムの送信時。詳細については、スマートアラートのチュートリアルをお試しください。	1.12 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnAppointmentSend`	appointmentSending	予定アイテムの送信時。詳細については、「スマートアラートを使用して Outlook アドインで OnMessageSend イベントと OnAppointmentSend イベントを処理する」を参照してください。	1.12 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnMessageCompose`	messageComposeOpened	新しいメッセージの作成時 ([全員に返信]、[全員に返信]、[転送]) または下書きの編集時。	1.12 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnAppointmentOrganizer`	appointmentOrganizerOpened	新しい予定を作成するとき、または既存の予定を編集するとき。	1.12 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnMessageFromChanged`	messageFromChanged	作成中のメッセージの [差出人 ] フィールドのメールアカウントを変更するとき。詳細については、「 Exchange アカウントを切り替えるときに署名を自動的に更新する」を参照してください。	1.13 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI² Android²³ iOS²³
`OnAppointmentFromChanged`	appointmentFromChanged	作成中の予定の [開催者] フィールドのメールアカウントの変更時。詳細については、「 Exchange アカウントを切り替えるときに署名を自動的に更新する」を参照してください。	1.13 新しい Mac UI²
`OnSensitivityLabelChanged`	sensitivityLabelChanged	メッセージまたは予定の作成中に秘密度ラベルを変更する場合。メールアイテムの秘密度ラベルを管理する方法については、「作成モードでメッセージまたは予定の秘密度ラベルを管理する」を参照してください。イベント固有のデータオブジェクト: SensitivityLabelChangedEventArgs	1.13 Web ブラウザー Windows (新規およびクラシック¹) 新しい Mac UI²
`OnMessageReadWithCustomAttachment`	使用不可	特定の添付ファイルの種類を含むメッセージを閲覧モードで開いたとき。	プレビュー⁴ Windows (クラシック¹)
`OnMessageReadWithCustomHeader`	使用不可	特定のインターネットヘッダー名を含むメッセージを読み取りモードで開いたとき。	プレビュー⁴ Windows (クラシック¹)
`OnMessageDecrypt`	messageDecrypt	暗号化されたメッセージのヘッダーをアドインのマニフェスト内のヘッダーキーと照合するとき。詳細については、「暗号化 Outlook アドインを作成する」を参照してください。	1.16 Web ブラウザー Windows (新規およびクラシック¹)

注:

¹ 従来の Outlook on Windows のイベントベースのアドインを実行するには、Windows 10 Version 1903 (ビルド 18362) または Windows Server 2019 Version 1903 以降が必要です。

² Microsoft 365 の統合マニフェストを使用するアドインは、Outlook on Mac およびモバイルデバイスではサポートされていません。 Mac とモバイルプラットフォームでアドインを使用できるようにするには、アドインのみのマニフェストを使用する 2 番目のバージョンを作成する必要があります。詳細については、 Microsoft 365 用統合アプリマニフェストを使用した Office アドインの「クライアントとプラットフォームのサポート」セクションを参照してください。

³ 詳細については、「 Outlook モバイルアドインにイベントベースのライセンス認証を実装する」を参照してください。

⁴OnMessageReadWithCustomAttachment イベントと OnMessageReadWithCustomHeader イベントをプレビューするには、従来の Outlook on Windows バージョン 2312 (ビルド 17110.10000) 以降をインストールする必要があります。次に、 Microsoft 365 Insider プログラムに参加し、 ベータチャネル オプションを選択して Office ベータビルドにアクセスします。

モバイルデバイス上の Outlook でのイベントベースのライセンス認証

モバイル上の Outlook では、メールボックス要件セット 1.5 までの API がサポートされます。ただし、後の要件セットで導入される追加の API や機能 ( OnNewMessageCompose イベントなど) のサポートが有効になっています。詳細については、「 Outlook モバイルアドインにイベントベースのライセンス認証を実装する」を参照してください。

動作と制限事項

イベントベースのアドインを開発するときは、次の機能の動作と制限事項に注意してください。

イベントベースのアドインは、管理者が展開した場合にのみ機能します。ユーザーが Microsoft Marketplace または Office Store から直接インストールした場合、自動的には起動しません (Microsoft Marketplace の制限の回避策については、「イベントに基づくアドインの Microsoft Marketplace 登録オプション」を参照してください)。管理展開は、マニフェストを Microsoft 365 管理センターにアップロードすることによって行われます。
UI 要素または表示 UI 要素と対話する API は、Word、PowerPoint、Excel ではサポートされていません。これは、イベントハンドラーが JavaScript のみのランタイムで実行されるためです。詳細については、「 Office アドインのランタイム」を参照してください。
イベントベースのアドインでは、特定のイベントの発生時に起動するためにインターネット接続が必要です。アドインイベントハンドラーは、実行時間が短く、軽量で、できる限り非侵入的であることが期待されています。アクティブ化後、アドインは約 300 秒以内にタイムアウトします。これは、イベントに基づくアドインの実行に許可されている最大時間です。アドインが起動イベントの処理を完了したことを示すには、関連するイベントハンドラーが event.completed メソッドを呼び出す必要があります。 ( event.completed ステートメントの後に含まれるコードは実行が保証されていないことに注意してください。)アドインが処理するイベントがトリガーされるたびに、アドインが再アクティブ化され、関連するイベントハンドラーが実行され、タイムアウト期間がリセットされます。タイムアウト後にアドインが終了するか、ユーザーが作成ウィンドウを閉じるか、アイテムが送信される。
同じイベントをサブスクライブする複数のアドインの動作は決定論的ではありません。 Outlook は、指定された順序でアドインを起動しません。 Excel、PowerPoint、Word の場合、ランダムな 1 つのアドインのみがアクティブ化されます。たとえば、OnDocumentOpenedを処理する複数の Word アドインの場合、それらのハンドラーのうちの 1 つだけが実行されます。
現在、アクティブに実行できるイベントベースのアドインは 5 つだけです。
サポートされているすべての Outlook クライアントで、アドインの実行を完了するには、アドインがアクティブ化された現在のメールアイテムにユーザーが残っている必要があります。現在のアイテムから移動すると (たとえば、別の作成ウィンドウやタブに切り替える)、アドインの操作は終了します。ただし、 OnMessageSend イベントでアクティブ化されるアドインは、実行している Outlook クライアントに応じて異なる方法でアイテムの切り替えを処理します。詳細については、「スマートアラートを使用して Outlook アドインで OnMessageSend イベントと OnAppointmentSend イベントを処理する」の「ユーザーが現在のメッセージから離れる」セクションを参照してください。
イベントベースのアドインは、アイテムの切り替えに加えて、作成中のメッセージまたは予定をユーザーが送信したときにも動作を停止します。

Windows 上の Excel、PowerPoint、Word、従来の Outlook でのイベントに基づくアドインの制限事項

Windows クライアントで実行するイベントベースのアドインを開発する場合は、次の点に注意してください。

イベントベースのアクティブ化の処理を実装する JavaScript ファイルでは、インポートはサポートされていません。
イベントベースのアクティベーションでは、マニフェストで参照されている JavaScript ファイルのみがサポートされています。イベント処理 JavaScript コードをこの 1 つのファイルにバンドルする必要があります。マニフェスト内で参照される JavaScript ファイルの場所は、アドインで使用するマニフェストの種類によって異なります。
- アドインのみのマニフェスト: <Runtime> ノード<Override>子要素
- Microsoft 365 の統合マニフェスト: "code" オブジェクトの"script"プロパティ
JavaScript バンドルが大きいと、アドインのパフォーマンスが低下する可能性があることに注意してください。負荷の高い操作は、イベント処理コードに含まれないように前処理することをお勧めします。
イベントを処理するためにマニフェストで指定された JavaScript 関数が実行されても、 Office.onReady() と Office.initialize のコードは実行されません。ユーザーのクライアントバージョンの確認など、イベントハンドラーに必要なスタートアップロジックを、代わりにイベントハンドラーに追加することをお勧めします。
Outlook では、返信メールリンク (mailto リンク) によって開始されたメッセージを作成するときに、 OnNewMessageCompose イベントハンドラーの [宛先]、[Cc]、または [Bcc] フィールドから受信者を取得すると、空の配列が返される場合があります。この問題は、 OnNewMessageCompose イベントが発生するまでに Outlook が受信者の電子メールアドレスの解決を完了していない場合に発生します。これを回避するには、代わりに OnMessageRecipientsChanged イベントハンドラーで受信者をチェックします。

Excel、PowerPoint、Word でのイベントベースのアドインの制限事項

次のプラットフォームまたは機能はまだサポートされていません。

Office on Mac

Outlook on the web と新しい Outlook on Windows でのイベントベースのアドインの制限

Outlook on the web と新しい Outlook on Windows では、イベントベースのライセンス認証は、標準の読み取りと作成のメッセージと予定画面でのみサポートされます。標準以外のサーフェイスでコンポジションしている場合、イベントベースのアクティベーションが機能しない場合があります。例:

[ メモ付き出欠確認] オプションを使用して会議出席依頼に返信する。
予定表から会議を転送する。

サポートされていない API

UI を変更または変更する一部の Office.js API は、イベントベースのアドインのイベントハンドラーでは許可されません。ブロックされる API を次に示します。

API	メソッド
`Office.devicePermission`	`requestPermissionsAsync`
`Office.context.auth`*	`getAccessToken` `getAccessTokenAsync`
`Office.context.mailbox`	`displayAppointmentForm` `displayMessageForm` `displayNewAppointmentForm` `displayNewMessageForm`
`Office.context.mailbox.item`	`close`
`Office.context.ui`	`displayDialogAsync` `messageParent`

注:

* OfficeRuntime.auth は、イベントベースのライセンス認証とシングルサインオン (SSO) をサポートするすべてのバージョンでサポートされていますが、 Office.auth は特定の Outlook ビルドでのみサポートされます。詳細については、「イベントベースの Outlook アドインまたはスパム報告 Outlook アドインでシングルサインオン (SSO) またはクロスオリジンリソース共有 (CORS) を使用する」を参照してください。

イベントハンドラーのプレビュー機能 (従来の Outlook on Windows)

従来の Outlook on Windows には、コンテンツ配信ネットワーク (CDN) から読み込む代わりに、Office.js の製品版とベータ版のローカルコピーが含まれています。既定では、API のローカル製品コピーが参照されます。 API のローカルベータ版を参照するには、コンピューターのレジストリを構成する必要があります。これにより、Windows 上の従来の Outlook のイベントハンドラーでプレビュー機能をテストできます。

レジストリで、[ HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer] に移動します。キーが存在しない場合は、作成します。
EnableBetaAPIsInJavaScript という名前のエントリを作成し、その値を 1 に設定します。

シングルサインオン (SSO) を有効にする

イベントに基づくアドインで SSO を有効にするには、その JavaScript ファイルを既知の URI に追加する必要があります。このリソースの構成方法については、「イベントベースの Office アドインまたはスパムを報告する Office アドインでシングルサインオン (SSO) またはクロスオリジンリソース共有 (CORS) を使用する」を参照してください。

外部データの要求

外部データを要求するには、 Fetch などの API を使用するか、サーバーと対話するために HTTP 要求を発行する標準の Web API である XMLHttpRequest (XHR) を使用します。

注:

アドインが JavaScript のみのランタイムで動作する場合は、Fetch API 呼び出しで絶対 URL を使用します。フェッチ API 呼び出しの相対 URL は、JavaScript のみのランタイムではサポートされていません。

XMLHttpRequest オブジェクトを使用する場合は、追加のセキュリティ対策を使用する必要があり、同一生成元ポリシーと CORS (クロスオリジンリソース共有) が必要であることに注意してください。

注:

完全な CORS サポートは、Office on the web、Mac、および Windows (バージョン 2201、ビルド 16.0.14813.10000 以降) クライアントで利用できます。

イベントに基づくアドインから CORS 要求を行うには、アドインとその JavaScript ファイルを既知の URI に追加する必要があります。このリソースの構成方法については、「イベントベースの Office アドインまたはスパムを報告する Office アドインでシングルサインオン (SSO) またはクロスオリジンリソース共有 (CORS) を使用する」を参照してください。

アドインのトラブルシューティング

イベントベースのアドインを開発するときには、アドインが読み込まれない、イベントが発生しないなどの問題のトラブルシューティングが必要になる場合があります。イベントベースのアドインのトラブルシューティング方法については、「イベントベースのアドインとスパム報告アドインのトラブルシューティング」を参照してください。

アドインを展開する

Office アプリケーションによっては、次のいずれかのオプションを使用してイベントベースのアドインを展開できます。

管理管理の展開: アドインは Microsoft 365 管理センターを通じて展開されます。
Microsoft Marketplace での制限付きリスト: アドインは Microsoft Marketplace に公開されますが、検索結果には表示されません。アドインの取得にはフライトコードの URL が必要です。イベントベースのアクティブ化機能が動作するには、管理者がアドインを展開する必要があります。
Microsoft Marketplace での制限なしの一覧: アドインは Microsoft Marketplace に公開され、ユーザーと管理者はアドインの名前または ID を使用して検索できます。イベントベースのライセンス認証機能を機能させるために、管理展開は必要ありません。アドインは、無制限のリストの特定の要件を満たしている必要があります。

次の表に、Office アプリケーションによるイベントベースのライセンス認証の展開オプションを示します。

Office アプリケーション	管理管理の展開	Microsoft Marketplace
Excel	サポート	制限付きリストオプション
Outlook	サポート	制限付きおよび制限なしのリスティングオプション
PowerPoint	サポート	制限付きリストオプション
Word	サポート	制限付きリストオプション

Microsoft 365 管理センターを使用してアドインを展開する方法については、「管理管理の展開」を参照してください。イベントに基づくアドインを Microsoft Marketplace に一覧表示する方法の詳細については、「イベントに基づくアドインの Microsoft Marketplace 登録オプション」を参照してください。

重要

スマートアラート機能を使用するアドインは、マニフェストの送信モードプロパティがプロンプト、ユーザー、またはソフトブロック オプションに設定されている場合にのみ、Microsoft Marketplace に公開できます。アドインの送信モードプロパティが [ブロック] に設定されている場合、Microsoft Marketplace の検証に失敗するため、organization の管理者のみが展開できます。

管理管理の展開

管理展開は、マニフェストを Microsoft 365 管理センターにアップロードすることによって行われます。これを行うには、次の手順を実行します。

管理ポータルで、ナビゲーションウィンドウの [ 設定 ] セクションを展開し、[ 統合アプリ] を選択します。
[ 統合アプリ ] ページで、[ カスタムアプリのアップロード ] アクションを選択します。
次の手順は、使用されているマニフェストによって異なります。
- Microsoft 365 の統合マニフェスト:
  1. [ アプリの種類 ] ドロップダウンボックスで、[ Teams アプリ] を選択します。 Office アドインではありません。
  2. ファイル選択コントロールを使用して、アプリパッケージの zip ファイルに移動して選択します。
  3. ページの指示に従って、インストールを完了します。
- アドインのみのマニフェスト:
  1. [ アプリの種類 ] ドロップダウンボックスで、[ Office アドイン] を選択します。
  2. ファイル選択コントロールを使用して、マニフェストに移動し、選択します。
  3. ページの指示に従って、インストールを完了します。

[カスタムアプリのアップロード] アクションが強調表示された Microsoft 365 管理センターの [統合アプリ] ページ。

アドインを展開する方法の詳細については、「Microsoft 365 管理センターで Office アドインを展開して公開する」を参照してください。

マニフェスト更新プログラムの展開

イベントベースのアドインが管理者によって展開されている場合、マニフェストに変更を加えるには、Microsoft 365 管理センターを通じて管理者の同意が必要です。管理者が変更を受け入れるまで、organization 内のユーザーはアドインを使用できません。管理者の同意プロセスの詳細については、「イベントベースのアドインをインストールするための管理の同意」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-02