Excel JavaScript API を使用した高度なプログラミングの概念Advanced programming concepts with the Excel JavaScript API

この記事では、「 Excel JavaScript API の基本的なプログラミングの概念 」の情報を基にして、より高度な概念をいくつか説明します。これらは Excel 2016 の複雑なアドインを構築するために不可欠です。This article builds upon the information in Excel JavaScript API core concepts to describe some of the more advanced concepts that are essential to building complex add-ins for Excel 2016.

Excel 用の Office.js APIOffice.js APIs for Excel

Excel アドインは、次の 2 つの JavaScript オブジェクト モデルを含む JavaScript API for Office を使用して、Excel のオブジェクトを操作します。An Excel add-in interacts with objects in Excel by using the JavaScript API for Office, which includes two JavaScript object models:

  • Excel JavaScript API: Office 2016 で導入された Excel JavaScript API には、ワークシート、範囲、表、グラフなどへのアクセスに使用できる、厳密に型指定されたオブジェクトが用意されています。Excel JavaScript API: Introduced with Office 2016, the Excel JavaScript API provides strongly-typed objects that you can use to access worksheets, ranges, tables, charts, and more.

  • 共通 API: Office 2013 で導入された共通 API (共有 API とも呼ばれる) を使用すると、Word、Excel、PowerPoint など複数の種類のホスト アプリケーションに共通する UI、ダイアログ、クライアント設定などの機能にアクセスできます。Common APIs: Introduced with Office 2013, the common APIs (also referred to as the Shared API) can be used to access features such as UI, dialogs, and client settings that are common across multiple types of host applications such as Word, Excel, and PowerPoint.

Excel 2016 を対象にしたアドインでは、機能の大部分を Excel JavaScript API を使用して開発する可能性がありますが、共有 API のオブジェクトも使用します。While you'll likely use the Excel JavaScript API to develop the majority of functionality in add-ins that target Excel 2016 or later, you'll also use objects in the Shared API. 次に例を示します。For example:

  • コンテキスト: コンテキスト オブジェクトは、アドインのランタイム環境を表し、API の主要なオブジェクトへのアクセスを提供します。contentLanguageofficeTheme のようなブック構成の詳細を含み、hostplatform のようなアドインのランタイム環境に関する情報も提供します。さらに、requirements.isSetSupported() メソッドを提供し、指定された要件セットがアドインが実行されている Excel のアプリケーションでサポートされているかを確認するために使用することができます。Context: The Context object represents the runtime environment of the add-in and provides access to key objects of the API. It consists of workbook configuration details such as contentLanguage and officeTheme and also provides information about the add-in's runtime environment such as host and platform. Additionally, it provides the requirements.isSetSupported() method, which you can use to check whether the specified requirement set is supported by the Excel application where the add-in is running.

  • Document:Document オブジェクトは getFileAsync() メソッドを提供します。これを使用すると、アドインが実行されている Excel ファイルをダウンロードできます。Document: The Document object provides the getFileAsync() method, which you can use to download the Excel file where the add-in is running.

要件セットRequirement sets

要件のセットを API メンバーのグループと呼びます。Office アドインを実行時チェックを実行したり、Office ホストがアドインを必要とする Api をサポートしているかどうかを判断するには、マニフェストで指定されている要件のセットを使用できます。サポートされる各プラットフォームで利用可能な特定の要件のセットを識別するには、 Excel の JavaScript API の要件の設定を参照してください。Requirement sets are named groups of API members. An Office Add-in can perform a runtime check or use requirement sets specified in the manifest to determine whether an Office host supports the APIs that the add-in needs. To identify the specific requirement sets that are available on each supported platform, see Excel JavaScript API requirement sets.

実行時に要件セットのサポートを確認するChecking for requirement set support at runtime

次のコード サンプルは、アドインが実行されているホスト アプリケーションが指定された API の要件セットをサポートしているかどうかを確認する方法を示しています。The following code sample shows how to determine whether the host application where the add-in is running supports the specified API requirement set.

if (Office.context.requirements.isSetSupported('ExcelApi', 1.3) === true) {
  /// perform actions
}
else {
  /// provide alternate flow/logic
}

マニフェストで要件セットのサポートを定義するDefining requirement set support in the manifest

アドインのマニフェストで 要件の要素 を使用して、最小限の要件セットおよび/またはアドインを有効にするのに必要な API メソッドを指定します。Office ホストまたはプラットフォームが要件セットまたはマニフェストの 要件 の要素で指定されている API のメソッドをサポートしていない場合は、アドインはそのホストまたはプラットフォームでは実行されず、 My アドイン に表示されるアドインの一覧に表示されません。You can use the Requirements element in the add-in manifest to specify the minimal requirement sets and/or API methods that your add-in requires to activate. If the Office host or platform doesn't support the requirement sets or API methods that are specified in the Requirements element of the manifest, the add-in won't run in that host or platform, and won't display in the list of add-ins that are shown in My Add-ins.

次のコード サンプルは、アドインが ExcelApi 要件セットのバージョン 1.3 以上をサポートする Office ホスト アプリケーションのすべて読み込まれる必要があることを指定する、アドインのマニフェストの Requirements 要素を示しています。The following code sample shows the Requirements element in an add-in manifest which specifies that the add-in should load in all Office host applications that support ExcelApi requirement set version 1.3 or greater.

<Requirements>
   <Sets DefaultMinVersion="1.3">
      <Set Name="ExcelApi" MinVersion="1.3"/>
   </Sets>
</Requirements>

注意

Excel for Windows、Excel Online、Excel for iPad などの Office ホストのプラットフォームすべてでアドインを使用できるようにするには、マニフェストで要件セットのサポートを定義するのではなく、実行時に要件のサポートを確認することをお勧めします。To make your add-in available on all platforms of an Office host, such as Excel for Windows, Excel Online, and Excel for iPad, we recommend that you check for requirement support at runtime instead of defining requirement set support in the manifest.

Office.js 共通 API の要件セットRequirement sets for the Office.js Common API

共通 API の要件セットの詳細は、「Office 共通 API の要件セット」を参照してください。For information about common API requirement sets, see Office common API requirement sets.

オブジェクトのプロパティを読み込むLoading the properties of an object

Excel JavaScript オブジェクトで load() メソッドを呼び出すと、API はsync() メソッドの実行時にオブジェクトを JavaScript メモリに読み込むように指示されます。load() メソッドには、読み込むプロパティのコンマで区切られた名前を含む文字列や、読み込むプロパティを指定するオブジェクト、改ページのオプションなどを指定できます。Calling the load() method on an Excel JavaScript object instructs the API to load the object into JavaScript memory when the sync() method runs. The load() method accepts a string that contains comma-delimited names of properties to load or an object that specifies properties to load, pagination options, etc.

注意

パラメーターを指定せずにオブジェクト (またはコレクション) の load() メソッドを呼び出すと、オブジェクトのすべてのスカラー プロパティ (またはコレクション内のすべてのオブジェクトのすべてのスカラー プロパティ) が読み込まれます。Excel ホスト アプリケーションとアドイン間のデータ転送量を減らすには、読み込むプロパティを明示的に指定しないで load() メソッドを呼び出さないようにします。If you call the load() method on an object (or collection) without specifying any parameters, all scalar properties of the object (or all scalar properties of all objects in the collection) will be loaded. To reduce the amount of data transfer between the Excel host application and the add-in, you should avoid calling the load() method without explicitly specifying which properties to load.

メソッドの詳細Method details

load(param: object)load(param: object)

JavaScript レイヤーで作成されたプロキシ オブジェクトに、パラメーターで指定されているプロパティとオブジェクトの値を設定します。Fills the proxy object created in JavaScript layer with property and object values specified by the parameters.

構文Syntax

object.load(param);

パラメーターParameters

パラメーターParameter Type 説明Description
param objectobject 省略可能です。パラメーターとの関係の名前をコンマで区切られた文字列または配列を受け取ります。(次の例で示すように) 選択とナビゲーション プロパティを設定するオブジェクトを渡すこともできます。Optional. Accepts parameter and relationship names as comma-delimited string or an array. An object can also be passed to set the selection and navigation properties (as shown in the example below).

戻り値Returns

Voidvoid

Example

次のコード サンプルでは、別の範囲のプロパティをコピーして 1 つの Excel の範囲のプロパティを設定します。プロパティ値にアクセスして対象範囲に書き込む前に、ソース オブジェクトを最初に読み込む必要があることに注意してください。この例では、2 つの範囲 (B2:E2 および B7:E7) のデータがあり、2 つの範囲の書式設定が最初は異なっていると仮定します。The following code sample sets the properties of one Excel range by copying the properties of another range. Note that the source object must be loaded first, before its property values can be accessed and written to the target range. This example assumes that there is data the two ranges (B2:E2 and B7:E7) and that the two ranges are initially formatted differently.

Excel.run(function (ctx) { 
    var sheet = ctx.workbook.worksheets.getItem("Sample");
    var sourceRange = sheet.getRange("B2:E2");
    sourceRange.load("format/fill/color, format/font/name, format/font/color");

    return ctx.sync()
        .then(function () {
            var targetRange = sheet.getRange("B7:E7");
            targetRange.set(sourceRange); 
            targetRange.format.autofitColumns();

            return ctx.sync();
        });
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

オプションのプロパティを読み込むLoad option properties

load() メソッドを呼び出すときに、コンマで区切られた文字列または配列を渡す代わりに、次のプロパティを含むオブジェクトを渡すことができます。As an alternative to passing a comma-delimited string or array when you call the load() method, you can pass an object that contains the following properties.

プロパティProperty Type 説明Description
select objectobject パラメーター/リレーションシップの名前のコンマ区切りリストまたは配列が含まれます。省略可能。Contains a comma-delimited list or an array of parameter/relationship names. Optional.
expand objectobject リレーションシップ名のコンマ区切りリストまたは配列が含まれています。省略可能。Contains a comma-delimited list or an array of relationship names. Optional.
top intint 結果に含めることができるコレクション項目の最大数を指定します。省略可能。このオプションは、オブジェクト表記オプションを使用する場合にのみ使用できます。Specifies the maximum number of collection items that can be included in the result. Optional. You can only use this option when you use the object notation option.
skip intint スキップされて結果に組み込まれないコレクション内の項目の数を指定します。top が指定されている場合は、指定された数の項目がスキップされた後で結果セットが開始されます。省略可能。このオプションは、オブジェクト表記オプションを使用する場合にのみ使用できます。Specify the number of items in the collection that are to be skipped and not included in the result. If top is specified, the result set will start after skipping the specified number of items. Optional. You can only use this option when you use the object notation option.

次のコード サンプルは、コレクション内の各ワークシートの使用範囲の name プロパティと address を選択することにより、ワークシートのコレクションを読み込みます。また、コレクションの最上位の 5 つのワークシートのみを読み込むことを指定します。top: 10skip: 5 を属性値として指定することで、次の 5 つのワークシートのセットを処理できます。The following code sample loads a workskeet collection by selecting the name property and the address of the used range for each worksheet in the collection. It also specifies that only the top five worksheets in the collection should be loaded. You could process the next set of five worksheets by specifying top: 10 and skip: 5 as attribute values.

myWorksheets.load({
    select: 'name, userRange/address',
    expand: 'tables',
    top: 5,
    skip: 0
});

スカラー プロパティとナビゲーション プロパティScalar and navigation properties

Excel JavaScript API のリファレンス ドキュメントでは、オブジェクトのメンバーは、2 つのカテゴリにグループ化されています: プロパティリレーションシップです。オブジェクトのプロパティは、文字列、整数、ブール値などのスカラー メンバーです。一方、オブジェクトのリレーションシップ (ナビゲーション プロパティとも呼ばれる) は、オブジェクトまたはオブジェクトのコレクションのいずれかであるメンバーです。たとえば、 Worksheet オブジェクトの name メンバーと position メンバーはスカラー プロパティですが、protectiontables はリレーションシップ (ナビゲーション プロパティ) です。In the Excel JavaScript API reference documentation, you may notice that object members are grouped into two categories: properties and relationships. A property of an object is a scalar member such as a string, an integer, or a boolean value, while a relationship of an object (also known as a navigation property) is a member that is either an object or collection of objects. For example, name and position members on the Worksheet object are scalar properties, whereas protection and tables are relationships (navigation properties).

を使用したスカラー プロパティとナビゲーション プロパティ object.load()Scalar properties and navigation properties with object.load()

パラメーターを指定しないで object.load() メソッドを呼び出すと、オブジェクトのすべてのスカラー プロパティが読み込まれます。オブジェクトのナビゲーション プロパティは読み込まれません。さらに、ナビゲーション プロパティは直接読み込むことができません。代わりに、load() メソッドを使用して、目的のナビゲーション プロパティ内の個別のスカラー プロパティを参照する必要があります。たとえば、範囲のフォント名を読み込むには、name プロパティへのパスとして format および font ナビゲーション プロパティを指定する必要があります。Calling the object.load() method with no parameters specified will load all scalar properties of the object; navigation properties of the object will not be loaded. Additionally, navigation properties cannot be loaded directly. Instead, you should use the load() method to reference individual scalar properties within the desired navigation property. For example, to load the font name for a range, you must specify the format and font navigation properties as the path to the name property:

someRange.load("format/font/name")

注意

Excel JavaScript API を使用すると、パスを詳しく調べることでナビゲーション プロパティのスカラー プロパティを設定できます。たとえば、someRange.format.font.size = 10; を使用して範囲のフォント サイズを設定できます。プロパティを設定する前にロードする必要はありません。With the Excel JavaScript API, you can set scalar properties of a navigation property by traversing the path. For example, you could set the font size for a range by using someRange.format.font.size = 10;. You do not need to load the property before you set it.

オブジェクトのプロパティを設定するSetting properties of an object

入れ子になったナビゲーション プロパティを持つオブジェクトのプロパティの設定は面倒です。前述のナビゲーション パスを使用してプロパティを個別に設定する代わりに、Excel JavaScript API のすべてのオブジェクトで使用できる、object.set() メソッドを使用できます。このメソッドを使用すると、同じ Office.js 型の別のオブジェクト、またはメソッドが呼び出されるオブジェクトのプロパティと同様に構造化されたプロパティを持つ JavaScript オブジェクトを渡すことによって、オブジェクトの複数のプロパティを一度に設定できます。Setting properties on an object with nested navigation properties can be cumbersome. As an alternative to setting individual properties using navigation paths as described above, you can use the object.set() method that is available on all objects in the Excel JavaScript API. With this method, you can set multiple properties of an object at once by passing either another object of the same Office.js type or a JavaScript object with properties that are structured like the properties of the object on which the method is called.

注意

set()\メソッドは、Excel JavaScript API などホスト固有の Office JavaScript API のオブジェクトでのみ実装されます。共通 (共有) API は、このメソッドをサポートしていません。The set() method is implemented only for objects within the host-specific Office JavaScript APIs, such as the Excel JavaScript API. The common (shared) APIs do not support this method.

set (properties: object, options: object)set (properties: object, options: object)

メソッドが呼び出されるオブジェクトのプロパティは、渡されたオブジェクトの対応するプロパテに指定された値に設定されます。properties パラメーターが JavaScript オブジェクトの場合、メソッドが呼び出される読み取り専用プロパティに対応する渡されたオブジェクトの任意のプロパティは、options パラメーターの値に応じて、無視されるか、例外のスローが発生します。Properties of the object on which the method is called are set to the values that are specified by the corresponding properties of the passed-in object. If the properties parameter is a JavaScript object, any property of the passed-in object that corresponds to a read-only property in the object on which the method is called will either be ignored or cause an exception to be thrown, depending on the value of the options parameter.

構文Syntax

object.set(properties[, options]);

パラメーターParameters

パラメーターParameter Type 説明Description
properties objectobject メソッドが呼び出されるオブジェクトの同じ Office.js 型のオブジェクト、またはメソッドが呼び出されるオブジェクトの構造を反映するプロパティ名と型を持つ JavaScript オブジェクトのいずれかです。Either an object of the same Office.js type of the object on which the method is called, or a JavaScript object with property names and types that mirror the structure of the object on which the method is called.
options objectobject 省略可能。最初のパラメーターが JavaScript オブジェクトの場合にのみ渡すことができます。オブジェクトには、次のプロパティを含めることができます。throwOnReadOnly?: boolean (既定値は true。渡された JavaScript オブジェクトに読み取り専用プロパティが含まれている場合は、エラーをスローします。)Optional. Can only be passed when the first parameter is a JavaScript object. The object can contain the following property: throwOnReadOnly?: boolean (Default is true: throw an error if the passed in JavaScript object includes read-only properties.)

戻り値Returns

Voidvoid

Example

次のコード サンプルは、set() メソッドを呼び出し、Range オブジェクトのプロパティの構造を反映するプロパティ名と型を持つ JavaScript オブジェクトを渡すことによって、範囲のいくつかの書式プロパティを設定します。この例では、範囲 B2:E2 にデータがあると仮定します。The following code sample sets several format properties of a range by calling the set() method and passing in a JavaScript object with property names and types that mirror the structure of properties in the Range object. This example assumes that there is data in range B2:E2.

Excel.run(function (ctx) { 
    var sheet = ctx.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("B2:E2");
    range.set({
        format: {
            fill: {
                color: '#4472C4'
            },
            font: {
                name: 'Verdana',
                color: 'white'
            }
        }
    });
    range.format.autofitColumns();

    return ctx.sync(); 
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

*OrNullObject メソッド*OrNullObject methods

多くの Excel JavaScript API メソッドは、API の条件が満たされない場合に例外を返します。たとえば、ブックに存在しないワークシート名を指定してワークシートを取得しようとすると、getItem() メソッドは ItemNotFound 例外を返します。Many Excel JavaScript API methods will return an exception when the condition of the API is not met. For example, if you attempt to get a worksheet by specifying a worksheet name that doesn't exist in the workbook, the getItem() method will return an ItemNotFound exception.

このようなシナリオの複雑な例外処理論理を実装する代わりに、Excel JavaScript API のいくつかのメソッドで使用可能な*OrNullObjectメソッド変数を使用することができます。*OrNullObjectメソッドは、特定のアイテムが存在しなければ例外を投げずに null 値 (JavaScriptnull ではない) を返します。たとえば、ワークシート のようなコレクションでgetItemOrNullObject()メソッドを呼び出して、コレクションからアイテムを引き出すことができます。getItemOrNullObject()メソッドは指定したアイテムが存在すればそれを返しますが、そうでなければ null オブジェクトを返します。返される null オブジェクトには、オブジェクトが存在するかの決定を評価できる boolean プロパティisNullObjectが含まれます。Instead of implementing complex exception handling logic for scenarios like this, you can use the *OrNullObject method variant that's available for several methods in the Excel JavaScript API. An *OrNullObject method will return a null object (not the JavaScript null) rather than throwing an exception if the specified item doesn't exist. For example, you can call the getItemOrNullObject() method on a collection such as Worksheets to attempt to retrieve an item from the collection. The getItemOrNullObject() method returns the specified item if it exists; otherwise, it returns a null object. The null object that is returned contains the boolean property isNullObject that you can evaluate to determine whether the object exists.

次のコード サンプルは getItemOrNullObject() メソッドを使用して、"Data" という名前のワークシートの取得を試行します。メソッドが null オブジェクトを返す場合は、新しいシートを作成し、そのシート上で操作を実行する必要があります。The following code sample attempts to retrieve a worksheet named "Data" by using the getItemOrNullObject() method. If the method returns a null object, a new sheet needs to be created before actions can taken on the sheet.

var dataSheet = context.workbook.worksheets.getItemOrNullObject("Data"); 

return context.sync()
  .then(function() {
    if (dataSheet.isNullObject) { 
        // Create the sheet
    }

    dataSheet.position = 1;
    //...
  })

関連項目See also