Excel JavaScript API を使用して範囲内の特殊なセルを検索する

Excel JavaScript API を使用して、数式、定数、エラー、またはその他の特性を持つセルをすばやく見つけ、書式設定を効率的に監査、リファクタリング、または適用できるようにします。 この記事では、 Range.getSpecialCells と Range.getSpecialCellsOrNullObjectを使用する方法、それぞれを選択するタイミング、セル値の型を使用して結果をさらに絞り込む方法について説明します。 Range オブジェクトがサポートするプロパティとメソッドの完全なセットについては、「Excel.Range クラス」を参照してください。

クイック リファレンス

特殊なセルを含む範囲を検索する

Range.getSpecialCells メソッドと Range.getSpecialCellsOrNullObject メソッドは、セルの特性とセルの値の種類に基づいて範囲を検索します。 これらのメソッドでは両方とも、RangeAreas オブジェクトが返されます。 次に示すのは、TypeScript データ型ファイルの、このメソッドのシグネチャです。

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

次のコード サンプルでは、 getSpecialCells を使用して、数式を含むすべてのセルを検索します。 ご注意ください:

• 検索スコープは、最初に worksheet.getUsedRange() を呼び出すことによってパフォーマンスを向上させるために制限されます。
• getSpecialCells は 1 つの RangeAreas オブジェクトを返します。そのため、連続しない一致を 1 回の操作で書式設定できます。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaRanges = usedRange.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaRanges.format.fill.color = "pink";

    await context.sync();
});

対象の特性を含むセルが範囲内に存在しない場合、getSpecialCells によって ItemNotFound エラーがスローされます。 この場合、制御のフローが catch ブロックに移ります (存在する場合)。 catch ブロックがない場合、エラーは メソッドを停止します。

対象の特性を含むセルが常に存在するはずである場合、そうしたセルが存在しないなら、コードを使ってエラーをスローする必要があるかもしれません。 一致するセルがないということが有効なシナリオでは、コードでこのような可能性があるかどうかを確認し、あれば、エラーをスローせずに適切に処理するようにしておく必要があります。 getSpecialCellsOrNullObject メソッドと、返された isNullObject プロパティを使用して、この動作を実現できます。 次のコード サンプルでは、このパターンを使用します。 このコードについては、以下の点に注意してください。

• getSpecialCellsOrNullObject メソッドは常にプロキシ オブジェクトを返すので、通常の JavaScript の意味ではnullされません。 ただし一致するセルが見つからなかった場合、オブジェクトの isNullObject プロパティは true に設定されます。
• isNullObject プロパティをテストする前に、context.syncを呼び出します。 これは、すべての *OrNullObject メソッドとプロパティの必要条件です。プロパティを読み取るためには常に、そのプロパティをロードして同期する必要があるためです。 ただし、isNullObject プロパティを明示的に読み込む必要はありません。 オブジェクトでloadが呼び出されていない場合でも、context.syncによって自動的に読み込まれます。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
• このコードをテストするには、最初に数式を含まないセルの範囲を選択してからコードを実行します。 次に、少なくとも 1 つのセルが数式を含む範囲を選択してからコードを再実行します。

await Excel.run(async (context) => {
    let range = context.workbook.getSelectedRange();
    let formulaRanges = range.getSpecialCellsOrNullObject(Excel.SpecialCellType.formulas);
    await context.sync();
        
    if (formulaRanges.isNullObject) {
        console.log("No cells have formulas");
    }
    else {
        formulaRanges.format.fill.color = "pink";
    }
    
    await context.sync();
});

わかりやすくするために、この記事の残りのサンプルでは getSpecialCellsを使用します。

セルの値の型に応じて対象のセルを絞り込む

Range.getSpecialCells() メソッドと Range.getSpecialCellsOrNullObject() メソッドでは、対象セルをさらに絞り込むためにオプションとして使用される 2 番目のパラメーターを承諾します。 この 2 番目のパラメーターは、特定の種類の値を含むセルのみを指定するために使用される Excel.SpecialCellValueType パラメーターです。

単一のセル値の型のテスト

Excel.SpecialCellValueType 列挙型には、次の 4 つの基本型があります (このセクションで後述する他の値の組み合わせに加えて)。

• Excel.SpecialCellValueType.errors
• Excel.SpecialCellValueType.logical (ブール値を意味します)
• Excel.SpecialCellValueType.numbers
• Excel.SpecialCellValueType.text

次のサンプルでは、数値定数を検索し、ピンク色に色を付けます。

重要なポイント:

• 対象となるのはリテラル数値定数のみです (数値に評価される数式、ブール値、テキスト、またはエラー セルではありません)。
• テストするには、リテラル番号の値、他の種類のリテラル値、および数式をシートに設定します。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let constantNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.constants,
        Excel.SpecialCellValueType.numbers);
    constantNumberRanges.format.fill.color = "pink";

    await context.sync();
});

複数のセル値の型のテスト

すべてのテキスト値とすべてのブール値 (Excel.SpecialCellValueType.logical) セルなど、複数のセル値型を操作する必要がある場合があります。 Excel.SpecialCellValueType 列挙型には、結合された型の値があります。 たとえば、 Excel.SpecialCellValueType.logicalText は、すべてのブール値セルとすべてのテキスト値セルを対象とします。 Excel.SpecialCellValueType.all は既定値であり、返されるセル値の型は制限されません。 次のコード サンプルでは、数値またはブール値を生成する数式ですべてのセルに色を付けます。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaLogicalNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.formulas,
        Excel.SpecialCellValueType.logicalNumbers);
    formulaLogicalNumberRanges.format.fill.color = "pink";

    await context.sync();
});

次の手順

• 特殊セル クエリと 文字列検索 を組み合わせて、より高度な監査を行います。
• 結果の RangeAreas オブジェクトに書式設定、コメント、またはデータ検証を適用します。

関連項目

• Office アドインの Excel JavaScript オブジェクト モデル
• Excel JavaScript API を使用してセルを操作する