Excel アドインで複数の範囲を同時に操作する

連続していない場合でも、複数の範囲に対して操作を適用したり、プロパティを一度に設定したりできます。 これにより、各範囲に個別にアクセスする場合と比較して、コードが短く効率的になります。

重要な点

• RangeAreasを使用して、1 回の呼び出しで複数の個別の範囲で同じことを読み取ったり設定したりします。
• プロパティは、すべてのメンバー範囲が同じ値を共有しない限り、 null されます。
• 各範囲に異なるロジックが必要な場合を除き、ループではなく、 RangeAreas オブジェクトにプロパティを 1 回設定します。
• 多数の単一セルで構成された大きな RangeAreas オブジェクトは避けてください。 getSpecialCellsやその他のフィルターを使用して最初に狭くします。
• 列全体または行全体に注意してください。 詳細については、「 無制限の範囲への読み取りまたは書き込み」を参照してください。

RangeAreas

RangeAreas オブジェクトは、タッチできない範囲のセットを表します。 多くのメンバーを Rangeと共有し、値の返し方にいくつかの違いがあります。

例:

• address は、すべてのアドレスのコンマ区切り文字列を 1 つ返します。
• dataValidation は、すべての範囲に同じ規則がある場合にのみ 1 つのオブジェクトを返し、それ以外の場合は nullを返します。
• cellCount は、すべての範囲のセルの合計です。
• calculate では、セット内のすべてのセルが再計算されます。
• getEntireColumn getEntireRowは、各メンバーの列または行全体にわたる新しいRangeAreasを返します。
• copyFrom は、ソースとして Range または RangeAreas を受け入れます。

RangeAreas でも利用可能な Range メンバーの全リスト

プロパティ

リストにあるプロパティを読み取るコードを書く前に、「RangeAreas のプロパティの読み取り」の内容を理解しておいてください。 繰り返される内容について細かい注意点があります。

• address
• addressLocal
• cellCount
• conditionalFormats
• context
• dataValidation
• format
• isEntireColumn
• isEntireRow
• style
• worksheet

メソッド

• calculate()
• clear()
• convertDataTypeToText()
• convertToLinkedDataType()
• copyFrom()
• getEntireColumn()
• getEntireRow()
• getIntersection()
• getIntersectionOrNullObject()
• getOffsetRange()(RangeAreas オブジェクトの getOffsetRangeAreas という名前)
• getSpecialCells()
• getSpecialCellsOrNullObject()
• getTables()
• getUsedRange()(RangeAreas オブジェクトの getUsedRangeAreas という名前)
• getUsedRangeOrNullObject()(RangeAreas オブジェクトの getUsedRangeAreasOrNullObject という名前)
• load()
• set()
• setDirty()
• toJSON()
• track()
• untrack()

RangeArea 固有のプロパティとメソッド

RangeAreas 型には、Range オブジェクトには存在しないプロパティとメソッドがいくつかあります。 それらの選択内容を次に示します。

• areas: RangeAreas オブジェクトが表す全範囲を含む RangeCollection オブジェクト。 RangeCollection オブジェクトも新しいオブジェクトであり、他の Excel コレクション オブジェクトと類似しています。 これには、範囲を表す Range オブジェクトの配列である items プロパティがあります。
• areaCount: RangeAreas で指定された範囲の合計数。
• getOffsetRangeAreas: Range.getOffsetRange と同じように動作します。ただし、RangeAreas を返し、元の RangeAreas で指定された範囲の 1 つからの各オフセットである範囲を含みます。

RangeAreas の作成

RangeAreas オブジェクトは複数の方法で作成できます。 次の一覧には、いくつかの例が含まれています。

• Worksheet.getRanges() を呼び出して、範囲のアドレスがコンマで区切られた文字列を渡します。 含める対象の範囲が既に NamedItem に指定されている場合、文字列にはアドレスではなくその名前を指定することができます。
• Range.getSpecialCells()を呼び出し、数式、データ検証、条件付き書式を含むセルなど、特定の型のセルを持つRangeAreas オブジェクトを返します。
• Workbook.getSelectedRanges() を呼び出します。 このメソッドは、現在アクティブなワークシート上で選択されている全範囲を表す RangeAreas を返します。

一度 RangeAreas オブジェクトを作成すると、getOffsetRangeAreas や getIntersection など、RangeAreas を返すオブジェクト上のメソッドを使用して別のオブジェクトを作成できます。

複数の範囲でのプロパティの設定

RangeAreas オブジェクトでプロパティを設定すると、RangeAreas.areas コレクション内の全範囲の対応するプロパティが設定されます。

次に、複数の範囲にプロパティを設定する例を示します。 この関数は、F3:F5 と H3:H5 の範囲を強調表示します。

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

    await context.sync();
});

この例は、getRanges に渡す範囲のアドレスをハード コーディングできる場合や実行時に簡単に計算できる場合に適用されます。 たとえば、これが適切なのは次のような場合です。

• コードが、既知のテンプレートのコンテキスト内で実行される。
• コードが、データのスキーマが既知であるインポート済みデータのコンテキスト内で実行される。

RangeAreasと組み合わせるgetSpecialCells

書式設定や検証を適用する前に、条件 (数式など) に一致するセルのみに RangeAreas をフィルター処理します。

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // Two discontiguous vertical bands.
    const targets = sheet.getRanges("A1:A100, C1:C100");

    // Narrow to only the formula cells within those bands.
    const formulaCells = targets.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaCells.format.fill.color = "lightYellow";
    await context.sync();
});

複数の範囲からの特定のセルの取得

RangeAreas オブジェクトの getSpecialCells メソッドと getSpecialCellsOrNullObject メソッドは、Range オブジェクトの同じ名前のメソッドと同じように機能します。 これらのメソッドでは、RangeAreas.areas コレクション内のすべての範囲から、指定された特性を持つセルが返されます。 特殊セルの詳細については、「範囲内の 特殊なセルを検索する」を参照してください。

RangeAreas オブジェクトで getSpecialCells メソッドまたは getSpecialCellsOrNullObject メソッドを呼び出す場合:

• 最初のパラメーターとして Excel.SpecialCellType.sameConditionalFormat を渡した場合、このメソッドでは、RangeAreas.areas コレクション内の最初の範囲の左上隅のセルと同じ条件付き書式を持つセルがすべて返されます。
• 最初のパラメーターとして Excel.SpecialCellType.sameDataValidation を渡した場合、このメソッドでは、RangeAreas.areas コレクション内の最初の範囲の左上隅のセルと同じデータ検証ルールを持つセルがすべて返されます。

RangeAreas のプロパティの読み取り

RangeAreas のプロパティ値の読み取りには、注意が必要です。RangeAreas内の範囲それぞれで、プロパティの値が異なる可能性があるためです。 一貫性のある値を返すことができる場合には返す、というのが一般的なルールです。 たとえば、次のコードでは、ピンク (#FFC0CB) と true の RGB コードは、 RangeAreas オブジェクトの範囲の両方がピンク色の塗りつぶしを持ち、両方が列全体であるため、コンソールに記録されます。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();

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

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

    console.log(rangeAreas.format.fill.color); // #FFC0CB
    console.log(rangeAreas.isEntireColumn); // true
});

プロパティ値は異なる場合があるため、これらの単純なルールに注意してください。

• ブール型プロパティは、すべての範囲で true の場合にのみ true され、それ以外の場合は false。
• address は常にコンマ区切りアドレス文字列を返します。
• 他のプロパティは、すべての範囲が同じ値を共有しない限り、 null されます。

たとえば、次のコードでは、1 つの範囲のみが列全体であり、1 つの範囲のみがピンクで塗りつぶされている RangeAreas を作成します。 コンソールには、塗りつぶし色の場合は null、isEntireRow プロパティの場合は false、address プロパティの場合は "Sheet1!F3:F5, Sheet1!H:H" ("Sheet1" はシート名) が表示されます。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let rangeAreas = sheet.getRanges("F3:F5, H:H");

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

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

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

関連項目

• Excel JavaScript API を使用した基本的なプログラミングの概念
• Excel JavaScript API を使用して広い範囲の読み取りまたは書き込みを行う
• Excel JavaScript API を使用して、無制限の範囲に対する読み取りまたは書き込みを行う