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

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

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 を使用すると、Word、Excel、PowerPoint など複数の種類のホスト アプリケーションに共通する UI、ダイアログ、クライアント設定などの機能にアクセスできます。Common APIs: Introduced with Office 2013, the Common 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 Common API. 次に例を示します。For example:

  • Context: Context オブジェクトは、アドインのランタイム環境を表し、API の主要なオブジェクトへのアクセスを提供します。Context: The Context object represents the runtime environment of the add-in and provides access to key objects of the API. これは contentLanguageofficeTheme などのブック構成の詳細で構成され、hostplatform などのアドインのランタイム環境に関する情報も提供します。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. さらに、requirements.isSetSupported() メソッドも提供されます。これを使用すると、指定した要件セットが、アドインが実行されている Excel アプリケーションでサポートされているかどうかを確認できます。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 メンバーの名前付きグループです。Requirement sets are named groups of API members. Office アドインはランタイム チェックを実行できます。または、マニフェストで指定されている要件セットを使用して、Office ホストがアドインに必要な API をサポートしているかどうかを確認できます。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. サポートされている各プラットフォームで使用できる特定の要件セットを確認するには、「Excel JavaScript API の要件セット」を参照してください。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

アドインのマニフェストで Requirements 要素 を使用して、アドインをアクティブにするために必要な最小要件セットや API メソッド (またはその両方) を指定できます。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. Office ホストまたはプラットフォームが、マニフェストの Requirements 要素で指定した要件セットまたは API メソッドをサポートしない場合、アドインはそのホストまたはプラットフォームでは実行されず、[個人用アドイン] に表示されるアドインの一覧にも表示されません。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 メモリに読み込むように指示されます。Calling the load() method on an Excel JavaScript object instructs the API to load the object into JavaScript memory when the sync() method runs. load() メソッドには、読み込むプロパティのコンマで区切られた名前を含む文字列や、読み込むプロパティを指定するオブジェクト、改ページのオプションなどを指定できます。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() メソッドを呼び出すと、オブジェクトのすべてのスカラー プロパティ (またはコレクション内のすべてのオブジェクトのすべてのスカラー プロパティ) が読み込まれます。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. Excel ホスト アプリケーションとアドイン間のデータ転送量を減らすには、読み込むプロパティを明示的に指定しないで load() メソッドを呼び出さないようにします。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. パラメーターとリレーションシップ名を、コンマで区切られた文字列または 1 つの配列として指定します。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 範囲のプロパティを設定します。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. この例では、2 つの範囲 (B2:E2 および B7:E7) のデータがあり、2 つの範囲の書式設定が最初は異なっていると仮定します。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 を選択することにより、ワークシートのコレクションを読み込みます。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. また、コレクションの上位 5 つのワークシートのみを読み込むように指定しています。It also specifies that only the top five worksheets in the collection should be loaded. top: 10skip: 5 を属性値として指定することで、次の 5 つのワークシートのセットを処理できます。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 つのカテゴリにグループ化されています。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. たとえば、Worksheet オブジェクトの name メンバーと position メンバーはスカラー プロパティですが、protectiontables はリレーションシップ (ナビゲーション プロパティ) です。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() メソッドを呼び出すと、オブジェクトのすべてのスカラー プロパティが読み込まれます。オブジェクトのナビゲーション プロパティは読み込まれません。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. その代わりに、load() メソッドを使用して、目的のナビゲーション プロパティ内のスカラー プロパティを個別に参照する必要があります。Instead, you should use the load() method to reference individual scalar properties within the desired navigation property. たとえば、範囲のフォント名を読み込むには、name プロパティへのパスとして format および font ナビゲーション プロパティを指定する必要があります。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 を使用すると、パスを詳しく調べることでナビゲーション プロパティのスカラー プロパティを設定できます。With the Excel JavaScript API, you can set scalar properties of a navigation property by traversing the path. たとえば、someRange.format.font.size = 10; を使用して範囲のフォント サイズを設定できます。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

入れ子になったナビゲーション プロパティを持つオブジェクトのプロパティを設定するのは面倒です。Setting properties on an object with nested navigation properties can be cumbersome. 前述のナビゲーション パスを使用してプロパティを個別に設定する代わりに、Excel JavaScript API のすべてのオブジェクトで使用できる、object.set() メソッドを使用できます。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. このメソッドを使用すると、同じ Office.js 型の別のオブジェクト、またはメソッドが呼び出されるオブジェクトのプロパティと同様に構造化されたプロパティを持つ JavaScript オブジェクトを渡すことによって、オブジェクトの複数のプロパティを一度に設定できます。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 のオブジェクトでのみ実装されます。The set() method is implemented only for objects within the host-specific Office JavaScript APIs, such as the Excel JavaScript API. 共通 (共有) 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 の条件が満たされない場合に例外を返します。Many Excel JavaScript API methods will return an exception when the condition of the API is not met. たとえば、ブックに存在しないワークシート名を指定してワークシートを取得しようとすると、getItem() メソッドは ItemNotFound 例外を返します。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 メソッドのバリエーションを使用できます。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. 指定された項目が存在しない場合、*OrNullObject メソッドは例外をスローするのではなく、null オブジェクト (JavaScript null ではない) を返します。An *OrNullObject method will return a null object (not the JavaScript null) rather than throwing an exception if the specified item doesn't exist. たとえば、Worksheets などのコレクションで getItemOrNullObject() メソッドを呼び出して、コレクションからのアイテムの取得を試行できます。For example, you can call the getItemOrNullObject() method on a collection such as Worksheets to attempt to retrieve an item from the collection. getItemOrNullObject() メソッドは、指定された項目が存在する場合はその項目を返し、それ以外の場合は null オブジェクトを返します。The getItemOrNullObject() method returns the specified item if it exists; otherwise, it returns a null object. 返される null オブジェクトには、ブール型プロパティ isNullObject が含まれています。これを評価して、オブジェクトが存在するかどうかを判断できます。The null object that is returned contains the boolean property isNullObject that you can evaluate to determine whether the object exists.

次のコード サンプルは getItemOrNullObject() メソッドを使用して、"Data" という名前のワークシートの取得を試行します。The following code sample attempts to retrieve a worksheet named "Data" by using the getItemOrNullObject() method. メソッドが null オブジェクトを返す場合は、新しいシートを作成し、そのシート上で操作を実行する必要があります。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