Excel.Range class
範囲は、セル、行、列、セルのブロックなど、1 つ以上の連続したセルのセットを表します。 API 全体での範囲の使用方法の詳細については、 Excel JavaScript API の範囲から始めます。
- Extends
注釈
例
// Get a Range object by its address.
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);
});
プロパティ
| address | 範囲参照を A1 スタイルで指定します。 アドレス値にはシート参照が含まれます (例: "Sheet1!A1:B4")。 |
| address |
ユーザーの言語で指定した範囲の範囲参照を表します。 |
| cell |
範囲内のセルの数を指定します。 セルの数が 2^31-1 (2,147,483,647) を超えると、この API は -1 を返します。 |
| column |
範囲内の列の合計数を指定します。 |
| column |
現在の範囲内のすべての列が非表示の場合にを表します。 値は、範囲内のすべての列が非表示の場合に |
| column |
範囲内の最初のセルの列番号を指定します。 0 を起点とする番号になります。 |
| context | オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。 |
| format | Format オブジェクト (範囲のフォント、塗りつぶし、罫線、配置などのプロパティをカプセル化するオブジェクト) を返します。 |
| formulas | A1 スタイル表記の数式を表します。 セルに数式がない場合は、代わりに値が返されます。 |
| formulas |
ユーザーの言語と数値書式ロケールで、A1 スタイル表記の数式を表します。 たとえば、英語の数式 "=SUM(A1, 1.5)" は、ドイツ語では "=SUMME(A1; 1,5)" になります。 セルに数式がない場合は、代わりに値が返されます。 |
| formulasR1C1 | R1C1 スタイル表記の数式を表します。 セルに数式がない場合は、代わりに値が返されます。 |
| hidden | 現在の範囲内のすべてのセルが非表示かどうかを表します。 値は、範囲内のすべてのセルが非表示の場合に |
| number |
指定した範囲の Excel の数値書式コードを表します。 Excel の数値書式の詳細については、「数値書式 コード」を参照してください。 |
| row |
範囲に含まれる行の合計数を返します。 |
| row |
現在の範囲内のすべての行が非表示になっているかどうかを表します。 値は、範囲内のすべての行が非表示の場合に |
| row |
範囲に含まれる最初のセルの行番号を返します。 0 を起点とする番号になります。 |
| sort | 現在の範囲について、範囲の並べ替えを表します。 |
| text | 指定した範囲のテキスト値。 テキスト値は、セルの幅には依存しません。 Excel UI で発生する数値記号 (#) の置換は、API によって返されるテキスト値には影響しません。 |
| values | 指定した範囲の Raw 値を表します。 返されるデータは、文字列、数値、またはブール値のいずれかです。 エラーが含まれているセルは、エラー文字列を返します。 返される値が正符号 ("+")、マイナス ("-")、または等号 ("=") で始まる場合、Excel はこの値を数式として解釈します。 |
| value |
各セル内のデータの種類を指定します。 |
| worksheet | 現在の範囲を含んでいるワークシート。 |
メソッド
| clear(apply |
範囲の値、書式、塗りつぶし、罫線などをクリアします。 |
| clear(apply |
範囲の値、書式、塗りつぶし、罫線などをクリアします。 |
| delete(shift) | 範囲に関連付けられているセルを削除します。 |
| delete(shift |
範囲に関連付けられているセルを削除します。 |
| get |
指定した範囲を包含する、最小の Range オブジェクトを取得します。 たとえば、"B2:C5" と "D10:E15" の |
| get |
行と列の番号に基づいて、1 つのセルを含んだ範囲オブジェクトを取得します。 セルは、ワークシートのグリッド内に留まる限り、親範囲の範囲外にすることができます。 返されるセルは、範囲の左上のセルを基準に配置されます。 |
| get |
範囲に含まれる列を 1 つ取得します。 |
| get |
現在の |
| get |
現在の |
| get |
範囲の列全体を表すオブジェクトを取得します (たとえば、現在の範囲がセル "B4:E11" を表す場合、その |
| get |
範囲の行全体を表すオブジェクトを取得します (たとえば、現在の範囲がセル "B4:E11" を表している場合、その |
| get |
指定した範囲の長方形の交差を表す範囲オブジェクトを取得します。 |
| get |
指定した範囲の長方形の交差を表す範囲オブジェクトを取得します。 積集合が見つからない場合、このメソッドは |
| get |
範囲内の最後のセルを取得します。 たとえば、"B2:D5" の最後のセルは "D5" になります。 |
| get |
範囲内の最後の列を取得します。 たとえば、"B2:D5" の最後の列は "D2:D5" になります。 |
| get |
範囲内の最後の行を取得します。 たとえば、"B2:D5" の最後の行は "B5:D5" になります。 |
| get |
指定した範囲からのオフセットで範囲を表すオブジェクトを取得します。 返される範囲のディメンションは、この範囲と一致します。 結果の範囲がワークシートのグリッドの境界線の外にはみ出る場合は、エラーがスローされます。 |
| get |
現在の |
| get |
範囲に含まれている行を 1 つ取得します。 |
| get |
現在の |
| get |
現在の |
| get |
指定した範囲オブジェクトのうち使用されている範囲を返します。 範囲内に使用されたセルがない場合、この関数は |
| get |
指定した範囲オブジェクトのうち使用されている範囲を返します。 範囲内に使用されているセルがない場合、このメソッドは |
| get |
現在の範囲の表示されている行を表します。 |
| insert(shift) | この範囲を占めるセルまたはセルの範囲をワークシートに挿入し、領域を空けるために他のセルをシフトします。 現在の空白位置にある新しい |
| insert(shift |
この範囲を占めるセルまたはセルの範囲をワークシートに挿入し、領域を空けるために他のセルをシフトします。 現在の空白位置にある新しい |
| load(options) | オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
| load(property |
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
| load(property |
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
| merge(across) | 範囲内のセルをワークシートの 1 つの領域に結合します。 |
| select() | Excel UI で指定した範囲を選択します。 |
| set(properties, options) | オブジェクトの複数のプロパティを同時に設定します。 適切なプロパティを持つプレーン オブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。 |
| set(properties) | 既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。 |
| toJSON() | API オブジェクトが |
| track() | ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを |
| unmerge() | 範囲内のセルを結合解除して別々のセルにします。 |
| untrack() | 前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは 、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に、 |
プロパティの詳細
address
範囲参照を A1 スタイルで指定します。 アドレス値にはシート参照が含まれます (例: "Sheet1!A1:B4")。
readonly address: string;プロパティ値
string
注釈
addressLocal
cellCount
範囲内のセルの数を指定します。 セルの数が 2^31-1 (2,147,483,647) を超えると、この API は -1 を返します。
readonly cellCount: number;プロパティ値
number
注釈
columnCount
columnHidden
現在の範囲内のすべての列が非表示の場合にを表します。 値は、範囲内のすべての列が非表示の場合に true されます。 値は、範囲内の列が非表示でない場合に false されます。 値は、範囲内の一部の列が非表示で、同じ範囲内の他の列が非表示でない場合に null されます。
columnHidden: boolean;プロパティ値
boolean
注釈
columnIndex
範囲内の最初のセルの列番号を指定します。 0 を起点とする番号になります。
readonly columnIndex: number;プロパティ値
number
注釈
context
オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。
context: RequestContext;プロパティ値
format
Format オブジェクト (範囲のフォント、塗りつぶし、罫線、配置などのプロパティをカプセル化するオブジェクト) を返します。
readonly format: Excel.RangeFormat;プロパティ値
注釈
formulas
A1 スタイル表記の数式を表します。 セルに数式がない場合は、代わりに値が返されます。
formulas: any[][];プロパティ値
any[][]
注釈
formulasLocal
ユーザーの言語と数値書式ロケールで、A1 スタイル表記の数式を表します。 たとえば、英語の数式 "=SUM(A1, 1.5)" は、ドイツ語では "=SUMME(A1; 1,5)" になります。 セルに数式がない場合は、代わりに値が返されます。
formulasLocal: any[][];プロパティ値
any[][]
注釈
formulasR1C1
R1C1 スタイル表記の数式を表します。 セルに数式がない場合は、代わりに値が返されます。
formulasR1C1: any[][];プロパティ値
any[][]
注釈
hidden
現在の範囲内のすべてのセルが非表示かどうかを表します。 値は、範囲内のすべてのセルが非表示の場合に true されます。 値は、範囲内のセルが非表示でない場合に false されます。 値は、範囲内の一部のセルが非表示で、同じ範囲内の他のセルが非表示でない場合に null されます。
readonly hidden: boolean;プロパティ値
boolean
注釈
numberFormat
指定した範囲の Excel の数値書式コードを表します。 Excel の数値書式の詳細については、「数値書式 コード」を参照してください。
numberFormat: any[][];プロパティ値
any[][]
注釈
例
// 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);
});
rowCount
rowHidden
現在の範囲内のすべての行が非表示になっているかどうかを表します。 値は、範囲内のすべての行が非表示の場合に true されます。 値は、範囲内の行が非表示でない場合に false されます。 値は、範囲内の一部の行が非表示で、同じ範囲内の他の行が非表示でない場合に null されます。
rowHidden: boolean;プロパティ値
boolean
注釈
rowIndex
範囲に含まれる最初のセルの行番号を返します。 0 を起点とする番号になります。
readonly rowIndex: number;プロパティ値
number
注釈
sort
現在の範囲について、範囲の並べ替えを表します。
readonly sort: Excel.RangeSort;プロパティ値
注釈
例
// 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();
});
}
text
指定した範囲のテキスト値。 テキスト値は、セルの幅には依存しません。 Excel UI で発生する数値記号 (#) の置換は、API によって返されるテキスト値には影響しません。
readonly text: string[][];プロパティ値
string[][]
注釈
values
指定した範囲の Raw 値を表します。 返されるデータは、文字列、数値、またはブール値のいずれかです。 エラーが含まれているセルは、エラー文字列を返します。 返される値が正符号 ("+")、マイナス ("-")、または等号 ("=") で始まる場合、Excel はこの値を数式として解釈します。
values: any[][];プロパティ値
any[][]
注釈
valueTypes
各セル内のデータの種類を指定します。
readonly valueTypes: Excel.RangeValueType[][];プロパティ値
注釈
worksheet
現在の範囲を含んでいるワークシート。
readonly worksheet: Excel.Worksheet;プロパティ値
注釈
メソッドの詳細
clear(applyTo)
範囲の値、書式、塗りつぶし、罫線などをクリアします。
clear(applyTo?: Excel.ClearApplyTo): void;パラメーター
- applyTo
- Excel.ClearApplyTo
省略可能。 クリア操作の種類を決定します。 詳細は「Excel.ClearApplyTo」をご覧ください。
戻り値
void
注釈
例
// 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(applyToString)
範囲の値、書式、塗りつぶし、罫線などをクリアします。
clear(applyToString?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"): void;パラメーター
- applyToString
-
"All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"
省略可能。 クリア操作の種類を決定します。 詳細は「Excel.ClearApplyTo」をご覧ください。
戻り値
void
注釈
delete(shift)
範囲に関連付けられているセルを削除します。
delete(shift: Excel.DeleteShiftDirection): void;パラメーター
セルをシフトする方向を指定します。 詳細は「Excel.DeleteShiftDirection」をご覧ください。
戻り値
void
注釈
例
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(shiftString)
範囲に関連付けられているセルを削除します。
delete(shiftString: "Up" | "Left"): void;パラメーター
- shiftString
-
"Up" | "Left"
セルをシフトする方向を指定します。 詳細は「Excel.DeleteShiftDirection」をご覧ください。
戻り値
void
注釈
getBoundingRect(anotherRange)
指定した範囲を包含する、最小の Range オブジェクトを取得します。 たとえば、"B2:C5" と "D10:E15" の GetBoundingRect は "B2:E15" です。
getBoundingRect(anotherRange: Range | string): Excel.Range;パラメーター
- anotherRange
-
Excel.Range | string
範囲オブジェクト、アドレス、または範囲名。
戻り値
注釈
例
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
});
getCell(row, column)
行と列の番号に基づいて、1 つのセルを含んだ範囲オブジェクトを取得します。 セルは、ワークシートのグリッド内に留まる限り、親範囲の範囲外にすることができます。 返されるセルは、範囲の左上のセルを基準に配置されます。
getCell(row: number, column: number): Excel.Range;パラメーター
- row
-
number
取得するセルの行番号。 0 を起点とする番号になります。
- column
-
number
取得セルの列番号。 0 を起点とする番号になります。
戻り値
注釈
例
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);
});
getColumn(column)
範囲に含まれる列を 1 つ取得します。
getColumn(column: number): Excel.Range;パラメーター
- column
-
number
取得する範囲の列番号。 0 を起点とする番号になります。
戻り値
注釈
例
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
});
getColumnsAfter(count)
現在の Range オブジェクトの右側にある特定の数の列を取得します。
getColumnsAfter(count?: number): Excel.Range;パラメーター
- count
-
number
省略可能。 結果の範囲に含める列の数です。 通常、正の数値を使用して現在の範囲外に範囲を作成します。 負の数値を使用して、現在の範囲内に範囲を作成することもできます。 既定値は 1 です。
戻り値
注釈
getColumnsBefore(count)
現在の Range オブジェクトの左側にある特定の数の列を取得します。
getColumnsBefore(count?: number): Excel.Range;パラメーター
- count
-
number
省略可能。 結果の範囲に含める列の数です。 通常、正の数値を使用して現在の範囲外に範囲を作成します。 負の数値を使用して、現在の範囲内に範囲を作成することもできます。 既定値は 1 です。
戻り値
注釈
getEntireColumn()
範囲の列全体を表すオブジェクトを取得します (たとえば、現在の範囲がセル "B4:E11" を表す場合、その getEntireColumn は列 "B:E" を表す範囲です)。
getEntireColumn(): Excel.Range;戻り値
注釈
例
// 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);
});
getEntireRow()
範囲の行全体を表すオブジェクトを取得します (たとえば、現在の範囲がセル "B4:E11" を表している場合、その GetEntireRow は行 "4:11" を表す範囲です)。
getEntireRow(): Excel.Range;戻り値
注釈
例
// 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);
});
getIntersection(anotherRange)
指定した範囲の長方形の交差を表す範囲オブジェクトを取得します。
getIntersection(anotherRange: Range | string): Excel.Range;パラメーター
- anotherRange
-
Excel.Range | string
範囲の交差を判断するために使用される、Range オブジェクトまたは Range アドレス。
戻り値
注釈
例
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
});
getIntersectionOrNullObject(anotherRange)
指定した範囲の長方形の交差を表す範囲オブジェクトを取得します。 積集合が見つからない場合、このメソッドは isNullObject プロパティを true に設定したオブジェクトを返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
getIntersectionOrNullObject(anotherRange: Range | string): Excel.Range;パラメーター
- anotherRange
-
Excel.Range | string
範囲の交差を判断するために使用される、Range オブジェクトまたは Range アドレス。
戻り値
注釈
例
// 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();
});
getLastCell()
範囲内の最後のセルを取得します。 たとえば、"B2:D5" の最後のセルは "D5" になります。
getLastCell(): Excel.Range;戻り値
注釈
例
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
});
getLastColumn()
範囲内の最後の列を取得します。 たとえば、"B2:D5" の最後の列は "D2:D5" になります。
getLastColumn(): Excel.Range;戻り値
注釈
例
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
});
getLastRow()
範囲内の最後の行を取得します。 たとえば、"B2:D5" の最後の行は "B5:D5" になります。
getLastRow(): Excel.Range;戻り値
注釈
例
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
});
getOffsetRange(rowOffset, columnOffset)
指定した範囲からのオフセットで範囲を表すオブジェクトを取得します。 返される範囲のディメンションは、この範囲と一致します。 結果の範囲がワークシートのグリッドの境界線の外にはみ出る場合は、エラーがスローされます。
getOffsetRange(rowOffset: number, columnOffset: number): Excel.Range;パラメーター
- rowOffset
-
number
範囲をオフセットする行数 (正、負、または 0)。 正の値は下方向、負の値は上方向のオフセットを表します。
- columnOffset
-
number
範囲をオフセットする列の数 (正、負、または 0)。 正の値は右方向、負の値は左方向のオフセットを表します。
戻り値
注釈
例
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
});
getResizedRange(deltaRows, deltaColumns)
現在のRange オブジェクトに似たRange オブジェクトを取得しますが、右下隅を一部の行と列で展開 (または縮小) します。
getResizedRange(deltaRows: number, deltaColumns: number): Excel.Range;パラメーター
- deltaRows
-
number
現在の範囲を基準にして、右下隅を拡張する行の数です。 範囲を拡張するには正の数値、または範囲を縮小するには負の数値を使用します。
- deltaColumns
-
number
現在の範囲を基準にして右下隅を展開する列の数。 範囲を拡張するには正の数値、または範囲を縮小するには負の数値を使用します。
戻り値
注釈
getRow(row)
範囲に含まれている行を 1 つ取得します。
getRow(row: number): Excel.Range;パラメーター
- row
-
number
取得する範囲の行番号。 0 を起点とする番号になります。
戻り値
注釈
例
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
});
getRowsAbove(count)
現在の Range オブジェクトの上にある特定の数の行を取得します。
getRowsAbove(count?: number): Excel.Range;パラメーター
- count
-
number
省略可能。 結果の範囲に含める行の数です。 通常、正の数値を使用して現在の範囲外に範囲を作成します。 負の数値を使用して、現在の範囲内に範囲を作成することもできます。 既定値は 1 です。
戻り値
注釈
getRowsBelow(count)
現在の Range オブジェクトの下にある特定の数の行を取得します。
getRowsBelow(count?: number): Excel.Range;パラメーター
- count
-
number
省略可能。 結果の範囲に含める行の数です。 通常、正の数値を使用して現在の範囲外に範囲を作成します。 負の数値を使用して、現在の範囲内に範囲を作成することもできます。 既定値は 1 です。
戻り値
注釈
getUsedRange(valuesOnly)
指定した範囲オブジェクトのうち使用されている範囲を返します。 範囲内に使用されたセルがない場合、この関数は ItemNotFound エラーをスローします。
getUsedRange(valuesOnly?: boolean): Excel.Range;パラメーター
- valuesOnly
-
boolean
値の入っているセルのみを使用セルと見なします。 [Api set: ExcelApi 1.2]
戻り値
注釈
例
// 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();
});
getUsedRangeOrNullObject(valuesOnly)
指定した範囲オブジェクトのうち使用されている範囲を返します。 範囲内に使用されているセルがない場合、このメソッドは isNullObject プロパティを true に設定したオブジェクトを返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;パラメーター
- valuesOnly
-
boolean
値の入っているセルのみを使用セルと見なします。
戻り値
注釈
例
// 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()
現在の範囲の表示されている行を表します。
getVisibleView(): Excel.RangeView;戻り値
注釈
insert(shift)
この範囲を占めるセルまたはセルの範囲をワークシートに挿入し、領域を空けるために他のセルをシフトします。 現在の空白位置にある新しい Range オブジェクトを返します。
insert(shift: Excel.InsertShiftDirection): Excel.Range;パラメーター
セルをシフトする方向を指定します。 詳細は「Excel.InsertShiftDirection」をご覧ください。
戻り値
注釈
例
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();
});
insert(shiftString)
この範囲を占めるセルまたはセルの範囲をワークシートに挿入し、領域を空けるために他のセルをシフトします。 現在の空白位置にある新しい Range オブジェクトを返します。
insert(shiftString: "Down" | "Right"): Excel.Range;パラメーター
- shiftString
-
"Down" | "Right"
セルをシフトする方向を指定します。 詳細は「Excel.InsertShiftDirection」をご覧ください。
戻り値
注釈
load(options)
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(options?: Excel.Interfaces.RangeLoadOptions): Excel.Range;パラメーター
読み込むオブジェクトのプロパティのオプションを提供します。
戻り値
load(propertyNames)
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(propertyNames?: string | string[]): Excel.Range;パラメーター
- propertyNames
-
string | string[]
読み込むプロパティを指定するコンマ区切り文字列または文字列の配列。
戻り値
例
// 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);
});
load(propertyNamesAndPaths)
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): Excel.Range;パラメーター
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select は読み込むプロパティを指定するコンマ区切りの文字列で、 propertyNamesAndPaths.expand は読み込むナビゲーション プロパティを指定するコンマ区切りの文字列です。
戻り値
merge(across)
範囲内のセルをワークシートの 1 つの領域に結合します。
merge(across?: boolean): void;パラメーター
- across
-
boolean
省略可能。
trueを設定して、指定した範囲の各行のセルを個別の結合セルとして結合します。 既定値は falseです。
戻り値
void
注釈
例
await Excel.run(async (context) => {
const sheetName = "Sheet1";
const rangeAddress = "A1:C3";
const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
range.merge(true);
await context.sync();
});
// 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();
});
select()
Excel UI で指定した範囲を選択します。
select(): void;戻り値
void
注釈
例
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();
});
set(properties, options)
オブジェクトの複数のプロパティを同時に設定します。 適切なプロパティを持つプレーン オブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。
set(properties: Interfaces.RangeUpdateData, options?: OfficeExtension.UpdateOptions): void;パラメーター
- properties
- Excel.Interfaces.RangeUpdateData
メソッドが呼び出されるオブジェクトのプロパティに等形的に構造化されたプロパティを持つ JavaScript オブジェクト。
- options
- OfficeExtension.UpdateOptions
properties オブジェクトが読み取り専用プロパティを設定しようとした場合にエラーを抑制するオプションを提供します。
戻り値
void
set(properties)
既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。
set(properties: Excel.Range): void;パラメーター
- 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();
});
toJSON()
API オブジェクトがJSON.stringify()に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (JSON.stringify、それに渡されるオブジェクトの toJSON メソッドを呼び出します)。元の Excel.Range オブジェクトは API オブジェクトですが、 toJSON メソッドは、元のオブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト ( Excel.Interfaces.RangeData として型指定) を返します。
toJSON(): Excel.Interfaces.RangeData;戻り値
track()
ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを .sync 呼び出しで使用し、".run" バッチのシーケンシャル実行の外部で使用していて、プロパティを設定するとき、またはオブジェクトのメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクト コレクションにオブジェクトを追加する必要があります。
track(): Excel.Range;戻り値
unmerge()
範囲内のセルを結合解除して別々のセルにします。
unmerge(): void;戻り値
void
注釈
例
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();
});
untrack()
前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは 、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();
});
Office Add-ins