JavaScript API for Office についてUnderstanding the JavaScript API for Office

この記事では、JavaScript API for Office とその使用方法に関する情報を提供します。参照情報については、「JavaScript API for Office」を参照してください。Visual Studio プロジェクト ファイルを JavaScript API for Office の最新バージョンに更新する方法については、「JavaScript API for Office およびマニフェスト スキーマ ファイルのバージョンを更新する」を参照してください。This article provides information about the JavaScript API for Office and how to use it. For reference information, see JavaScript API for Office. For information about updating Visual Studio project files to the most current version of the JavaScript API for Office, see Update the version of your JavaScript API for Office and manifest schema files.

注意

AppSource にアドインを公開し、Office エクスペリエンスで利用できるようにする予定がある場合は、AppSource の検証ポリシーに準拠していることを確認してください。たとえば、検証に合格するには、定義したメソッドをサポートするすべてのプラットフォームでアドインが動作する必要があります (詳細については、セクション 4.12Office アドインを使用できるホストおよびプラットフォームのページを参照してください)。If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

アドインで JavaScript API for Office ライブラリを参照するReferencing the JavaScript API for Office library in your add-in

JavaScript API for Office ライブラリは、Office.js ファイルと関連するホスト アプリケーション固有のファイル (Excel-15.js や Outlook-15.js など) で構成されています。最も簡単に API を参照する方法は、次に示す <script> をページの <head> タグに追加して、CDN を使用することです。The JavaScript API for Office library consists of the Office.js file and associated host application-specific .js files, such as Excel-15.js and Outlook-15.js. The simplest method of referencing the API is using our CDN by adding the following <script> to your page's <head> tag:

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

これにより、アドインが最初に読み込まれるときに JavaScript API for Office ファイルのダウンロードとキャッシュを実行して、アドインが確実に指定したバージョンの最新の Office.js および関連ファイルを使用するようにします。This will download and cache the JavaScript API for Office files the first time your add-in loads to make sure that it is using the most up-to-date implementation of Office.js and its associated files for the specified version.

バージョン管理や下位互換性の処理方法など、Office.js CDN に関する詳細については、「Office ライブラリの JavaScript API を Office コンテンツ配信ネットワーク (CDN) から参照する」を参照してください。For more details around the Office.js CDN, including how versioning and backward compatability is handled, see Referencing the JavaScript API for Office library from its content delivery network (CDN).

アドインの初期化Initializing your add-in

適用対象: すべてのアドインの種類Applies to: All add-in types

Office アドインには、次のような処理を行うスタートアップ ロジックがよくあります。Office Add-ins often have start-up logic to do things such as:

  • ユーザーの Office のバージョンが、ご使用のコードを呼び出す Office API をすべてサポートするかを確認します。Check that the user's version of Office will support all the Office APIs that your code calls.

  • 特定の名前を含むワークシートなど、特定の成果物の有無を確認します。Ensure the existence of certain artifacts, such as worksheet with a specific name.

  • Excel でユーザーにいくつかのセルを選択するプロンプトを表示したり、選択した値で初期化されたグラフを挿入したりすることです。You can use the initialize event handler to implement common add-in initialization scenarios, such as prompting the user to select some cells in Excel, and then inserting a chart initialized with those selected values.

  • バインディングを確立します。Establish bindings.

  • Office ダイアログ API を使用して、アドインの設定の既定値をユーザーに確認します。Use the Office dialog API to prompt the user for default add-in settings values.

ただし、ライブラリが完全に読み込まれるまで、スタートアップ コードは任意の Office.js API を呼び出してはいけません。But your start-up code must not call any Office.js APIs until the library is fully loaded. ご利用のコードで確実にライブラリが読み込まれるようにするには、2 つの方法があります。There are two ways that your code can ensure that the library is loaded. これらの方法は、次の各セクションで説明します。These attributes are described in the following sections.

これらの手法の違いの詳細については、「Office.initialize と Office.onReady の間の主な相違点」を参照してください。For information about the differences in these techniques, see Major differences between Office.initialize and Office.onReady(). アドインの初期化時のイベントのシーケンスの詳細については、「DOM とランタイム環境を読み込む」を参照してください。For more detail about the sequence of events when an add-in is initialized, see Loading the DOM and runtime environment.

Office.onReady() を使用した初期化Initialize with Office.onReady()

Office.onReady() は、Office.js ライブラリが完全に読み込まれているかどうかをチェックするときに、Promise オブジェクトを返す非同期メソッドです。Office.onReady() is an asynchronous method that returns a Promise object while it checks to see if the Office.js library is fully loaded. ライブラリが読み込まれるとき (に限り)、Office ホスト アプリケーションを Office.HostType 列挙値 (ExcelWord など)、およびプラットフォームを Office.PlatformType 列挙値 (PCMacOfficeOnline など) で指定するオブジェクトとして Promise を解決します。When, and only when, the library is loaded, it resolves the Promise as an object that specifies the Office host application with an Office.HostType enum value (Excel, Word, etc.) and the platform with an Office.PlatformType enum value (PC, Mac, OfficeOnline, etc.). Office.onReady() を呼び出すときに、ライブラリが既に読み込まれている場合、Promise をすぐに解決します。If the library is already loaded when Office.onReady() is called, then the Promise resolves immediately.

Office.onReady() を呼び出す方法の 1 つは、コールバック メソッドを渡すことです。One way to call Office.onReady() is to pass it a callback method. 次に例を示します。Here's an example:

Office.onReady(function(info) {
    if (info.host === Office.HostType.Excel) {
        // Do Excel-specific initialization (for example, make add-in task pane's
        // appearance compatible with Excel "green").
    }
    if (info.platform === Office.PlatformType.PC) {
        // Make minor layout changes in the task pane.
    }
    console.log(`Office.js is now ready in ${info.host} on ${info.platform}`);
});

また、コールバックを渡す代わりに、then() メソッドを Office.onReady() の呼び出しにチェーン接続することもできます。Alternatively, you can chain a then() method to the call of Office.onReady(), instead of passing a callback. たとえば、次のコードで、ユーザーのバージョンの Excel が、アドインで呼び出す可能性があるすべての API をサポートしているかを確認します。For example, the following code checks to see that the user's version of Excel supports all the APIs that the add-in might call.

Office.onReady()
    .then(function() {
        if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
            console.log("Sorry, this add-in only works with newer versions of Excel.");
        }
    });

asyncawait キーワードを TypeScript で使用する同じ例を次に示します。Here is the same example using the async and await keywords in TypeScript:

(async () => {
    await Office.onReady();
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
})();

独自の初期化ハンドラーやテストを含む追加の JavaScript フレームワークを使用している場合、通常、そのようなフレームワークは Office.onReady() への応答内に配置される必要があります。If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should be placed within the Office.initialize event. たとえば、JQuery$(document).ready() 関数は次のように参照します。For example, JQuery's $(document).ready() function would be referenced as follows:

Office.onReady(function() {
    // Office is ready
    $(document).ready(function () {
        // The document is ready
    });
});

ただし、この実習には例外があります。However, there are exceptions to this practice. たとえば、ブラウザーのツールを使用してご使用の UI をデバッグするため、(Office ホスト内にサイドロードする代わりに) ブラウザーでご利用のアドインを開く必要があるとします。For example, suppose you want to open your add-in in a browser (instead of sideload it in an Office host) in order to debug your UI with browser tools. Office.js がブラウザーに読み込まれないため、onReady は実行できず、Office onReady 内に呼び出される場合は、$(document).ready は実行されません。Since Office.js won't load in the browser, onReady won't run and the $(document).ready won't run if it's called inside the Office onReady. 別の例外: アドインの読み込み中に、作業ウィンドウに表示する進行状況のインジケーターが必要です。Another exception: you want a progress indicator to appear in the task pane while the add-in is loading. このシナリオでは、コードで jQuery ready を呼び出す必要があり、コールバックを使用して進行状況のインジケーターを表示します。In this scenario, your code should call the jQuery ready and use it's callback to render the progress indicator. その後、Office onReady のコールバックで、進行状況のインジケーターを最終的な UI に置き換えることができます。Then the Office onReady's callback can replace the progress indicator with the final UI.

Office.initialize を使用した初期化Initialize with Office.initialize

Office.js ライブラリが完全に読み込まれ、ユーザーとの対話の準備が完了すると、初期化イベントが発生します。An initialize event fires when the Office.js library is fully loaded and ready for user interaction. 初期化ロジックを実装する Office.initialize にハンドラーを割り当てることができます。You can assign a handler to Office.initialize that implements your initialization logic. ユーザーのバージョンの Excel が、アドインで呼び出す可能性があるすべての API をサポートしているかを確認する例は、次のとおりです。The following is an example that checks to see that the user's version of Excel supports all the APIs that the add-in might call.

Office.initialize = function () {
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
};

独自の初期化ハンドラーやテストを含む追加の JavaScript フレームワークを使用している場合、通常、そのようなフレームワークは Office.initialize イベント内に配置される必要があります If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should be placed within the Office.initialize event. (ただし、前に「Office.onReady() を使用した初期化」セクションで説明した例外が、この場合も適用されます)。たとえば、JQuery$(document).ready() 関数は、次のように参照されます。(But the exceptions described in the Initialize with Office.onReady() section earlier apply in this case also.) For example, JQuery's $(document).ready() function would be referenced as follows:

Office.initialize = function () {
    // Office is ready
    $(document).ready(function () {
        // The document is ready
    });
  };

作業ウィンドウ アドインとコンテンツ アドインの場合、Office.initialize で追加の reason パラメーターが提供されます。For task pane and content add-ins, Office.initialize provides an additional reason parameter. このパラメーターでは、アドインがどのように現在のドキュメントに追加されたかが示されます。This parameter specifies how an add-in was added to the current document. これは、最初にアドインが挿入されたときと、既にアドインがドキュメント内に存在しているときに、別のロジックを提供するために使用できます。For task pane and content add-ins, Office.initialize provides an additional reason parameter. This parameter can be used to determine how an add-in was added to the current document. You can use this to provide different logic for when an add-in is first inserted versus when it already existed within the document.

Office.initialize = function (reason) {
    $(document).ready(function () {
        switch (reason) {
            case 'inserted': console.log('The add-in was just inserted.');
            case 'documentOpened': console.log('The add-in is already part of the document.');
        }
    });
 };

詳細については、Office.initialize イベントに関するページ、および InitializationReason 列挙型に関するページを参照してください。For more information, see Office.initialize Event and InitializationReason Enumeration.

注意

現在、Office.onReady() も呼び出したかどうかに関係なく、Office.Initialize を設定する必要があります。Currently, you must set Office.Initialize, regardless of whether Office.onReady() is also called. Office.Initialize が必要ない場合には、次の例に示すように空の関数を設定することができます。If you have no use for Office.Initialize, you can set it to an empty function as shown in the following example.

Office.initialize = function () {};

Office.initialize と Office.onReady の間の主な相違点Major differences between Office.initialize and Office.onReady

  • Office.initialize にハンドラーは 1 つだけ割り当てることができ、1 回だけは、Office のインフラストラクチャで呼び出されますが、Office.onReady() の呼び出しはコードと異なる場所にして、異なるコールバックを使用します。You can assign only one handler to Office.initialize and it is called, only once, by the Office infrastructure; but you can call Office.onReady() in different places in your code and use different callbacks. たとえば、ご利用のコードでは、カスタム スクリプトが初期化ロジックを実行するコールバックを読み込むとすぐに Office.onReady() を呼び出しますが、ご利用のコードには、そのスクリプトが異なるコールバックで Office.onReady() を呼び出す、ボタンを作業ウィンドウに含めることもできます。For example, your code could call Office.onReady() as soon as your custom script loads with a callback that runs initialization logic; and your code could also have a button in the task pane, whose script calls Office.onReady() with a different callback. その場合は、ボタンがクリックされたときに 2 番目のコールバックが実行されます。If so, the second callback runs when the button is clicked.

  • Office.initialize イベントは、Office.js 自体が初期化される内部プロセスの最後に発生します。The Office.initialize event fires at the end of the internal process in which Office.js initializes itself. 内部のプロセスが終了した後、すぐに発生します。And it fires immediately after the internal process ends. イベントにハンドラーを割り当てるコードが、イベント発生後に長時間実行される場合、ハンドラーは実行されません。If the code in which you assign a handler to the event executes too long after the event fires, then your handler doesn't run. たとえば、WebPack タスク マネージャーを使用する場合は、Office.js が読み込まれた後で、カスタム JavaScript を読み込む前に、ポリフィルのファイルを読み込むためのアドインのホーム ページを構成する場合があります。For example, if you are using the WebPack task manager, it might configure the add-in's home page to load polyfill files after it loads Office.js but before it loads your custom JavaScript. ご使用のスクリプトでハンドラーの読み込みと割り当てが行われる時点で、初期化イベントは既に発生しています。By the time your script loads and assigns the handler, the initialize event has already happened. ですが、Office.onReady() を呼び出すのに "遅すぎる" ことは決してありません。But it is never "too late" to call Office.onReady(). 初期化イベントが既に発生している場合、コールバックがすぐに実行されます。If the initialize event has already happened, the callback runs immediately.

注意

スタートアップ ロジックがない場合でも、次の例に示すように、アドイン JavaScript を読み込むときには、空の関数を Office.initialize に割り当てる必要があります。Even if you have no start-up logic, you should assign an empty function to Office.initialize when your add-in JavaScript loads, as shown in the following example. Office のホストとプラットフォームの組み合わせによっては、初期化イベントが発生し、指定されたイベント ハンドラー関数が実行されるまで、作業ウィンドウは読み込まれません。Some Office host and platform combinations won't load the task pane until the initialize event fires and the specified event handler function runs.

Office.initialize = function () {};

Office JavaScript API オブジェクト モデルOffice JavaScript API object model

初期化されると、アドインでホスト (Excel、Outlook など) とやりとりできるようになります。Once initialized, the add-in can interact with the host (e.g. Excel, Outlook). 特定の使用パターンに関する詳細については、「Office JavaScript API オブジェクト モデル」ページを参照してください。The Office JavaScript API object model page has more details on specific usage patterns. 共有 API と特定のホストの両方についても、詳細な参照ドキュメントがあります。There is also detailed reference documentation for both shared APIs and specific hosts.

API サポート マトリックスAPI support matrix

次の表は、アドインの種類 (コンテンツ、作業ウィンドウ、および Outlook) 全体でサポートされている API と機能、および 1.1 アドイン マニフェスト スキーマと機能 (JavaScript API for Office v1.1 でサポート) を使用してアドインがサポートする Office のホスト アプリケーションを指定する際に、これらの API と機能をホストする Office アプリケーションについてまとめたものです。This table summarizes the API and features supported across add-in types (content, task pane, and Outlook) and the Office applications that can host them when you specify the Office host applications your add-in supports by using the 1.1 add-in manifest schema and features supported by v1.1 JavaScript API for Office.

ホスト名Host name データベースDatabase ブックWorkbook メールボックスMailbox プレゼンテーションPresentation ドキュメントDocument ProjectProject
サポートされる****ホスト アプリケーションSupported Host applications Access Web アプリAccess web apps Excel、Excel,
Excel OnlineExcel Online
Outlook、Outlook,
Outlook Web App、Outlook Web App,
OWA for DevicesOWA for Devices
PowerPoint,PowerPoint,
PowerPoint OnlinePowerPoint, PowerPoint Online
WordWord プロジェクトProject
サポートされるアドインの種類Supported add-in types コンテンツContent Yy Yy Yy
作業ウィンドウTask pane Yy Yy Yy Yy
OutlookOutlook Yy
サポートされている API 機能Supported API features テキストの読み取り/書き込みRead/Write Text Yy Yy Yy Yy
(読み取り専用)(Read only)
マトリックスの読み取り/書き込みRead/Write Matrix Yy Yy
テーブルの読み取り/書き込みRead/Write Table Yy Yy
HTML の読み取り/書き込みRead/Write HTML Yy
読み取り/書き込みRead/Write
Office Open XMLOffice Open XML
Yy
タスク、リソース、ビュー、フィールド プロパティの読み取りRead task, resource, view, and field properties Yy
選択変更イベントSelection changed events Yy Yy
ドキュメント全体の取得Get whole document Yy Yy
バインドとイベント バインドBindings and binding events Yy
(完全および部分的なテーブル バインドのみ)(Only full and partial table bindings)
Yy Yy
カスタム XML パーツの読み取り/書き込みRead/Write Custom XML Parts Yy
アドイン状態データの保持 (設定)Persist add-in state data (settings) Yy
(ホスト アドインごと)(Per host add-in)
Yy
(ドキュメントごと)(Per document)
Yy
(メールボックスごと)(Per mailbox)
Yy
(ドキュメントごと)(Per document)
Yy
(ドキュメントごと)(Per document)
設定変更イベントSettings changed events Yy Yy Yy Yy
アクティブ ビュー モードGet active view mode
およびビュー変更イベントの取得and view changed events
Yy
ドキュメント内のNavigate to locations
場所に移動in the document
Yy Yy Yy
ルールと RegEx を使用したActivate contextually
文脈からのアクティブ化using rules and RegEx
Yy
アイテム プロパティの読み取りRead Item properties Yy
ユーザー プロファイルの読み取りRead User profile Yy
添付ファイルの取得Get attachments Yy
ユーザー ID トークンの取得Get User identity token Yy
Exchange Web サービスの呼出Call Exchange Web Services Yy