Excel.Range class

範囲参照を A1 スタイルで指定します。 アドレスの値にシート参照が含まれています (例: "Sheet1!A1:B4")。

readonly address: string;

プロパティ値

注釈

API セット: ExcelApi 1.1

指定した範囲の範囲参照をユーザーの言語で表します。

readonly addressLocal: string;

プロパティ値

注釈

API セット: ExcelApi 1.1

範囲内のセルの数を指定します。 セルの数が 2^31-1 (2,147,483,647) を超えると、この API は -1 を返します。

readonly cellCount: number;

プロパティ値

注釈

API セット: ExcelApi 1.1

範囲内の列の総数を指定します。

readonly columnCount: number;

プロパティ値

注釈

API セット: ExcelApi 1.1

現在の範囲内のすべての列が非表示になっているかどうかを表します。 範囲内のすべての列が非表示の場合、値は true されます。 値は、範囲内に非表示の列がない場合に false されます。 範囲内の一部の列が非表示になっていて、同じ範囲内の他の列が非表示でない場合、値は null されます。

columnHidden: boolean;

プロパティ値

注釈

API セット: ExcelApi 1.2

範囲内の最初のセルの列番号を指定します。 0 を起点とする番号になります。

readonly columnIndex: number;

プロパティ値

注釈

API セット: ExcelApi 1.1

範囲と交差する ConditionalFormats のコレクション。

readonly conditionalFormats: Excel.ConditionalFormatCollection;

プロパティ値

注釈

API セット: ExcelApi 1.6

オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。

context: RequestContext;

プロパティ値

この範囲に適用されているセル コントロールにアクセスします。 範囲に複数のセル コントロールがある場合は、 EmptyCellControl が返されます。

control: CellControl;

プロパティ値

注釈

API セット: ExcelApi 1.18

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml

// Add checkboxes to the table.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();

  // Get the second column in the table, without the header.
  const range = sheet.tables.getItem("FruitTable").columns.getItem("Analysis").getDataBodyRange();

  // Change the boolean values to checkboxes.
  range.control = {
    type: Excel.CellControlType.checkbox
  };
  await context.sync();
});

dataValidation オブジェクトを返します。

readonly dataValidation: Excel.DataValidation;

プロパティ値

注釈

API セット: ExcelApi 1.8

Format オブジェクト (範囲のフォント、塗りつぶし、罫線、配置などのプロパティをカプセル化するオブジェクト) を返します。

readonly format: Excel.RangeFormat;

プロパティ値

注釈

API セット: ExcelApi 1.1

範囲の配列数式を指定します。 指定した範囲に配列数式が含まれていない場合、このプロパティは null を返します。

formulaArray: string;

プロパティ値

注釈

API セット: ExcelApiDesktop 1.1

A1 スタイル表記の数式を表します。 セルに数式がない場合は、代わりにその値が返されます。

formulas: any[][];

プロパティ値

注釈

API セット: ExcelApi 1.1

ユーザーの言語と数値書式ロケールで、A1 スタイル表記の数式を表します。 たとえば、英語の数式 "=SUM(A1, 1.5)" は、ドイツ語では "=SUMME(A1; 1,5)" になります。 セルに数式がない場合は、代わりにその値が返されます。

formulasLocal: any[][];

プロパティ値

注釈

API セット: ExcelApi 1.1

R1C1 スタイル表記の数式を表します。 セルに数式がない場合は、代わりにその値が返されます。

formulasR1C1: any[][];

プロパティ値

注釈

API セット: ExcelApi 1.2

すべてのセルにスピル ボーダーがあるかどうかを表します。 すべてのセルにスピル罫線がある場合は true を返し、すべてのセルにスピル罫線がない場合は false を返します。 スピル境界線があるセルとないセルの両方が範囲内に存在する場合に null を返します。

readonly hasSpill: boolean;

プロパティ値

注釈

API セット: ExcelApi 1.12

100% ズームの場合、範囲の上端から範囲の下端までの距離をポイント単位で返します。

readonly height: number;

プロパティ値

注釈

API セット: ExcelApi 1.10

現在の範囲内のすべてのセルが非表示になっているかどうかを表します。 値は、範囲内のすべてのセルが非表示になっている場合に true されます。 範囲内の非表示セルがない場合は、値が false されます。 値は、範囲内の一部のセルが非表示になっていて、同じ範囲内の他のセルが非表示でない場合に null されます。

readonly hidden: boolean;

プロパティ値

注釈

API セット: ExcelApi 1.2

現在の範囲のハイパーリンクを表します。

hyperlink: Excel.RangeHyperlink;

プロパティ値

注釈

API セット: ExcelApi 1.7

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-hyperlink.yaml

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

    let productsRange = sheet.getRange("A3:A5");
    productsRange.load("values");

    await context.sync();

    // Create a hyperlink to a URL 
    // for each product name in the first table.
    for (let i = 0; i < productsRange.values.length; i++) {
        let cellRange = productsRange.getCell(i, 0);
        let cellText = productsRange.values[i][0];

        let hyperlink = {
            textToDisplay: cellText,
            screenTip: "Search Bing for '" + cellText + "'",
            address: "https://www.bing.com?q=" + cellText
        }
        cellRange.hyperlink = hyperlink;
    }

    await context.sync();
});

現在の範囲が列全体であるかどうかを表します。

readonly isEntireColumn: boolean;

プロパティ値

注釈

API セット: ExcelApi 1.7

現在の範囲が行全体であるかどうかを表します。

readonly isEntireRow: boolean;

プロパティ値

注釈

API セット: ExcelApi 1.7

100% ズームの場合、ワークシートの左端から範囲の左端までの距離をポイント単位で返します。

readonly left: number;

プロパティ値

注釈

API セット: ExcelApi 1.10

各セルのデータ型の状態を表します。

readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];

プロパティ値

注釈

API セット: ExcelApi 1.9

指定された範囲に対する Excel の数値書式コードを表します。 Excel の数値の書式設定の詳細については、「 数値の書式コード」を参照してください。

numberFormat: any[][];

プロパティ値

注釈

API セット: ExcelApi 1.1

例

// Set the text of the chart title to "My Chart" and display it as an overlay on the chart.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "F5:G7";
    const numberFormat = [[null, "d-mmm"], [null, "d-mmm"], [null, null]]
    const values = [["Today", 42147], ["Tomorrow", "5/24"], ["Difference in days", null]];
    const formulas = [[null,null], [null,null], [null,"=G6-G5"]];
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.numberFormat = numberFormat;
    range.values = values;
    range.formulas= formulas;
    range.load('text');
    await context.sync();
    
    console.log(range.text);
});

各セルの数値形式のカテゴリを表します。

readonly numberFormatCategories: Excel.NumberFormatCategory[][];

プロパティ値

注釈

API セット: ExcelApi 1.12

ユーザーの言語設定に基づいた、指定された範囲に対する Excel の数値書式コードを表します。 Excel は、 numberFormatLocal プロパティを取得または設定するときに、いかなる言語または形式の強制も実行しません。 返されるすべてのテキストは、システム設定で指定された言語に基づいて、ローカルで書式設定された文字列を使用します。

numberFormatLocal: any[][];

プロパティ値

注釈

API セット: ExcelApi 1.7

範囲に含まれる行の合計数を返します。

readonly rowCount: number;

プロパティ値

注釈

API セット: ExcelApi 1.1

現在の範囲内のすべての行が非表示になっているかどうかを表します。 範囲内のすべての行が非表示の場合、値が true されます。 値は、範囲内に非表示の行がない場合に false されます。 値 null 範囲内の一部の行が非表示になっていて、同じ範囲内の他の行が非表示でない場合に値がされます。

rowHidden: boolean;

プロパティ値

注釈

API セット: ExcelApi 1.2

範囲に含まれる最初のセルの行番号を返します。 0 を起点とする番号になります。

readonly rowIndex: number;

プロパティ値

注釈

API セット: ExcelApi 1.1

すべてのセルが配列数式として保存されるかどうかを表します。 すべてのセルが配列数式として保存される場合は true 、すべてのセルが配列数式として保存されない場合は false を返します。 一部のセルが配列数式として保存され、一部のセルが保存されないかどうかを null 返します。

readonly savedAsArray: boolean;

プロパティ値

注釈

API セット: ExcelApi 1.12

現在の範囲について、範囲の並べ替えを表します。

readonly sort: Excel.RangeSort;

プロパティ値

注釈

API セット: ExcelApi 1.2

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

async function sortTopToBottom(criteria: string) {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1:E5");

        // Find the column header that provides the sort criteria.
        const header = range.find(criteria, {});
        header.load("columnIndex");
        await context.sync();

        range.sort.apply(
            [
                {
                    key: header.columnIndex,
                    sortOn: Excel.SortOn.value
                }
            ],
            false /*matchCase*/,
            true /*hasHeaders*/,
            Excel.SortOrientation.rows
        );
        await context.sync();
    });
}

現在の範囲のスタイルを表します。 セルのスタイルに一貫性がない場合は、 null が返されます。 カスタム スタイルの場合は、スタイル名が返されます。 組み込みスタイルの場合は、 BuiltInStyle 列挙型の値を表す文字列が返されます。

style: string;

プロパティ値

注釈

API セット: ExcelApi 1.7

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/style.yaml

await Excel.run(async (context) => {
    let worksheet = context.workbook.worksheets.getItem("Sample");
    let range = worksheet.getRange("A1:E1");

    // Apply built-in style. 
    // Styles are in the Home tab ribbon.
    range.style = Excel.BuiltInStyle.neutral;
    range.format.horizontalAlignment = "Right";

    await context.sync();
});

指定した範囲のテキスト値。 テキスト値は、セルの幅には依存しません。 Excel UI で行われる数値記号 (#) 置換は、API によって返されるテキスト値には影響しません。

readonly text: string[][];

プロパティ値

注釈

API セット: ExcelApi 1.1

100% ズームの場合、ワークシートの上端から範囲の上端までの距離をポイント単位で返します。

readonly top: number;

プロパティ値

注釈

API セット: ExcelApi 1.10

指定した範囲の Raw 値を表します。 返されるデータは、文字列、数値、またはブール値を指定できます。 エラーが含まれているセルは、エラー文字列を返します。 返された値がプラス ("+")、マイナス ("-")、または等号 ("=") で始まる場合、Excel はこの値を数式として解釈します。 ロケール形式の文字列 (たとえば、nl-NL または fr-FR の日付 "19-8-2025"、形式 DD-MM-YYYY) は、日付としてではなくテキストとして保存されます。 日付が日付として格納されるようにするには、 formulasLocal などのロケール対応 API を使用するか、ISO (YYYY-MM-DD) または数値日付シリアルなどのロケールに依存しない形式を使用します。

values: any[][];

プロパティ値

注釈

API セット: ExcelApi 1.1

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml

// Change the value of the checkbox in B3.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const range = sheet.getRange("B3");

  range.values = [["TRUE"]];
  await context.sync();
});

この範囲内のセルの値の JSON 表現。 Range.values とは異なり、Range.valuesAsJson はセル内のすべてのデータ型をサポートします。 たとえば、標準のブール値、数値値、文字列値に加えて、書式設定された数値や Web 画像などがあります。 この API から返されるデータは、常に en-US ロケールに合わせて調整されます。 ユーザーの表示ロケールでデータを取得するには、 Range.valuesAsJsonLocal を使用します。

valuesAsJson: CellValue[][];

プロパティ値

注釈

API セット: ExcelApi 1.16

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-formatted-number.yaml

// This function creates a double data type,
// and sets the format of this data type as a date.
await Excel.run(async (context) => {
  // Get the Sample worksheet and a range on that sheet.
  const sheet = context.workbook.worksheets.getItemOrNullObject("Sample");
  const dateRange = sheet.getRange("A1");

  // Write a number formatted as a date to cell A1.
  dateRange.valuesAsJson = [
    [
      {
        type: Excel.CellValueType.double,
        basicValue: 32889.0,
        numberFormat: "m/d/yyyy"
      }
    ]
  ];
  await context.sync();
});

この範囲内のセルの値の JSON 表現。 Range.values とは異なり、Range.valuesAsJsonLocal はセル内のすべてのデータ型をサポートします。 たとえば、標準のブール値、数値値、文字列値に加えて、書式設定された数値や Web 画像などがあります。 この API から返されるデータは、常にユーザーの表示ロケールに合わせて調整されます。 ロケールに関係なくデータを取得するには、 Range.valuesAsJson を使用します。

valuesAsJsonLocal: CellValue[][];

プロパティ値

注釈

API セット: ExcelApi 1.16

各セルのデータ型を指定します。

readonly valueTypes: Excel.RangeValueType[][];

プロパティ値

注釈

API セット: ExcelApi 1.1

100% ズームの場合、範囲の左端から範囲の右端までの距離をポイント単位で返します。

readonly width: number;

プロパティ値

注釈

API セット: ExcelApi 1.10

現在の範囲を含んでいるワークシート。

readonly worksheet: Excel.Worksheet;

プロパティ値

注釈

API セット: ExcelApi 1.1

指定したオートフィル ロジックを使用して、現在の範囲からコピー先の範囲までを塗りつぶします。 コピー先範囲は null することも、ソース範囲を水平方向または垂直方向に拡張することもできます。 不連続な範囲はサポートされていません。

詳細については、「 オートフィルとフラッシュ フィルを使う」を参照してください。

autoFill(destinationRange?: Range | string, autoFillType?: Excel.AutoFillType): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.9、Null の ExcelApi プレビュー destinationRange

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-auto-fill.yaml

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const sumCell = sheet.getRange("P4");
  
  // Copy everything. The formulas will be contextually updated based on their new locations.
  sumCell.autoFill("P4:P7", Excel.AutoFillType.fillCopy);
  sumCell.format.autofitColumns();
  await context.sync();
});

指定したオートフィル ロジックを使用して、現在の範囲からコピー先の範囲までを塗りつぶします。 コピー先範囲は null することも、ソース範囲を水平方向または垂直方向に拡張することもできます。 不連続な範囲はサポートされていません。

詳細については、「 オートフィルとフラッシュ フィルを使う」を参照してください。

autoFill(destinationRange?: Range | string, autoFillType?: "FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.9、Null の ExcelApi プレビュー destinationRange

ワークシート上のセルの範囲を計算します。

calculate(): void;

返品

注釈

API セット: ExcelApi 1.6

この範囲内の単語のスペルをチェックします。 この方法では、Excel UI で [スペルチェック] ダイアログ ボックスが開きます。

checkSpelling(options?: Excel.CheckSpellingOptions): void;

パラメーター

返品

注釈

API セット: ExcelApiDesktop 1.1

範囲の値と書式設定 (塗りつぶしや罫線など) をクリアします。

clear(applyTo?: Excel.ClearApplyTo): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

// Clear the format and contents of the range.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.clear();
    await context.sync(); 
});

範囲の値と書式設定 (塗りつぶしや罫線など) をクリアします。

clear(applyTo?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

コントロールを含むセルに特に注意を払って、範囲内のセルの値をクリアします。 範囲に空白の値のみが含まれ、コントロールが既定値に設定されている場合、値とコントロールの書式設定は削除されます。 それ以外の場合、これにより、コントロールのあるセルが既定値に設定され、範囲内の他のセルの値がクリアされます。

clearOrResetContents(): void;

返品

注釈

API セット: ExcelApi 1.18

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml

// Remove all content from the Analysis column.
await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();

  // Get the second column in the table, without the header.
  const range = sheet.tables.getItem("FruitTable").columns.getItem("Analysis").getDataBodyRange();

  // Clear all the data from the second column.
  range.clearOrResetContents();
  await context.sync();
});

データ型を持つ範囲セルをテキストに変換します。

convertDataTypeToText(): void;

返品

注釈

API セット: ExcelApi 1.9

範囲セルをワークシート内のリンクされたデータ型に変換します。

convertToLinkedDataType(serviceID: number, languageCulture: string): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.9

ソースの範囲または RangeAreas からセル データまたは書式設定を現在の範囲にコピーします。 コピー先範囲のサイズは、ソース範囲または RangeAreasとは異なる場合があります。 コピー先がソースより小さい場合、宛先は自動的に展開されます。 注: Excel UI のコピー機能と同様に、宛先範囲が行または列のいずれかでソース範囲の正確な倍数である場合、ソース コンテンツは複数回レプリケートされます。 たとえば、2x2 範囲を 2x6 範囲にコピーすると、元の 2x2 範囲のコピーが 3 つ作成されます。

copyFrom(sourceRange: Range | RangeAreas | string, copyType?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.9

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-copyfrom.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the copied data.
    sheet.getRange("F2").values = [["Copied Formula"]];

    // Copy a range preserving the formulas.
    // Note: non-formula values are copied over as is.
    sheet.getRange("G2").copyFrom("A1:E1", Excel.RangeCopyType.formulas);
    await context.sync();
});

ソースの範囲または RangeAreas からセル データまたは書式設定を現在の範囲にコピーします。 コピー先範囲のサイズは、ソース範囲または RangeAreasとは異なる場合があります。 コピー先がソースより小さい場合、宛先は自動的に展開されます。 注: Excel UI のコピー機能と同様に、宛先範囲が行または列のいずれかでソース範囲の正確な倍数である場合、ソース コンテンツは複数回レプリケートされます。 たとえば、2x2 範囲を 2x6 範囲にコピーすると、元の 2x2 範囲のコピーが 3 つ作成されます。

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

パラメーター

返品

注釈

API セット: ExcelApi 1.9

範囲に関連付けられているセルを削除します。

delete(shift: Excel.DeleteShiftDirection): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.delete("Left");
    await context.sync(); 
});

範囲に関連付けられているセルを削除します。

delete(shift: "Up" | "Left"): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

指定された条件に基づいて指定された文字列を見つけます。 現在の範囲が 1 つのセルより大きい場合、検索はその範囲に制限され、それ以外の場合は、そのセルの後から始まるシート全体が検索されます。

find(text: string, criteria: Excel.SearchCriteria): Excel.Range;

パラメーター

返品

検索テキストと条件に一致する値を含む最初のセルを表す Range オブジェクト。

注釈

API セット: ExcelApi 1.9

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-find.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();

    // NOTE: If no match is found, an ItemNotFound error
    // is thrown when Range.find is evaluated.
    const searchText = (document.getElementById("searchText") as HTMLTextAreaElement).value;
    const foundRange = searchRange.find(searchText, {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();

    console.log(foundRange.address);
});

指定された条件に基づいて指定された文字列を見つけます。 現在の範囲が 1 つのセルより大きい場合、検索はその範囲に制限され、それ以外の場合は、そのセルの後から始まるシート全体が検索されます。 一致するものがない場合、このメソッドは isNullObject プロパティが true に設定されたオブジェクトを返します。 詳細については、「 *OrNullObject のメソッドとプロパティ」を参照してください。

findOrNullObject(text: string, criteria: Excel.SearchCriteria): Excel.Range;

パラメーター

返品

検索条件に一致した Range 。

注釈

API セット: ExcelApi 1.9

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-find.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();
    const searchText = (document.getElementById("searchText") as HTMLTextAreaElement).value;
    const foundRange = searchRange.findOrNullObject(searchText, {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();

    if (foundRange.isNullObject) {
        console.log("Text not found");
    } else {
        console.log(foundRange.address);
    }
});

現在の範囲に対してフラッシュ フィルを実行します。 フラッシュ フィルはパターンを検知すると自動的にデータを入力するため、パターンを見つけるには、範囲が 1 つの列範囲であり、その周囲にデータがある必要があります。

flashFill(): void;

返品

注釈

API セット: ExcelApi 1.9

左上のセルが現在のRangeオブジェクトと同じで、行数と列数が指定されているRange オブジェクトを取得します。

getAbsoluteResizedRange(numRows: number, numColumns: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.7

指定した範囲を包含する、最小の Range オブジェクトを取得します。 たとえば、"B2:C5" と "D10:E15" の GetBoundingRect は "B2:E15" になります。

getBoundingRect(anotherRange: Range | string): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:G6";
    let range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range = range.getBoundingRect("G4:H8");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // Prints Sheet1!D4:H8
});

行と列の番号に基づいて、1 つのセルを含んだ範囲オブジェクトを取得します。 ワークシート グリッド内にある限り、セルは親範囲の境界外に置かれてかまいません。 返されるセルは、範囲の左上のセルを基準に配置されます。

getCell(row: number, column: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

2D 配列を返します。各セルのフォント、塗りつぶし、罫線、配置などのプロパティ データをカプセル化します。

getCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;

パラメーター

返品

各項目が対応するセルの要求されたプロパティを表す 2D 配列。

注釈

API セット: ExcelApi 1.9

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/cell-properties.yaml

await Excel.run(async (context) => {
    const cell = context.workbook.getActiveCell();

    // Get only the properties requested in this load-options object.
    const propertiesToGet: Excel.CellPropertiesLoadOptions = {
        address: true,
        format: {
            fill: {
                color: true
            },
            font: {
                bold: true,
                color: true
            }
        },
        style: true
    };
    const cellProperties = cell.getCellProperties(propertiesToGet);

    await context.sync();
    const activeCellProperties: Excel.CellProperties = cellProperties.value[0][0];
    console.log(JSON.stringify(activeCellProperties, null, 2));
});

範囲に含まれる列を 1 つ取得します。

getColumn(column: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet19";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getColumn(1);
    range.load('address');
    await context.sync();

    console.log(range.address); // prints Sheet1!B1:B8
});

一次元配列を返します。各列のフォント、塗りつぶし、罫線、配置などのプロパティ データをカプセル化します。 指定された列内の列間で一貫性のないプロパティについては、null が返されます。

getColumnProperties(columnPropertiesLoadOptions: ColumnPropertiesLoadOptions): OfficeExtension.ClientResult<ColumnProperties[]>;

パラメーター

返品

各項目が対応する列の要求されたプロパティを表す配列。

注釈

API セット: ExcelApi 1.9

現在の Range オブジェクトの右側にある特定の数の列を取得します。

getColumnsAfter(count?: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.2

現在の Range オブジェクトの左側にある特定の数の列を取得します。

getColumnsBefore(count?: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.2

同じワークシート内または複数のワークシート内の指定した範囲の依存セルがすべて含まれる範囲を表す WorkbookRangeAreas オブジェクトを返します。 依存関係が見つからない場合は、 ItemNotFound エラーをスローします。

getDependents(): Excel.WorkbookRangeAreas;

返品

注釈

API セット: ExcelApi 1.15

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/precedents-and-dependents.yaml

/** Highlight all dependents (direct and indirect) of the active cell. */
async function getAllDependents() {
  await Excel.run(async (context) => {
    // Get addresses of all dependent cells of the active cell.
    const range = context.workbook.getActiveCell();
    const dependents = range.getDependents();
    range.load("address");
    dependents.areas.load("address");
    await context.sync();

    console.log(`All dependent cells of ${range.address} (orange cells):`);

    for (let i = 0; i < dependents.areas.items.length; i++) {
      // Highlight and print the address of each dependent cell.
      dependents.areas.items[i].format.fill.color = "Orange";
      console.log(`  ${dependents.areas.items[i].address}`);
    }
    await context.sync();
  });

同じワークシート内または複数のワークシート内の指定した範囲の直接従属セルがすべて含まれるセルを表す WorkbookRangeAreas オブジェクトを返します。 依存関係が見つからない場合は、 ItemNotFound エラーをスローします。

getDirectDependents(): Excel.WorkbookRangeAreas;

返品

注釈

API セット: ExcelApi 1.13

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/precedents-and-dependents.yaml

/** Highlight the direct dependents of the active cell. */
async function getDirectDependents() {
  await Excel.run(async (context) => {
    // Direct dependents are cells that contain formulas that directly refer to the active cell.
    let range = context.workbook.getActiveCell();
    let directDependents = range.getDirectDependents();
    range.load("address");
    directDependents.areas.load("address");
    await context.sync();

    console.log(`Direct dependent cells of ${range.address} (yellow cells):`);

    for (let i = 0; i < directDependents.areas.items.length; i++) {
      // Highlight and print the address of each direct dependent cell.
      directDependents.areas.items[i].format.fill.color = "Yellow";
      console.log(`  ${directDependents.areas.items[i].address}`);
    }
    await context.sync();
  });

同じワークシート内または複数のワークシート内で指定した範囲の直接指定の先頭のセルがすべて含まれる範囲を表す WorkbookRangeAreas オブジェクトを返します。 前例が見つからない場合は、 ItemNotFound エラーをスローします。

getDirectPrecedents(): Excel.WorkbookRangeAreas;

返品

注釈

API セット: ExcelApi 1.12

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/precedents-and-dependents.yaml

/** Highlight the direct precedents of the active cell. */
async function getDirectPrecedents() {
  await Excel.run(async (context) => {
    // Precedents are cells referenced by the formula in a cell.
    // A "direct precedent" is a cell directly referenced by the selected formula.
    let range = context.workbook.getActiveCell();
    let directPrecedents = range.getDirectPrecedents();
    range.load("address");
    directPrecedents.areas.load("address");
    await context.sync();

    console.log(`Direct precedent cells of ${range.address} (yellow cells):`);

    for (let i = 0; i < directPrecedents.areas.items.length; i++) {
      // Highlight and print the address of each direct precedent cell.
      directPrecedents.areas.items[i].format.fill.color = "Yellow";
      console.log(`  ${directPrecedents.areas.items[i].address}`);
    }
    await context.sync();
  });

各セルのフォント、塗りつぶし、罫線、配置、およびその他のプロパティの表示データをカプセル化する 2D 配列を返します。 セルに直接設定されたプロパティのみを表示する getCellProperties とは異なり、条件付き書式やスタイルなどの間接的なソースから表示されるプロパティが返されます。

getDisplayedCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;

パラメーター

返品

各項目が対応するセルの要求された表示プロパティを表す 2D 配列。

注釈

API セット: ExcelApi 1.19

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/cell-properties.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const cell = sheet.getRange("D3");
    const propertiesToGet: Excel.CellPropertiesLoadOptions = {
        address: true,
        format: {
            fill: {
                color: true
            },
            font: {
                bold: true,
                color: true
            },
        },
        style: true
    };

    // Direct properties exclude formatting inherited from styles or conditional formatting.
    const directProperties = cell.getCellProperties(propertiesToGet);
    // Displayed properties include formatting inherited from styles or conditional formatting.
    const displayedProperties = cell.getDisplayedCellProperties(propertiesToGet);

    await context.sync();

    console.log("Direct properties:");
    console.log(JSON.stringify(directProperties.value[0][0], null, 2));
    console.log("Displayed properties (including conditional formatting):");
    console.log(JSON.stringify(displayedProperties.value[0][0], null, 2));
});

範囲の列全体を表すオブジェクトを取得します (たとえば、現在の範囲がセル "B4:E11" を表す場合、その getEntireColumn は列 "B:E" を表す範囲です)。

getEntireColumn(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.1

例

// Note: the grid properties of the Range (values, numberFormat, formulas) 
// contains null since the Range in question is unbounded.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeEC = range.getEntireColumn();
    rangeEC.load('address');
    await context.sync();
    
    console.log(rangeEC.address);
});

範囲の行全体を表すオブジェクトを取得します (たとえば、現在の範囲がセル "B4:E11" を表す場合、その GetEntireRow は行 "4:11" を表す範囲です)。

getEntireRow(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.1

例

// Gets an object that represents the entire row of the range 
// (for example, if the current range represents cells "B4:E11", 
// its GetEntireRow is a range that represents rows "4:11").
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "D:F"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeER = range.getEntireRow();
    rangeER.load('address');
    await context.sync();
    
    console.log(rangeER.address);
});

指定された方向に基づいて、現在の範囲から範囲の端までを含む範囲オブジェクトを返します。 これは、Excel on Windows UI の Ctrl キー + Shift キー + 方向キーの動作と同じです。

getExtendedRange(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.13

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-get-range-edge.yaml

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.down;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get all the cells from the currently selected range to the bottom-most edge of the used range.
  // This method acts like the Ctrl+Shift+Arrow key keyboard shortcut while a range is selected.
  const extendedRange = range.getExtendedRange(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  extendedRange.select();

  await context.sync();
});

指定された方向に基づいて、現在の範囲から範囲の端までを含む範囲オブジェクトを返します。 これは、Excel on Windows UI の Ctrl キー + Shift キー + 方向キーの動作と同じです。

getExtendedRange(direction: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.13

範囲を Base64 でエンコードされた PNG 画像としてレンダリングします。

getImage(): OfficeExtension.ClientResult<string>;

返品

注釈

API セット: ExcelApi 1.7

指定した範囲の長方形の交差を表す範囲オブジェクトを取得します。

getIntersection(anotherRange: Range | string): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getIntersection("D4:G6");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!D4:F6
});

指定した範囲の長方形の交差を表す範囲オブジェクトを取得します。 共通部分が見つからない場合、このメソッドは isNullObject プロパティが true に設定されたオブジェクトを返します。 詳細については、「 *OrNullObject のメソッドとプロパティ」を参照してください。

getIntersectionOrNullObject(anotherRange: Range | string): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.4

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

範囲内の最後のセルを取得します。 たとえば、"B2:D5" の最後のセルは "D5" になります。

getLastCell(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastCell();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F8
});

範囲内の最後の列を取得します。 たとえば、"B2:D5" の最後の列は "D2:D5" になります。

getLastColumn(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastColumn();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F1:F8
});

範囲内の最後の行を取得します。 たとえば、"B2:D5" の最後の行は "B5:D5" になります。

getLastRow(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastRow();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A8:F8
});

この範囲内の結合された領域を表す RangeAreas オブジェクトを返します。 この範囲内の結合された領域の数が 512 を超える場合、このメソッドは結果を返さないことに注意してください。 RangeAreas オブジェクトが存在しない場合、このメソッドは isNullObject プロパティが true に設定されたオブジェクトを返します。 詳細については、「 *OrNullObject のメソッドとプロパティ」を参照してください。

getMergedAreasOrNullObject(): Excel.RangeAreas;

返品

注釈

API セット: ExcelApi 1.13

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-merged-ranges.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Retrieve the merged range within the table and load its details.
  const mergedAreas = tableRange.getMergedAreasOrNullObject();
  mergedAreas.load("address");
  mergedAreas.load("cellCount");

  // Select the merged range.
  const range = mergedAreas.areas.getItemAt(0);
  range.select();
  await context.sync();

  // Print out the details of the `mergedAreas` range object.
  console.log(`Address of the merged range: ${mergedAreas.address}`);
  console.log(`Number of cells in the merged range: ${mergedAreas.cellCount}`);

  await context.sync();
});

指定した範囲からのオフセットで範囲を表すオブジェクトを取得します。 返される範囲のディメンションは、この範囲と一致します。 結果の範囲がワークシートのグリッドの境界線の外にはみ出る場合は、エラーがスローされます。

getOffsetRange(rowOffset: number, columnOffset: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:F6";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getOffsetRange(-1,4);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!H3:J5
});

範囲に重なるピボットテーブルの範囲のコレクションを取得します。

getPivotTables(fullyContained?: boolean): Excel.PivotTableScopedCollection;

パラメーター

返品

注釈

API セット: ExcelApi 1.12

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

await Excel.run(async (context) => {
  const activeRange = context.workbook.getSelectedRange();

  // Get all the PivotTables that intersect with this range.
  const partiallyContainedPivotTables = activeRange.getPivotTables();
  // Get all the PivotTables that are completely contained within this range.
  const fullyContainedPivotTables = activeRange.getPivotTables(true);

  partiallyContainedPivotTables.load("name");
  fullyContainedPivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current range:")
  partiallyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
  console.log("PivotTables completely contained in the current range:")
  fullyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

同じワークシート内または複数のワークシート内の指定した範囲内で指定した列の先行セルがすべて含まれるセル範囲を表す WorkbookRangeAreas オブジェクトを返します。 前例が見つからない場合は、 ItemNotFound エラーをスローします。

getPrecedents(): Excel.WorkbookRangeAreas;

返品

注釈

API セット: ExcelApi 1.14

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/precedents-and-dependents.yaml

/** Highlight all precedents (direct and indirect) of the active cell. */
async function getAllPrecedents() {
  await Excel.run(async (context) => {
    // Precedents are cells referenced by the formula in a cell.
    let range = context.workbook.getActiveCell();
    let precedents = range.getPrecedents();
    range.load("address");
    precedents.areas.load("address");
    await context.sync();

    console.log(`All precedent cells of ${range.address} (orange cells):`);

    for (let i = 0; i < precedents.areas.items.length; i++) {
      // Highlight and print the address of each precedent cell.
      precedents.areas.items[i].format.fill.color = "Orange";
      console.log(`  ${precedents.areas.items[i].address}`);
    }
    await context.sync();
  });

指定された方向に対応するデータ領域のエッジ セルである範囲オブジェクトを返します。 これは、Excel on Windows UI の Ctrl キー + 方向キーの動作と同じです。

getRangeEdge(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.13

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-get-range-edge.yaml

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.up;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get the top-most cell of the current used range.
  // This method acts like the Ctrl+Arrow key keyboard shortcut while a range is selected.
  const rangeEdge = range.getRangeEdge(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  rangeEdge.select();

  await context.sync();
});

指定された方向に対応するデータ領域のエッジ セルである範囲オブジェクトを返します。 これは、Excel on Windows UI の Ctrl キー + 方向キーの動作と同じです。

getRangeEdge(direction: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.13

現在の Range オブジェクトに似たRangeオブジェクトを取得しますが、その右下隅がいくつかの行と列だけ展開 (または縮小) されています。

getResizedRange(deltaRows: number, deltaColumns: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.2

範囲に含まれている行を 1 つ取得します。

getRow(row: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getRow(1);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A2:F2
});

一次元配列を返します。各行のフォント、塗りつぶし、罫線、配置などのプロパティ データをカプセル化します。 特定の行内の各セル間で一貫していないプロパティの場合は、 null が返されます。

getRowProperties(rowPropertiesLoadOptions: RowPropertiesLoadOptions): OfficeExtension.ClientResult<RowProperties[]>;

パラメーター

返品

各項目が対応する行の要求されたプロパティを表す配列。

注釈

API セット: ExcelApi 1.9

現在の Range オブジェクトの上の一定数の行を取得します。

getRowsAbove(count?: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.2

現在の Range オブジェクトの下に一定数の行を取得します。

getRowsBelow(count?: number): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.2

指定した型と値に一致するすべてのセルを表す、1 つ以上の四角形の範囲で構成される RangeAreas オブジェクトを取得します。 特殊セルが見つからない場合は、 ItemNotFound エラーがスローされます。

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

パラメーター

返品

注釈

API セット: ExcelApi 1.9

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml

await Excel.run(async (context) => {

    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const usedRange = sheet.getUsedRange();

    // Find the ranges with either text or logical (boolean) values.
    const formulaRanges = usedRange.getSpecialCells("Constants", "LogicalText");
    formulaRanges.format.fill.color = "orange";

    return context.sync();
});

指定した型と値に一致するすべてのセルを表す、1 つ以上の四角形の範囲で構成される RangeAreas オブジェクトを取得します。 特殊セルが見つからない場合は、 ItemNotFound エラーがスローされます。

getSpecialCells(cellType: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas", cellValueType?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

パラメーター

返品

注釈

API セット: ExcelApi 1.9

指定した型と値に一致するすべてのセルを表す、1 つ以上の範囲からなる RangeAreas オブジェクトを取得します。 特別なセルが見つからない場合、このメソッドは isNullObject プロパティが true に設定されたオブジェクトを返します。 詳細については、「 *OrNullObject のメソッドとプロパティ」を参照してください。

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

パラメーター

返品

注釈

API セット: ExcelApi 1.9

指定した型と値に一致するすべてのセルを表す、1 つ以上の範囲からなる RangeAreas オブジェクトを取得します。 特別なセルが見つからない場合、このメソッドは isNullObject プロパティが true に設定されたオブジェクトを返します。 詳細については、「 *OrNullObject のメソッドとプロパティ」を参照してください。

getSpecialCellsOrNullObject(cellType: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas", cellValueType?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

パラメーター

返品

注釈

API セット: ExcelApi 1.9

アンカー セルで呼び出されたとき、スピル範囲を含む範囲オブジェクトを取得します。 複数のセルを含む範囲に適用される場合は失敗します。

getSpillingToRange(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.12

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/dynamic-arrays.yaml

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

  // Set G4 to a formula that returns a dynamic array.
  const targetCell = sheet.getRange("G4");
  targetCell.formulas = [["=A4:D4"]];

  // Get the address of the cells that the dynamic array spilled into.
  const spillRange = targetCell.getSpillingToRange();
  spillRange.load("address");

  // Fit the columns for readability.
  sheet.getUsedRange().format.autofitColumns();
  await context.sync();

  console.log(`Copying the table headers spilled into ${spillRange.address}.`);
});

アンカー セルで呼び出されたとき、スピル範囲を含む範囲オブジェクトを取得します。 範囲がアンカー セルではない場合、またはスピル範囲が見つからない場合、このメソッドは isNullObject プロパティが true に設定されたオブジェクトを返します。 詳細については、「 *OrNullObject のメソッドとプロパティ」を参照してください。

getSpillingToRangeOrNullObject(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.12

スピルするセルのアンカー セルを含む範囲オブジェクトを取得します。 複数のセルを含む範囲に適用される場合は失敗します。

getSpillParent(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.12

スピルされるセルのアンカー セルを含む範囲オブジェクトを取得します。 スピルされたセルではない場合、または複数のセルが指定されている場合、このメソッドは isNullObject プロパティが true に設定されたオブジェクトを返します。 詳細については、「 *OrNullObject のメソッドとプロパティ」を参照してください。

getSpillParentOrNullObject(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.12

この範囲内の左上のセルの周囲の領域を表す Range オブジェクトを返します。 周囲の領域は、この範囲に相対の空白の行と空白の列の任意の組み合わせで囲まれた範囲です。

getSurroundingRegion(): Excel.Range;

返品

注釈

API セット: ExcelApi 1.7

範囲と重なるテーブルの集まりを範囲限定で取得します。

getTables(fullyContained?: boolean): Excel.TableScopedCollection;

パラメーター

返品

注釈

API セット: ExcelApi 1.9

指定した範囲オブジェクトのうち使用されている範囲を返します。 範囲内に使用されているセルがない場合、この関数は ItemNotFound エラーをスローします。

getUsedRange(valuesOnly?: boolean): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

指定した範囲オブジェクトのうち使用されている範囲を返します。 範囲内に使用されているセルがない場合、このメソッドは isNullObject プロパティが true に設定されたオブジェクトを返します。 詳細については、「 *OrNullObject のメソッドとプロパティ」を参照してください。

getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.4

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/used-range.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // Pass true so only cells with values count as used
    const usedDataRange = dataRange.getUsedRangeOrNullObject(
        true /* valuesOnly */
    );

    //Must sync before reading value returned from *OrNullObject method/property.
    await context.sync();

    if (usedDataRange.isNullObject) {
        console.log("Need Data to Make Chart");
        console.log("To create a meaningful chart, press 'Fill the table' (or add names to the Product column and numbers to some of the other cells). Then press 'Try to create chart' again.");
    } else {
        const chart = sheet.charts.add(
            Excel.ChartType.columnClustered,
            dataRange,
            "Columns"
        );
        chart.setPosition("A15", "F30");
        chart.title.text = "Quarterly sales chart";
        chart.legend.position = "Right";
        chart.legend.format.fill.setSolidColor("white");
        chart.dataLabels.format.font.size = 15;
        chart.dataLabels.format.font.color = "black";
    }

    await context.sync();
});

現在の範囲の表示されている行を表します。

getVisibleView(): Excel.RangeView;

返品

注釈

API セット: ExcelApi 1.3

アウトラインの列と行をグループ化します。

group(groupOption: Excel.GroupOption): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.10

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // Group the larger, main level. Note that the outline controls
    // will be on row 10, meaning 4-9 will collapse and expand.
    sheet.getRange("4:9").group(Excel.GroupOption.byRows);

    // Group the smaller, sublevels. Note that the outline controls
    // will be on rows 6 and 9, meaning 4-5 and 7-8 will collapse and expand.
    sheet.getRange("4:5").group(Excel.GroupOption.byRows);
    sheet.getRange("7:8").group(Excel.GroupOption.byRows);
    await context.sync();
});

アウトラインの列と行をグループ化します。

group(groupOption: "ByRows" | "ByColumns"): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.10

行または列グループの詳細を非表示にします。

hideGroupDetails(groupOption: Excel.GroupOption): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.10

行または列グループの詳細を非表示にします。

hideGroupDetails(groupOption: "ByRows" | "ByColumns"): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.10

この範囲を占めるセルまたはセルの範囲をワークシートに挿入し、領域を空けるために他のセルをシフトします。 空白のスペースに新しい Range オブジェクトを返します。

insert(shift: Excel.InsertShiftDirection): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.insert(Excel.InsertShiftDirection.down);
    await context.sync();
});

この範囲を占めるセルまたはセルの範囲をワークシートに挿入し、領域を空けるために他のセルをシフトします。 空白のスペースに新しい Range オブジェクトを返します。

insert(shift: "Down" | "Right"): Excel.Range;

パラメーター

返品

注釈

API セット: ExcelApi 1.1

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(options?: Excel.Interfaces.RangeLoadOptions): Excel.Range;

パラメーター

返品

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(propertyNames?: string | string[]): Excel.Range;

パラメーター

返品

例

// Use the range address to get the range object.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8"; 
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    await context.sync();
    
    console.log(range.cellCount);
});

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Range;

パラメーター

返品

範囲内のセルをワークシートの 1 つの領域に結合します。

merge(across?: boolean): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.2

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-merged-ranges.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Create a merged range in the first row of the table.
  const chartTitle = tableRange.getRow(0);
  chartTitle.merge(true);

  // Format the merged range.
  chartTitle.format.horizontalAlignment = "Center";

  await context.sync();
});

セルの値、書式設定、数式を現在の範囲から移動先の範囲に移動し、それらのセル内の古い情報を置き換えます。 現在の範囲より小さい場合、出力先範囲は自動的に拡張されます。 宛先範囲内で、元の範囲の領域外にあるセルは変更されません。 注: この API を使用して範囲を新しいアドレスに移動する場合は、新しいアドレスを使用して新しい範囲オブジェクトを取得する必要があります。

moveTo(destinationRange: Range | string): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.11

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-copyfrom.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the moved data.
    sheet.getRange("F12").values = [["Moved Range:"]];

    // Move the range from A1:E1 to G12:K12.
    sheet.getRange("A1:E1").moveTo("G12");
    await context.sync();
});

列によって指定される範囲から重複する値を削除します。

removeDuplicates(columns: number[], includesHeader: boolean): Excel.RemoveDuplicatesResult;

パラメーター

返品

削除された行の数と残りの一意の行の数を含む結果オブジェクト。

注釈

API セット: ExcelApi 1.9

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-remove-duplicates.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:D11");

    const deleteResult = range.removeDuplicates([0],true);    
    deleteResult.load();    
    await context.sync();

    console.log(deleteResult.removed + " entries with duplicate names removed.");
    console.log(deleteResult.uniqueRemaining + " entries with unique names remain in the range.");
});

現在の範囲内で、指定された条件に基づき、指定された文字列を検索し、置換します。

replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;

パラメーター

返品

実行された置換の数。

注釈

API セット: ExcelApi 1.9

Excel UI で指定した範囲を選択します。

select(): void;

返品

注釈

API セット: ExcelApi 1.1

例

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.select();
    await context.sync(); 
});

オブジェクトの複数のプロパティを同時に設定します。 適切なプロパティを持つプレーン オブジェクト、または同じ型の別の API オブジェクトを渡すことができます。

set(properties: Interfaces.RangeUpdateData, options?: OfficeExtension.UpdateOptions): void;

パラメーター

返品

既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。

set(properties: Excel.Range): void;

パラメーター

返品

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/multiple-property-set.yaml

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

    const sourceRange = sheet.getRange("B2:E2");
    sourceRange.load("format/fill/color, format/font/name, format/font/color");
    await context.sync();

    // Set properties based on the loaded and synced 
    // source range.
    const targetRange = sheet.getRange("B7:E7");
    targetRange.set(sourceRange); 
    targetRange.format.autofitColumns();
    await context.sync();
});

Updates セル プロパティの 2D 配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。

setCellProperties(cellPropertiesData: SettableCellProperties[][]): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.9

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/cell-properties.yaml

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

    // Create the SettableCellProperties objects for the range.
    // Create these objects once, outside the function, in your add-in.
    const topHeaderProps: Excel.SettableCellProperties = {
        // Set the style property to the name of an Excel style.
        // The `BuiltInStyle` enum lists the built-in style names.
        // A style overwrites formatting, so don't use style and format in the same object.
        style: Excel.BuiltInStyle.heading1
    };

    const headerProps: Excel.SettableCellProperties = {
        // Setting these cell properties doesn't change unspecified format subproperties.
        format: {
            fill: {
                color: "Blue"
            },
            font: {
                color: "White",
                bold: true
            }
        }
    };

    const nonApplicableProps: Excel.SettableCellProperties = {
        format: {
            fill: {
                pattern: Excel.FillPattern.gray25
            },
            font: {
                color: "Gray",
                italic: true
            }
        }
    };

    const matchupScoreProps: Excel.SettableCellProperties = {
        format: {
            borders: {
                bottom: {
                    style: Excel.BorderLineStyle.continuous
                },
                left: {
                    style: Excel.BorderLineStyle.continuous
                },
                right: {
                    style: Excel.BorderLineStyle.continuous
                },
                top: {
                    style: Excel.BorderLineStyle.continuous
                }
            },
            horizontalAlignment: Excel.HorizontalAlignment.center
        }
    };

    const range = sheet.getRange("A1:E5");

    // Use empty JSON objects to leave a cell's properties unchanged.
    range.setCellProperties([
        [topHeaderProps, {}, {}, {}, {}],
        [{}, {}, headerProps, headerProps, headerProps],
        [{}, headerProps, nonApplicableProps, matchupScoreProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, nonApplicableProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, matchupScoreProps, nonApplicableProps]
    ]);

    sheet.getUsedRange().format.autofitColumns();
    await context.sync();
});

Updates 列プロパティの 1 次元配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。

setColumnProperties(columnPropertiesData: SettableColumnProperties[]): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.9

次の再計算が発生したときに再計算する範囲を設定します。

setDirty(): void;

返品

注釈

API セット: ExcelApi 1.9

Updates 行プロパティの 1 次元配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。

setRowProperties(rowPropertiesData: SettableRowProperties[]): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.9

アクティブ セルに多数の値が含まれる場合、そのセルのカードを表示します。

showCard(): void;

返品

注釈

API セット: ExcelApi 1.7

アクティブ セル (参照元) から、その値を直接参照しているセル (参照先) に向けてトレース矢印を引きます。

showDependents(remove?: boolean): void;

パラメーター

返品

注釈

API セット: ExcelApiDesktop 1.1

行または列グループの詳細を表示します。

showGroupDetails(groupOption: Excel.GroupOption): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.10

行または列グループの詳細を表示します。

showGroupDetails(groupOption: "ByRows" | "ByColumns"): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.10

対象セルが直接参照しているセル (参照元) から、対象セルに向けて矢印を引きます。

showPrecedents(remove?: boolean): void;

パラメーター

返品

注釈

API セット: ExcelApiDesktop 1.1

Python in Excel の数式 = PY のマーシャリング モードを設定します。

togglePythonMarshalMode(marshalMode?: Excel.PythonMarshalMode): void;

パラメーター

返品

注釈

API セット: ExcelApi ベータ版 (プレビューのみ)

Python in Excel の数式 = PY のマーシャリング モードを設定します。

togglePythonMarshalMode(marshalMode?: "PythonObject" | "ExcelValue"): void;

パラメーター

返品

注釈

API セット: ExcelApi ベータ版 (プレビューのみ)

API オブジェクトが JSON.stringify() に渡されるときに、より有用な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (次に、JSON.stringify渡されたオブジェクトの toJSON メソッドを呼び出します)。元の Excel.Range オブジェクトが API オブジェクトであるのに対し、 toJSON メソッドは、元のオブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト ( Excel.Interfaces.RangeData と型指定) を返します。

toJSON(): Excel.Interfaces.RangeData;

返品

ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject) の短縮形です。 このオブジェクトを .sync 呼び出しと ".run" バッチの連続実行の外部で使用していて、プロパティを設定したり、オブジェクトでメソッドを呼び出したりするときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクト コレクションにオブジェクトを追加する必要があります。

track(): Excel.Range;

返品

アウトラインの列と行のグループを解除します。

ungroup(groupOption: Excel.GroupOption): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.10

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // This removes two levels of groups from the "A1-R10" range.
    // Any groups at the same level on the same dimension will be removed by a single call.
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    await context.sync();
});

アウトラインの列と行のグループを解除します。

ungroup(groupOption: "ByRows" | "ByColumns"): void;

パラメーター

返品

注釈

API セット: ExcelApi 1.10

範囲内のセルを結合解除して別々のセルにします。

unmerge(): void;

返品

注釈

API セット: ExcelApi 1.2

例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.unmerge();
    await context.sync(); 
});

前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは、 context.trackedObjects.remove(thisObject) の省略形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ リリースを有効にする前に、 context.sync() を呼び出す必要があります。

untrack(): Excel.Range;

返品

例

await Excel.run(async (context) => {
    const largeRange = context.workbook.getSelectedRange();
    largeRange.load(["rowCount", "columnCount"]);
    await context.sync();

    for (let i = 0; i < largeRange.rowCount; i++) {
        for (let j = 0; j < largeRange.columnCount; j++) {
            const cell = largeRange.getCell(i, j);
            cell.values = [[i *j]];

            // Call untrack() to release the range from memory.
            cell.untrack();
        }
    }

    await context.sync();
});