Excel アドインで複数の範囲を同時に操作する (プレビュー)Work with multiple ranges simultaneously in Excel add-ins (preview)

Excel JavaScript ライブラリを使用すると、同時に複数の範囲に対してアドインによる操作の実行とプロパティの設定が可能になります。The Excel JavaScript library enables your add-in to perform operations, and set properties, on multiple ranges simultaneously. 範囲は連続している必要はありません。The ranges do not have to be contiguous. コードがよりシンプルになることに加え、この方法でプロパティを設定すれば、各範囲に同じプロパティを個別に設定する方法よりも処理速度が格段に速くなります。In addition to making your code simpler, this way of setting a property runs much faster than setting the same property individually for each of the ranges.

注意

この記事で説明する API には、Office 2016 クイック実行バージョン 1809 Build 10820.20000 以降が必要です The APIs described in this article require Office 2016 Click-to-Run version 1809 Build 10820.20000 or later. (適切なビルドを取得するには、 Office Insider プログラムに参加する必要がある場合があります)。この機能を使用するには、office JavaScript ライブラリのプレビューバージョンをoffice の JS CDNから使用する必要があります。To use this feature, you must use the preview version of the Office JavaScript library from the Office.js CDN. TypeScript のコンパイルおよび IntelliSense 用の型定義ファイルは、CDN と、定義された定義ファイルにあります。The type definition file for TypeScript compilation and IntelliSense is found at the CDN and DefinitelyTyped. これらの種類は、でnpm install --save-dev @types/office-js-previewインストールできます。You can install these types with npm install --save-dev @types/office-js-preview. 今後予定されている API の詳細については、「Excel JavaScript API 要件セット」参照してください。For more information on our upcoming APIs, please visit Excel JavaScript API requirement sets.(You may need to join the Office Insider program to get an appropriate build.) この機能を使用するには、office JavaScript ライブラリのプレビューバージョンをoffice の JS CDNから使用する必要があります。To use this feature, you must use the preview version of the Office JavaScript library from the Office.js CDN. TypeScript のコンパイルおよび IntelliSense 用の型定義ファイルは、CDN と、定義された定義ファイルにあります。The type definition file for TypeScript compilation and IntelliSense is found at the CDN and DefinitelyTyped. これらの種類は、でnpm install --save-dev @types/office-js-previewインストールできます。You can install these types with npm install --save-dev @types/office-js-preview. 今後予定されている API の詳細については、「Excel JavaScript API 要件セット」参照してください。For more information on our upcoming APIs, please visit Excel JavaScript API requirement sets.

RangeAreasRangeAreas

範囲の集合 (連続している可能性もあります) は、 rangeareasオブジェクトによって表されます。A set of (possibly discontiguous) ranges is represented by a RangeAreas object. Range 型と同様のプロパティとメソッドを持ちますが (多くの場合は同じまたは類似した名前)、以下に対しては調整が行われています。It has properties and methods similar to the Range type (many with the same, or similar, names), but adjustments have been made to:

  • プロパティのデータ型と、セッターとゲッターの動作。The data types for properties and the behavior of the setters and getters.
  • メソッド パラメーターのデータ型と、メソッドの動作。The data types of method parameters and the method behaviors.
  • メソッドの戻り値のデータ型。The data types of method return values.

次にいくつか例を示します。Some examples:

  • RangeAreas には address プロパティがあり、Range.address プロパティのように 1 つのアドレスを返すのではなく、複数の範囲のアドレスをコンマで区切った文字列を返します。RangeAreas has an address property that returns a comma-delimited string of range addresses, instead of just one address as with the Range.address property.
  • RangeAreas には、一貫性がある場合、RangeAreas に指定された全範囲のデータ検証を表す DataValidation オブジェクトを返す dataValidation プロパティがあります。RangeAreas has a dataValidation property that returns a DataValidation object that represents the data validation of all the ranges in the RangeAreas, if it is consistent. RangeAreas に指定された全範囲に同じ DataValidation オブジェクトが適用されていない場合、このプロパティは null となります。The property is null if identical DataValidation objects are not applied to all the all the ranges in the RangeAreas. これは、RangeAreas オブジェクトに関する、汎用的ではありませんが一般的な原則です: RangeAreas に指定された全範囲のプロパティの値に一貫性がない場合、null となりますThis is a general, but not universal, principle with the RangeAreas object: If a property does not have consistent values on all the all the ranges in the RangeAreas, then it is null. より詳しい情報といくつかの例外については、「RangeAreas のプロパティの読み取り」を参照してください。See Read properties of RangeAreas for more information and some exceptions.
  • RangeAreas.cellCount は、RangeAreas に指定された全範囲の合計セル数を取得します。RangeAreas.cellCount gets the total number of cells in all the ranges in the RangeAreas.
  • RangeAreas.calculate は、RangeAreas に指定された全範囲のセルを再計算します。RangeAreas.calculate recalculates the cells of all the ranges in the RangeAreas.
  • RangeAreas.getEntireColumnRangeAreas.getEntireRow は、RangeAreas に指定された全範囲のセルの列 (または行) すべてを表す、別の RangeAreas オブジェクトを返します。RangeAreas.getEntireColumn and RangeAreas.getEntireRow return another RangeAreas object that represents all of the columns (or rows) in all the ranges in the RangeAreas. たとえば、RangeAreas が "A1:C4" と "F14:L15" を表す場合、RangeAreas.getEntireColumn は "A:C" と "F:L" を表す RangeAreas オブジェクトを返します。For example, if the RangeAreas represents "A1:C4" and "F14:L15", then RangeAreas.getEntireColumn returns a RangeAreas object that represents "A:C" and "F:L".
  • RangeAreas.copyFrom は、コピー操作のコピー元範囲を表す Range または RangeAreas パラメーターのいずれかを取得できます。RangeAreas.copyFrom can take either a Range or a RangeAreas parameter representing the source range(s) of the copy operation.

RangeAreas でも利用可能な Range メンバーの全リストComplete list of Range members that are also available on RangeAreas

プロパティProperties

リストにあるプロパティを読み取るコードを書く前に、「RangeAreas のプロパティの読み取り」の内容を理解しておいてください。Be familiar with Read properties of RangeAreas before you write code that reads any properties listed. 繰り返される内容について細かい注意点があります。There are subtleties to what gets returned.

  • addressaddress
  • addressLocaladdressLocal
  • cellCountcellCount
  • conditionalFormatsconditionalFormats
  • contextcontext
  • dataValidationdataValidation
  • formatformat
  • isEntireColumnisEntireColumn
  • isEntireRowisEntireRow
  • stylestyle
  • worksheetworksheet
メソッドMethods

プレビュー段階の Range メソッドについてはマークが付いています。Range methods in preview are marked.

  • calculate()calculate()
  • clear()clear()
  • convertDataTypeToText() (プレビュー)convertDataTypeToText() (preview)
  • convertToLinkedDataType() (プレビュー)convertToLinkedDataType() (preview)
  • copyFrom() (プレビュー)copyFrom() (preview)
  • getEntireColumn()getEntireColumn()
  • getEntireRow()getEntireRow()
  • getIntersection()getIntersection()
  • getIntersectionOrNullObject()getIntersectionOrNullObject()
  • getOffsetRange() (RangeAreas オブジェクトでの名前は getOffsetRangeAreas)getOffsetRange() (named getOffsetRangeAreas on the RangeAreas object)
  • getSpecialCells() (プレビュー)getSpecialCells() (preview)
  • getSpecialCellsOrNullObject() (プレビュー)getSpecialCellsOrNullObject() (preview)
  • getTables() (プレビュー)getTables() (preview)
  • getUsedRange() (RangeAreas オブジェクトでの名前は getUsedRangeAreas)getUsedRange() (named getUsedRangeAreas on the RangeAreas object)
  • getUsedRangeOrNullObject() (RangeAreas オブジェクトでの名前は getUsedRangeAreasOrNullObject)getUsedRangeOrNullObject() (named getUsedRangeAreasOrNullObject on the RangeAreas object)
  • load()load()
  • set()set()
  • setDirty() (プレビュー)setDirty() (preview)
  • toJSON()toJSON()
  • track()track()
  • untrack()untrack()

RangeArea 固有のプロパティとメソッドRangeArea-specific properties and methods

RangeAreas 型には、Range オブジェクトには存在しないプロパティとメソッドがいくつかあります。The RangeAreas type has some properties and methods that are not on the Range object. 次にいくつか選択したものを示します。The following is a selection of them:

  • areas: RangeAreas オブジェクトが表す全範囲を含む RangeCollection オブジェクト。areas: A RangeCollection object that contains all of the ranges represented by the RangeAreas object. RangeCollection オブジェクトも新しいオブジェクトであり、他の Excel コレクション オブジェクトと類似しています。The RangeCollection object is also new and is similar to other Excel collection objects. これには、範囲を表す Range オブジェクトの配列である items プロパティがあります。It has an items property which is an array of Range objects representing the ranges.
  • areaCount: RangeAreas で指定された範囲の合計数。areaCount: The total number of ranges in the RangeAreas.
  • getOffsetRangeAreas: Range.getOffsetRange と同じように動作します。ただし、RangeAreas を返し、元の RangeAreas で指定された範囲の 1 つからの各オフセットである範囲を含みます。getOffsetRangeAreas: Works just like Range.getOffsetRange, except that a RangeAreas is returned and it contains ranges that are each offset from one of the ranges in the original RangeAreas.

RangeAreas の作成Create RangeAreas

RangeAreas オブジェクトの作成には、2 つの基本的な方法があります。You can create RangeAreas object in two basic ways:

  • Worksheet.getRanges() を呼び出して、範囲のアドレスがコンマで区切られた文字列を渡します。Call Worksheet.getRanges() and pass it a string with comma-delimited range addresses. 含める対象の範囲が既に NamedItem に指定されている場合、文字列にはアドレスではなくその名前を指定することができます。If any range you want to include has been made into a NamedItem, you can include the name, instead of the address, in the string.
  • Workbook.getSelectedRanges() を呼び出します。Call Workbook.getSelectedRanges(). このメソッドは、現在アクティブなワークシート上で選択されている全範囲を表す RangeAreas を返します。This method returns a RangeAreas representing all the ranges that are selected on the currently active worksheet.

一度 RangeAreas オブジェクトを作成すると、getOffsetRangeAreasgetIntersection など、RangeAreas を返すオブジェクト上のメソッドを使用して別のオブジェクトを作成できます。Once you have a RangeAreas object, you can create others using the methods on the object that return RangeAreas such as getOffsetRangeAreas and getIntersection.

注意

RangeAreas オブジェクトに新たな範囲を直接追加することはできません。You cannot directly add additional ranges to a RangeAreas object. たとえば、RangeAreas.areas 内のコレクションには add メソッドが存在しません。For example, the collection in RangeAreas.areas does not have an add method.

警告

RangeAreas.areas.items 配列のメンバーの追加または削除を直接試行してはいけません。Do not attempt to directly add or delete members of the the RangeAreas.areas.items array. これにより、後でコード内で望ましくない動作が発生します。This will lead to undesirable behavior in your code. たとえば、追加の Range オブジェクトを配列にプッシュすることは可能ですが、エラーが発生します。RangeAreas のプロパティとメソッドは、その新しいアイテムがその場所に存在していないかのように動作するためです。For example, it is possible to push an additional Range object onto the array, but doing so will cause errors because RangeAreas properties and methods behave as if the new item isn't there. たとえば、areaCount プロパティにはこの方法でプッシュされた範囲は含まれません。また、RangeAreas.getItemAt(index) は、indexareasCount-1より大きい場合、エラーをスローします。For example, the areaCount property does not include ranges pushed in this way, and the RangeAreas.getItemAt(index) throws an error if index is larger than areasCount-1. 同様に、RangeAreas.areas.items 配列内の Range オブジェクトを、参照を取得してその Range.delete メソッドを呼び出すという方法で削除すると、バグとなります。Range オブジェクトは削除されますが、親 RangeAreas オブジェクトのプロパティとメソッドは、そのオブジェクトがまだ存在するものとして動作するためです。Similarly, deleting a Range object in the RangeAreas.areas.items array by getting a reference to it and calling its Range.delete method causes bugs: although the Range object is deleted, the properties and methods of the parent RangeAreas object behave, or try to, as if it is still in existence. たとえば、コードで RangeAreas.calculate を呼び出すと、Office は範囲を計算しようとしますが、範囲オブジェクトが既に存在しないためにエラーとなります。For example, if your code calls RangeAreas.calculate, Office will try to calculate the range, but will error because the range object is gone.

複数の範囲でのプロパティの設定Set properties on multiple ranges

RangeAreas オブジェクトでプロパティを設定すると、RangeAreas.areas コレクション内の全範囲の対応するプロパティが設定されます。Setting a property on a RangeAreas object sets the corresponding property on all the ranges in the RangeAreas.areas collection.

次に、複数の範囲にプロパティを設定する例を示します。The following is an example of setting a property on multiple ranges. この関数は、F3:F5H3:H5 の範囲を強調表示します。The function highlights the ranges F3:F5 and H3:H5.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();
    var rangeAreas = sheet.getRanges("F3:F5, H3:H5");
    rangeAreas.format.fill.color = "pink";

    return context.sync();
})

この例は、getRanges に渡す範囲のアドレスをハード コーディングできる場合や実行時に簡単に計算できる場合に適用されます。This example applies to scenarios in which you can hard code the range addresses that you pass to getRanges or easily calculate them at runtime. たとえば、これが適切なのは次のような場合です。Some of the scenarios in which this would be true include:

  • コードが、既知のテンプレートのコンテキスト内で実行される。The code runs in the context of a known template.
  • コードが、データのスキーマが既知であるインポート済みデータのコンテキスト内で実行される。The code runs in the context of imported data where the schema of the data is known.

複数の範囲からの特定のセルの取得Get special cells from multiple ranges

RangeAreas オブジェクトの getSpecialCells メソッドと getSpecialCellsOrNullObject メソッドは、Range オブジェクトの同じ名前のメソッドと同じように機能します。The getSpecialCells and getSpecialCellsOrNullObject methods on the RangeAreas object work analogously to methods of the same name on the Range object. これらのメソッドでは、RangeAreas.areas コレクション内のすべての範囲から、指定された特性を持つセルが返されます。These methods return the cells with the specified characteristic from all of the ranges in the RangeAreas.areas collection. 特殊なセルの詳細については、「範囲内の特殊なセルの検索」のセクションを参照してください。See the Find special cells within a range section for more details on special cells.

RangeAreas オブジェクトで getSpecialCells メソッドまたは getSpecialCellsOrNullObject メソッドを呼び出す場合:When calling the getSpecialCells or getSpecialCellsOrNullObject method on a RangeAreas object:

  • 最初のパラメーターとして Excel.SpecialCellType.sameConditionalFormat を渡した場合、このメソッドでは、RangeAreas.areas コレクション内の最初の範囲の左上隅のセルと同じ条件付き書式を持つセルがすべて返されます。If you pass Excel.SpecialCellType.sameConditionalFormat as the first parameter, the method returns all cells with the same conditional formatting as the upper-leftmost cell in the first range in the RangeAreas.areas collection.
  • 最初のパラメーターとして Excel.SpecialCellType.sameDataValidation を渡した場合、このメソッドでは、RangeAreas.areas コレクション内の最初の範囲の左上隅のセルと同じデータ検証ルールを持つセルがすべて返されます。If you pass Excel.SpecialCellType.sameDataValidation as the first parameter, the method returns all cells with the same data validation rule as the upper-leftmost cell in the first range in the RangeAreas.areas collection.

RangeAreas のプロパティの読み取りRead properties of RangeAreas

RangeAreas のプロパティ値の読み取りには、注意が必要です。RangeAreas内の範囲それぞれで、プロパティの値が異なる可能性があるためです。Reading property values of RangeAreas requires care, because a given property may have different values for different ranges within the RangeAreas. 一貫性のある値を返すことができる場合には返す、というのが一般的なルールです。The general rule is that if a consistent value can be returned it will be returned. たとえば、次のコードでは、ピンクの RGB コード (#FFC0CB) と true がコンソールに記録されます。RangeAreasオブジェクト内の範囲のどちらも、塗りつぶし色がピンクであり、列全体であるためです。For example, in the following code, The RGB code for pink (#FFC0CB) and true will be logged to the console because both the ranges in the RangeAreas object have a pink fill and both are entire columns.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();

    // The ranges are the F column and the H column.
    var rangeAreas = sheet.getRanges("F:F, H:H");  
    rangeAreas.format.fill.color = "pink";

    rangeAreas.load("format/fill/color, isEntireColumn");

    return context.sync()
        .then(function () {
            console.log(rangeAreas.format.fill.color); // #FFC0CB
            console.log(rangeAreas.isEntireColumn); // true
        })
        .then(context.sync);
})

一貫性を期待できない場合、事態は複雑となります。Things get more complicated when consistency isn't possible. RangeAreas プロパティの動作は、次の 3 つの原則に従います。The behavior of RangeAreas properties follows these three principles:

  • RangeAreas オブジェクトのブール値プロパティは、すべてのメンバー範囲でプロパティが true でない限り、false を返します。A boolean property of a RangeAreas object returns false unless the property is true for all the member ranges.
  • ブール値以外のプロパティ (address プロパティを除く) は、すべてのメンバー範囲で対応するプロパティが同じ値ではない限り、null を返します。Non-boolean properties, with the exception of the address property, return null unless the corresponding property on all the member ranges has the same value.
  • address プロパティは、メンバー範囲のアドレスをコンマで区切った文字列を返します。The address property returns a comma-delimited string of the addresses of the member ranges.

たとえば、次のコードでは、1 つの範囲のみが列全体であり、1 つの範囲のみがピンクで塗りつぶされている RangeAreas を作成します。For example, the following code creates a RangeAreas in which only one range is an entire column and only one is filled with pink. コンソールには、塗りつぶし色の場合は nullisEntireRow プロパティの場合は falseaddress プロパティの場合は "Sheet1!F3:F5, Sheet1!H:H" ("Sheet1" はシート名) が表示されます。The console will show null for the fill color, false for the isEntireRow property, and "Sheet1!F3:F5, Sheet1!H:H" (assuming the sheet name is "Sheet1") for the address property.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();
    var rangeAreas = sheet.getRanges("F3:F5, H:H");

    var pinkColumnRange = sheet.getRange("H:H");
    pinkColumnRange.format.fill.color = "pink";

    rangeAreas.load("format/fill/color, isEntireColumn, address");

    return context.sync()
        .then(function () {
            console.log(rangeAreas.format.fill.color); // null
            console.log(rangeAreas.isEntireColumn); // false
            console.log(rangeAreas.address); // "Sheet1!F3:F5, Sheet1!H:H"
        })
        .then(context.sync);
})

関連項目See also