DOM とランタイム環境を読み込むLoading the DOM and runtime environment

アドインでは、DOM と Office アドイン両方のランタイム環境が、独自のカスタム ロジックを実行する前に読み込まれていることを確認する必要があります。An add-in must ensure that both the DOM and the Office Add-ins runtime environment are loaded before running its own custom logic.

コンテンツまたは作業ウィンドウ アドインの起動Startup of a content or task pane add-in

次の図は、Excel、PowerPoint、Project、Word、または Access でコンテンツ アドインまたは作業ウィンドウ アドインの起動に関連するイベントのフローを示しています。The following figure shows the flow of events involved in starting a content or task pane add-in in Excel, PowerPoint, Project, Word, or Access.

コンテンツ アドインまたは作業ウィンドウ アドイン起動時のイベントのフロー

コンテンツ アドインまたは作業ウィンドウ アドインが起動すると、次のイベントが発生します。The following events occur when a content or task pane add-in starts:

  1. ユーザーは、既にアドインが含まれているドキュメントを開くか、ドキュメントにアドインを挿入します。The user opens a document that already contains an add-in or inserts an add-in in the document.

  2. Office ホスト アプリケーションが、アドインの XML マニフェストを AppSource、SharePoint のアドイン カタログ、またはアドインの発生元である共有フォルダー カタログから読み取ります。The Office host application reads the add-in's XML manifest from AppSource, an add-in catalog on SharePoint, or the shared folder catalog it originates from.

  3. Office ホスト アプリケーションが、ブラウザー コントロールにアドインの HTML ページを開きます。The Office host application opens the add-in's HTML page in a browser control.

    次の手順 4. と 5. は、同時に実行されることも、同時に実行されないこともあります。したがって、次の処理に進む前に、DOM とアドイン ランタイム環境の両方の読み込みが完了したことをアドインのコードで確認する必要があります。The next two steps, steps 4 and 5, occur asynchronously and in parallel. For this reason, your add-in's code must make sure that both the DOM and the add-in runtime environment have finished loading before proceeding.

  4. ブラウザー コントロールが、DOM と HTML 本文を読み込み、window.onload イベントに対するイベント ハンドラーを呼び出します。The browser control loads the DOM and HTML body, and calls the event handler for the window.onload event.

  5. Office ホスト アプリケーションがランタイム環境を読み込みます (このランタイム環境は、コンテンツ配布ネットワーク (CDN) サーバーから JavaScript API for JavaScript ライブラリ ファイルをダウンロードしてキャッシュします)。その後、ハンドラーが割り当てられている場合は、Office オブジェクトの initialize イベントに対するアドインのイベント ハンドラーを呼び出します。The Office host application loads the runtime environment, which downloads and caches the JavaScript API for JavaScript library files from the content distribution network (CDN) server, and then calls the add-in's event handler for the initialize event of the Office object, if a handler has been assigned to it. 現時点では、コールバック (またはチェーンされた then() 関数) が Office.onReady ハンドラーに渡された (チェーンされた) かどうかも確認します。At this time it also checks to see if any callbacks (or chained then() functions) have been passed (or chained) to the Office.onReady handler. Office.initializeOffice.onReady の違いの詳細については、「アドインの初期化」をご覧ください。For more information about the distinction between Office.initialize and Office.onReady, see Initializing your add-in.

  6. DOM と HTML 本文の読み込み、およびアドインの初期化が完了すると、アドインのメイン関数は処理を続行できます。When the DOM and HTML body finish loading and the add-in finishes initializing, the main function of the add-in can proceed.

Outlook アドインの起動Startup of an Outlook add-in

次の図は、デスクトップ、タブレット、スマートフォンで実行される Outlook アドインの起動に関係するイベントのフローを示しています。The following figure shows the flow of events involved in starting an Outlook add-in running on the desktop, tablet, or smartphone.

Outlook アドイン起動時のイベントのフロー

Outlook アドインが起動すると、次のイベントが発生します。The following events occur when an Outlook add-in starts:

  1. Outlook は起動時に、ユーザーの電子メール アカウント用にインストールされている Outlook アドインの XML マニフェストを読み取ります。When Outlook starts, Outlook reads the XML manifests for Outlook add-ins that have been installed for the user's email account.

  2. ユーザーが Outlook でアイテムを選択します。The user selects an item in Outlook.

  3. 選択されたアイテムが Outlook アドインのアクティブ化条件を満たしている場合は、Outlook がアドインをアクティブにし、ボタンを UI に表示します。If the selected item satisfies the activation conditions of an Outlook add-in, Outlook activates the add-in and makes its button visible in the UI.

  4. ユーザーがボタンをクリックして Outlook アドインを起動すると、Outlook がアプリの HTML ページをブラウザー コントロール内に表示します。次の手順 5 と 6 は同時に行われます。If the user clicks the button to start the Outlook add-in, Outlook opens the HTML page in a browser control. The next two steps, steps 5 and 6, occur in parallel.

  5. ブラウザー コントロールが DOM と HTML 本文を読み込んで、onload イベントに対するイベント ハンドラーを呼び出します。The browser control loads the DOM and HTML body, and calls the event handler for the onload event.

  6. Outlook がランタイム環境を読み込みます (このランタイム環境は、コンテンツ配布ネットワーク (CDN) サーバーから JavaScript API for JavaScript ライブラリ ファイルをダウンロードしてキャッシュします)。その後、ハンドラーが割り当てられている場合は、アドインの Office オブジェクトの initialize イベントに対するイベント ハンドラーを呼び出します。Outlook loads the runtime environment, which downloads and caches the JavaScript API for JavaScript library files from the content distribution network (CDN) server, and then calls the event handler for the initialize event of the Office object of the add-in, if a handler has been assigned to it. 現時点では、コールバック (またはチェーンされた then() 関数) が Office.onReady ハンドラーに渡された (チェーンされた) かどうかも確認します。At this time it also checks to see if any callbacks (or chained then() functions) have been passed (or chained) to the Office.onReady handler. Office.initializeOffice.onReady の違いの詳細については、「アドインの初期化」をご覧ください。For more information about the distinction between Office.initialize and Office.onReady, see Initializing your add-in.

  7. DOM と HTML 本文の読み込み、およびアドインの初期化が完了すると、アドインのメイン関数は処理を続行できます。When the DOM and HTML body finish loading and the add-in finishes initializing, the main function of the add-in can proceed.

読み込み状態のチェックChecking the load status

DOM とランタイム環境の両方で読み込みが完了したことを確認する方法の 1 つは、jQuery .ready() 関数を使用することです: $(document).ready()One way to check that both the DOM and the runtime environment have finished loading is to use the jQuery .ready() function: $(document).ready(). たとえば、次の onReady イベント ハンドラーは、アドインの実行の初期化に固有のコードの前に、DOM が最初に読み込まれることを確認します。For example, the following onReady event handler makes sure the DOM is first loaded before the code specific to initializing the add-in runs. その後、onReady ハンドラーは mailbox.item プロパティを使用して、Outlook で現在選択されている項目を取得し、アドインのメイン関数 initDialer を呼び出します。Subsequently, the onReady handler proceeds to use the mailbox.item property to obtain the currently selected item in Outlook, and calls the main function of the add-in, initDialer.

Office.onReady()
    .then(
        // Checks for the DOM to load.
        $(document).ready(function () {
            // After the DOM is loaded, add-in-specific code can run.
            var mailbox = Office.context.mailbox;
            _Item = mailbox.item;
            initDialer();
        });
);

また、次の例に示されているように、同じコードを initialize イベント ハンドラーで使用することができます。Alternatively, you can use the same code in an initialize event handler as shown in the following example.

Office.initialize = function () {
    // Checks for the DOM to load.
    $(document).ready(function () {
        // After the DOM is loaded, add-in-specific code can run.
        var mailbox = Office.context.mailbox;
        _Item = mailbox.item;
        initDialer();
    });
}

この方法は、任意の Office アドインの onReady または initialize ハンドラーで使用できます。This same technique can be used in the onReady or initialize handlers of any Office Add-in.

ダイヤラー サンプル Outlook アドインでは、JavaScript のみを使用してこれらと同じ条件を確認するという少し異なる方法を使用しています。The phone dialer sample Outlook add-in shows a slightly different approach using only JavaScript to check these same conditions.

重要

アドインに実行する初期化タスクがない場合でも、次の例に示されているように、Office.onReady の呼び出しを少なくとも 1 つ含めるか、最小のイベント ハンドラー関数 Office.initialize を割り当てる必要があります。Even if your add-in has no initialization tasks to perform, you must include at least a call of Office.onReady or assign minimal Office.initialize event handler function as shown in the following examples.

Office.onReady();
Office.initialize = function () {};

Office.onReady を呼び出したり、Office.initialize イベントを割り当てたりしない場合、アドインを開始するとエラーが発生する可能性があります。If you do not call Office.onReady or assign an Office.initialize event handler, your add-in may raise an error when it starts. また、ユーザーが Excel Online、PowerPoint Online、Outlook Web App などの Office Online Web クライアントでアドインを使用しようとすると、アドインの実行が失敗します。Also, if a user attempts to use your add-in with an Office Online web client, such as Excel Online, PowerPoint Online, or Outlook Web App, it will fail to run.

アドインに複数のページが含まれる場合、新しいページが読み込まれるときに、そのページは Office.onReady を呼び出すか、Office.initialize イベント ハンドラーを割り当てる必要があります。If your add-in includes more than one page, whenever it loads a new page that page must either call Office.onReady or assign an Office.initialize event handler.

関連項目See also