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 に関する詳細については、「 JavaScript API for 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. それらについては、以下のセクションで説明します。They are described in the sections below. 新しく、より柔軟性が高い手法、呼び出し Office.onReady()の使用をお勧めします。We recommend that you use the newer, more flexible, technique, calling Office.onReady(). ハンドラーを割り当てる古いテクニック Office.initialize、はまだサポートされています。The older technique, assigning a handler to Office.initialize, is still supported. Office.initialize と Office.onReady() の間の主な相違点を参照してください。See also 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.

を呼び出す方法の 1 つは、 コールバック メソッドを渡すことです。Office.onReady()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 ホスト内にsideload する代わりに)ことを考えます。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 の中に呼び出される場合は$(document).ready は実行されません onReadySince 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 ライブラリが完全に読み込まれ、ユーザーとの対話の準備が完了すると、initialize イベントが発生します。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 が追加の 理由 のパラメーターを提供します。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.initialize と Office.onReadyの間の主な相違点Major differences between Office.initialize and Office.onReady

  • にハンドラーを 1 つだけを割り当てることができ、1 回だけは、Office のインフラストラクチャで呼び出すことができますが、 Office.onReady()の呼び出しは コードと異なる場所にして、異なるコールバックを使用します。Office.initializeYou 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.js 自分自身の初期化の内部プロセスの最後に発生します。Office.initializeThe 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(). Initialize イベントがすでに実行されている場合には、すぐにコールバックが実行されます。If the initialize event has already happened, the callback runs immediately.

注意

スタートアップ ロジックがない場合でも、 JアドインのJavaScript を読み込む際に Office.onReady() を呼び出すか、または Office.initialize に空の関数を割り当てることは良い練習になります。これは、Office のホストとプラットフォームの組み合わせによっては、これらのいずれかが発生するまで、作業ウィンドウをロードできないためです。Even if you have no start-up logic, it is a good practice to either call Office.onReady() or assign an empty function to Office.initialize when your add-in JavaScript loads, because some Office host and platform combinations won't load the task pane until one of these happens. 次の行では、これを行う 2 つの方法を示しています。The following lines show the two ways this can be done:

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

Office JavaScript オブジェクトモデル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 プロジェクトProject
サポートされる****ホスト アプリケーションSupported Host applications Access Web アプリAccess web apps Excel、Excel,
Excel OnlineExcel Online
Outlook、Outlook,
Outlook Web App、Outlook Web App,
デバイス用OWAOWA for Devices
PowerPoint、PowerPoint,
PowerPoint OnlinePowerPoint 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