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

この記事では、Excel の JavaScript API を使用して範囲の共通のタスクを実行する方法を示すコード サンプルを提供します。Range オブジェクトでサポートされているプロパティとメソッドの完全なリストについては、「Range オブジェクト (Excel の JavaScript API)」をご覧ください。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).

範囲を取得する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 のデータ

コピーと貼り付けCopy and Paste

注意

CopyFrom 関数は現在、パブリック プレビュー (ベータ版) でのみ使用可能です。この機能を使用するには、Office.js CDN のベータ版のライブラリを使用する必要があります: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js。TypeScript を使用している場合、またはコード エディターで IntelliSense 用の TypeScript 型定義ファイルを使用している場合は、https://appsforoffice.microsoft.com/lib/beta/hosted/office.d.ts を使用してください。The copyFrom function is currently available only in public preview (beta). To use this feature, you must use the beta library of the Office.js CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js. If you are using TypeScript or your code editor uses TypeScript type definition files for IntelliSense, use https://appsforoffice.microsoft.com/lib/beta/hosted/office.d.ts.

範囲の copyFrom 関数は、Excel の UI のコピーと貼り付けの動作と同じ動作をします。copyFrom が呼び出された範囲オブジェクトがコピー先です。コピー元のソースは、範囲、または範囲を表す文字列のアドレスとして渡されます。次のコード サンプルでは、A1:E1 からデータを G1 で始まる範囲にコピーします (これは G1:K1 への貼り付けとなります)。Range’s copyFrom function replicates the copy-and-paste behavior of the Excel UI. The range object that copyFrom is called on is the destination. The source to be copied is passed as a range or a string address representing a range. The following code sample copies the data from A1:E1 into the range starting at G1 (which ends up pasting into G1:K1).

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    // copy a range starting at a single cell destination
    sheet.getRange("G1").copyFrom("A1:E1");
    return context.sync();
}).catch(errorHandlerFunction);

Range.copyFrom には、次の 3 つの省略可能なパラメーターがあります。Range.copyFrom has three optional parameters.

copyFrom(sourceRange: Range | string, copyType?: "All" | "Formulas" | "Values" | "Formats", skipBlanks?: boolean, transpose?: boolean): void;

copyType はコピー元からコピー先へコピーするデータを指定します。“Formulas” はコピー元のセル内の数式を移動し、それらの数式の範囲の相対的な位置を保存します。数式でない内容はそのままコピーされます。“Values” はデータの値をコピーしますが、数式の場合は数式の結果をコピーします。“Formats” はフォント、色、その他の書式設定を含めた範囲の書式をコピーしますが、値はコピーしません。”All” (規定の選択肢) はデータと書式の両方をコピーし、セルに数式がある場合はそれを保存します。copyType specifies what data gets copied from the source to the destination. “Formulas” transfers the formulas in the source cells and preserves the relative positioning of those formulas’ ranges. Any non-formula entries are copied as-is. “Values” copies the data values and, in the case of formulas, the result of the formula. “Formats” copies the formatting of the range, including font, color, and other format settings, but no values. ”All” (the default option) copies both data and formatting, preserving cells’ formulas if found.

skipBlanks は空白のセルをコピー先にコピーするかどうかを設定します。True の場合、copyFrom はコピー元範囲内の空白のセルをスキップします。スキップしたセルは、コピー先範囲内の対応するセルの既存のデータに上書きされることはありません。既定では false です。skipBlanks sets whether blank cells are copied into the destination. When true, copyFrom skips blank cells in the source range. Skipped cells will not overwrite the existing data of their corresponding cells in the destination range. The default is false.

次のコード サンプルとイメージは、簡単なシナリオでのこの動作を示しています。The following code sample and images demonstrate this behavior in a simple scenario.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    // copy a range, omitting the blank cells so existing data is not overwritten in those cells
    sheet.getRange("D1").copyFrom("A1:C1",
        Excel.RangeCopyType.all,
        true, // skipBlanks
        false); // transpose
    // copy a range, including the blank cells which will overwrite existing data in the target cells
    sheet.getRange("D2").copyFrom("A2:C2",
        Excel.RangeCopyType.all,
        false, // skipBlanks
        false); // transpose
    return context.sync();
}).catch(errorHandlerFunction);

前出の関数を実行する前。Before the preceeding function has been run.

範囲のコピー メソッドを実行する前の Excel データ。

前出の関数を実行した後。After the preceeding function has been run.

範囲のコピー メソッドが実行された後の Excel データ。

transpose はデータが転置されているかどうか、すなわち行と列が交換されているかどうかを決定します。転置された範囲は主な対角線に沿って反転し、行 12、および 3 は列 AB、および C になります。transpose determines whether or not the data is transposed, meaning its rows and columns are switched, into the source location. A transposed range is flipped along the main diagonal, so rows 1, 2, and 3 will become columns A, B, and C.

関連項目See also