Excel JavaScript API を使用して範囲を操作するWork with ranges using the Excel JavaScript API

この記事では、Excel JavaScript API を使用して、範囲に関する一般的なタスクを実行する方法を示すサンプル コードを提供します。 Range オブジェクトがサポートするプロパティとメソッドの完全な一覧については、「Range オブジェクト (JavaScript API for Excel)」を参照してください。This article provides code samples that show how to perform common tasks with ranges using the Excel JavaScript API. For the complete list of properties and methods that the Range object supports, see Range Object (JavaScript API for Excel).

注意

範囲を指定してより詳細なタスクを実行する方法のサンプル コードについては、「Excel JavaScript API を使用して範囲を操作する (詳細)」を参照してください。For code samples that show how to perform more advanced tasks with ranges, see Work with ranges using the Excel JavaScript API (advanced).

範囲を取得するGet a range

次の例では、ワークシート内の範囲への参照を取得する、さまざまな方法を示しています。The following examples show different ways to get a reference to a range within a worksheet.

アドレスによって範囲を取得するGet range by address

次のコード サンプルでは、Sample という名前のワークシートからアドレス B2:B5 の範囲を取得し、address プロパティを読み込んで、コンソールにメッセージを書き込みます。The following code sample gets the range with address B2:B5 from the worksheet named Sample, loads its address property, and writes a message to the console.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("B2:C5");
    range.load("address");

    return context.sync()
        .then(function () {
            console.log(`The address of the range B2:C5 is "${range.address}"`);
        });
}).catch(errorHandlerFunction);

名前によって範囲を取得するGet range by name

次のコード サンプルでは、Sample という名前のワークシートから MyRange という名前の範囲を取得し、address プロパティを読み込んで、コンソールにメッセージを書き込みます。The following code sample gets the range named MyRange from the worksheet named Sample, loads its address property, and writes a message to the console.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("MyRange");
    range.load("address");

    return context.sync()
        .then(function () {
            console.log(`The address of the range "MyRange" is "${range.address}"`);
        });
}).catch(errorHandlerFunction);

使用範囲を取得するGet used range

次のコード サンプルでは、Sample という名前のワークシートから使用範囲を取得し、address プロパティを読み込んで、コンソールにメッセージを書き込みます。 使用範囲とは、値または書式設定が割り当てられているワークシート内のセルを含む、最小の範囲です。 ワークシート全体が空白の場合、getUsedRange() メソッドは、ワークシートの左上のセルのみで構成される範囲を返します。The following code sample gets the used range from the worksheet named Sample, loads its address property, and writes a message to the console. The used range is the smallest range that encompasses any cells in the worksheet that have a value or formatting assigned to them. If the entire worksheet is blank, the getUsedRange() method returns a range that consists of only the top-left cell in the worksheet.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getUsedRange();
    range.load("address");

    return context.sync()
        .then(function () {
            console.log(`The address of the used range in the worksheet is "${range.address}"`);
        });
}).catch(errorHandlerFunction);

範囲全体を取得するGet entire range

次のコード サンプルでは、Sample という名前のワークシートからワークシートの範囲全体を取得し、address プロパティを読み込んで、コンソールにメッセージを書き込みます。The following code sample gets the entire worksheet range from the worksheet named Sample, loads its address property, and writes a message to the console.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange();
    range.load("address");

    return context.sync()
        .then(function () {
            console.log(`The address of the entire worksheet range is "${range.address}"`);
        });
}).catch(errorHandlerFunction);

セルの範囲を挿入するInsert a range of cells

次のコードサンプルは、場所 B4:E4 にセルの範囲を挿入し、他のセルを下にシフトして、新しいセルのためのスペースを提供します。The following code sample inserts a range of cells in location B4:E4 and shifts other cells down to provide space for the new cells.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("B4:E4");

    range.insert(Excel.InsertShiftDirection.down);
    
    return context.sync();
}).catch(errorHandlerFunction);

範囲を挿入する前のデータData before range is inserted

範囲を挿入する前の Excel のデータ

範囲を挿入した後のデータData after range is inserted

範囲を挿入した後の Excel のデータ

セルの範囲をクリアするClear a range of cells

次のコード サンプルは、範囲 E2:E5 のセルの内容と書式をすべてクリアします。The following code sample clears all contents and formatting of cells in the range E2:E5.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("E2:E5");

    range.clear();

    return context.sync();
}).catch(errorHandlerFunction);

範囲をクリアする前のデータData before range is cleared

範囲をクリアする前の Excel のデータ

範囲をクリアした後のデータData after range is cleared

範囲をクリアした後の Excel のデータ

セルの範囲を削除するDelete a range of cells

次のコード サンプルは、範囲 B4:E4 のセルを削除し、他のセルを上にシフトして、削除されたセルのために空いたスペースに入力します。The following code sample deletes the cells in the range B4:E4 and shift other cells up to fill the space that was vacated by the deleted cells.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("B4:E4");

    range.delete(Excel.DeleteShiftDirection.up);

    return context.sync();
}).catch(errorHandlerFunction);

範囲を削除する前のデータData before range is deleted

範囲を削除する前の Excel のデータ

範囲を削除した後のデータData after range is deleted

範囲を削除した後の Excel のデータ

選択範囲を設定するSet the selected range

次のコード サンプルは、作業中のワークシートの範囲 B2:E6 を選択します。The following code sample selects the range B2:E6 in the active worksheet.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getActiveWorksheet();
    var range = sheet.getRange("B2:E6");

    range.select();

    return context.sync();
}).catch(errorHandlerFunction);

選択範囲 B2:E6Selected range B2:E6

Excel の選択範囲

選択範囲を取得するGet the selected range

次のコード サンプルでは、選択範囲を取得し、address プロパティを読み込んで、コンソールにメッセージを書き込みます。The following code sample gets the selected range, loads its address property, and writes a message to the console.

Excel.run(function (context) {
    var range = context.workbook.getSelectedRange();
    range.load("address");

    return context.sync()
        .then(function () {
            console.log(`The address of the selected range is "${range.address}"`);
        });
}).catch(errorHandlerFunction);

値または数式を設定するSet values or formulas

次の例は、1 つのセルまたはセルの範囲の値と数式を設定する方法を示しています。The following examples show how to set values and formulas for a single cell or a range of cells.

1 つのセルの値を設定するSet value for a single cell

次のコード サンプルでは、セル C3 の値を "5" に設定し、データに最も適した列の幅を設定します。The following code sample sets the value of cell C3 to "5" and then sets the width of the columns to best fit the data.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var range = sheet.getRange("C3");
    range.values = [[ 5 ]];
    range.format.autofitColumns();

    return context.sync();
}).catch(errorHandlerFunction);

セルの値が更新される前のデータData before cell value is updated

セルの値が更新される前の Excel のデータ

セルの値が更新された後のデータData after cell value is updated

セルの値が更新された後の Excel のデータ

複数のセルの範囲の値を設定するSet values for a range of cells

次のコード サンプルでは、範囲 B5:D5 のセルの値を設定し、データに最も適した列の幅を設定します。The following code sample sets values for the cells in the range B5:D5 and then sets the width of the columns to best fit the data.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var data = [
        ["Potato Chips", 10, 1.80],
    ];
    
    var range = sheet.getRange("B5:D5");
    range.values = data;
    range.format.autofitColumns();

    return context.sync();
}).catch(errorHandlerFunction);

複数のセルの値が更新される前のデータData before cell values are updated

複数のセルの値が更新される前の Excel のデータ

複数のセルの値が更新された後のデータData after cell values are updated

複数のセルの値が更新された後の Excel のデータ

1 つのセルの数式を設定するSet formula for a single cell

次のコード サンプルでは、セル E3 の数式を設定し、データに最も適した列の幅を設定します。The following code sample sets a formula for cell E3 and then sets the width of the columns to best fit the data.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var range = sheet.getRange("E3");
    range.formulas = [[ "=C3 * D3" ]];
    range.format.autofitColumns();

    return context.sync();
}).catch(errorHandlerFunction);

セルの数式が設定される前のデータData before cell formula is set

セルの数式が設定される前の Excel のデータ

セルの数式が設定された後のデータData after cell formula is set

セルの数式が設定された後の Excel のデータ

セルの範囲の数式を設定するSet formulas for a range of cells

次のコード サンプルでは、範囲 E2:E6 のセルの数式を設定し、データに最も適した列の幅を設定します。The following code sample sets formulas for cells in the range E2:E6 and then sets the width of the columns to best fit the data.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var data = [
        ["=C3 * D3"],
        ["=C4 * D4"],
        ["=C5 * D5"],
        ["=SUM(E3:E5)"]
    ];
    
    var range = sheet.getRange("E3:E6");
    range.formulas = data;
    range.format.autofitColumns();

    return context.sync();
}).catch(errorHandlerFunction);

複数のセルの数式が設定される前のデータData before cell formulas are set

複数のセルの数式が設定される前の Excel のデータ

複数のセルの数式が設定された後のデータData after cell formulas are set

複数のセルの数式が設定された後の Excel のデータ

値、テキスト、または数式を取得するGet values, text, or formulas

次の例は、セルの範囲から値、テキスト、および数式を取得する方法を示しています。These examples show how to get values, text, and formulas from a range of cells.

セルの範囲から値を取得するGet values from a range of cells

次のコード サンプルでは、範囲 B2:E6 を取得し、values プロパティを読み込んで、コンソールに値を書き込みます。 範囲の values プロパティは、セルに含まれる未処理の値を指定します。 範囲内の一部のセルに数式が含まれている場合でも、範囲の values プロパティは、それらのセルの未処理の値 (数式ではなく) を指定します。The following code sample gets the range B2:E6, loads its values property, and writes the values to the console. The values property of a range specifies the raw values that the cells contain. Even if some cells in a range contain formulas, the values property of the range specifies the raw values for those cells, not any of the formulas.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("B2:E6");
    range.load("values");

    return context.sync()
        .then(function () {
            console.log(JSON.stringify(range.values, null, 4));
        });
}).catch(errorHandlerFunction);

範囲内のデータ (列 E の値は数式の結果)Data in range (values in column E are a result of formulas)

複数のセルの数式が設定された後の Excel のデータ

range.values (上記のコード サンプルによりコンソールに記録される)range.values (as logged to the console by the code sample above)

[
    [
        "Product",
        "Qty",
        "Unit Price",
        "Total Price"
    ],
    [
        "Almonds",
        2,
        7.5,
        15
    ],
    [
        "Coffee",
        1,
        34.5,
        34.5
    ],
    [
        "Chocolate",
        5,
        9.56,
        47.8
    ],
    [
        "",
        "",
        "",
        97.3
    ]
]

セルの範囲からテキストを取得するGet text from a range of cells

次のコード サンプルでは、範囲 B2:E6 を取得し、text プロパティを読み込んでコンソールに書き込みます。 範囲の text プロパティは、範囲内のセルの表示値を指定します。 範囲内の一部のセルに数式が含まれている場合でも、範囲の text プロパティは、それらのセルの表示値 (数式ではなく) を指定します。The following code sample gets the range B2:E6, loads its text property, and writes it to the console. The text property of a range specifies the display values for cells in the range. Even if some cells in a range contain formulas, the text property of the range specifies the display values for those cells, not any of the formulas.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("B2:E6");
    range.load("text");

    return context.sync()
        .then(function () {
            console.log(JSON.stringify(range.text, null, 4));
        });
}).catch(errorHandlerFunction);

範囲内のデータ (列 E の値は数式の結果)Data in range (values in column E are a result of formulas)

複数のセルの数式が設定された後の Excel のデータ

range.text (上記のコード サンプルによりコンソールに記録される)range.text (as logged to the console by the code sample above)

[
    [
        "Product",
        "Qty",
        "Unit Price",
        "Total Price"
    ],
    [
        "Almonds",
        "2",
        "7.5",
        "15"
    ],
    [
        "Coffee",
        "1",
        "34.5",
        "34.5"
    ],
    [
        "Chocolate",
        "5",
        "9.56",
        "47.8"
    ],
    [
        "",
        "",
        "",
        "97.3"
    ]
]

セルの範囲から数式を取得するGet formulas from a range of cells

次のコード サンプルでは、範囲 B2:E6 を取得し、formulas プロパティを読み込んでコンソールに書き込みます。 範囲の formulas プロパティは、数式と数式を含まない範囲のセルの未処理の値が含まれる、範囲内のセルの数式を指定します。The following code sample gets the range B2:E6, loads its formulas property, and writes it to the console. The formulas property of a range specifies the formulas for cells in the range that contain formulas and the raw values for cells in the range that do not contain formulas.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var range = sheet.getRange("B2:E6");
    range.load("formulas");

    return context.sync()
        .then(function () {
            console.log(JSON.stringify(range.formulas, null, 4));
        });
}).catch(errorHandlerFunction);

範囲内のデータ (列 E の値は数式の結果)Data in range (values in column E are a result of formulas)

複数のセルの数式が設定された後の Excel のデータ

range.formulas (上記のコード サンプルによりコンソールに記録される)range.formulas (as logged to the console by the code sample above)

[
    [
        "Product",
        "Qty",
        "Unit Price",
        "Total Price"
    ],
    [
        "Almonds",
        2,
        7.5,
        "=C3 * D3"
    ],
    [
        "Coffee",
        1,
        34.5,
        "=C4 * D4"
    ],
    [
        "Chocolate",
        5,
        9.56,
        "=C5 * D5"
    ],
    [
        "",
        "",
        "",
        "=SUM(E3:E5)"
    ]
]

範囲の書式を設定するSet range format

次の例は、範囲内のセルのフォントの色、塗りつぶしの色、および数値の書式を設定する方法を示しています。The following examples show how to set font color, fill color, and number format for cells in a range.

フォントの色と塗りつぶしの色を設定するSet font color and fill color

次のコード サンプルは、範囲 B2:E2 のセルのフォントの色と塗りつぶしの色を設定します。The following code sample sets the font color and fill color for cells in range B2:E2.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var range = sheet.getRange("B2:E2");
    range.format.fill.color = "#4472C4";;
    range.format.font.color = "white";

    return context.sync();
}).catch(errorHandlerFunction);

フォントの色と塗りつぶしの色を設定する前の範囲内のデータData in range before font color and fill color are set

書式設定する前の Excel のデータ

フォントの色と塗りつぶしの色を設定した後の範囲内のデータData in range after font color and fill color are set

書式設定した後の Excel のデータ

数値の書式を設定するSet number format

次のコード サンプルは、範囲 D3:E5 のセルの数値を書式を設定します。The following code sample sets the number format for the cells in range D3:E5.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var formats = [
        ["0.00", "0.00"],
        ["0.00", "0.00"],
        ["0.00", "0.00"]
    ];

    var range = sheet.getRange("D3:E5");
    range.numberFormat = formats;

    return context.sync();
}).catch(errorHandlerFunction);

数値の書式を設定する前の範囲内のデータData in range before number format is set

書式設定する前の Excel のデータ

数値の書式を設定した後の範囲内のデータData in range after number format is set

書式設定した後の Excel のデータ

範囲の条件付き書式Conditional formatting of ranges

範囲には、条件に基づいて個々のセルに適用する書式設定を含めることができます。Ranges can have formats applied to individual cells based on conditions. この詳細については、「Excel の範囲に条件付き書式を適用する」を参照してください。For more information about this, see Apply conditional formatting to Excel ranges.

文字列のマッチングを使用してセルを検索する (プレビュー)Find a cell using string matching (preview)

注意

現在、Range オブジェクトの find 関数は、パブリック プレビューでのみ利用できます。The Range object's find function is currently available only in public preview. この機能を使用するには、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.

Range オブジェクトには、範囲内で指定された文字列を検索するための find メソッドがあります。The Range object has a find method to search for a specified string within the range. このメソッドは、一致するテキストがある最初のセルの範囲を返します。It returns the range of the first cell with matching text. 次のコード サンプルは、文字列 Food と等しい値を持つ最初のセルを検索して、そのアドレスをコンソールに記録します。The following code sample finds the first cell with a value equal to the string Food and logs its address to the console. 指定した文字列が範囲に存在しない場合、ItemNotFound エラーが find によってスローされます。Note that find throws an ItemNotFound error if the specified string doesn't exist in the range. 指定した文字列が範囲に存在しない可能性がある場合は、自分のコードで適切にシナリオを処理できるように、findOrNullObject メソッドを使用するようにしてください。If you expect that the specified string may not exist in the range, use the findOrNullObject method instead, so your code gracefully handles that scenario.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var table = sheet.tables.getItem("ExpensesTable");
    var searchRange = table.getRange();
    var foundRange = searchRange.find("Food", {
        completeMatch: true, // find will match the whole cell value
        matchCase: false, // find will not match case
        searchDirection: Excel.SearchDirection.forward // find will start searching at the beginning of the range
    });

    foundRange.load("address");
    return context.sync()
        .then(function() {
            console.log(foundRange.address);
    });
}).catch(errorHandlerFunction);

単一のセルを表す範囲に対して find メソッドが呼び出されると、ワークシート全体が検索されます。When the find method is called on a range representing a single cell, the entire worksheet is searched. 検索はその単一のセルから始まり、SearchCriteria.searchDirection によって指定された方向へ行われ、場合によってはワークシートの最終部分で折り返されます。The search begins at that cell and goes in the direction specified by SearchCriteria.searchDirection, wrapping around the ends of the worksheet if needed.

関連項目See also