Excel.Range class
範囲は、セル、行、列、セルのブロックなど、1 つ以上の連続したセルのセットを表します。 API 全体での範囲の使用方法の詳細については、 Excel JavaScript API の範囲から始めます。
- Extends
注釈
プロパティ
address | 範囲参照を A1 スタイルで指定します。 アドレス値にはシート参照が含まれます (例: "Sheet1!A1:B4")。 |
address |
ユーザーの言語で指定した範囲の範囲参照を表します。 |
cell |
範囲内のセルの数を指定します。 セルの数が 2^31-1 (2,147,483,647) を超えると、この API は -1 を返します。 |
column |
範囲内の列の合計数を指定します。 |
column |
現在の範囲内のすべての列が非表示の場合にを表します。 値は、 |
column |
範囲内の最初のセルの列番号を指定します。 0 を起点とする番号になります。 |
conditional |
範囲と交差する の |
context | オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。 |
data |
dataValidation オブジェクトを返します。 |
format | Format オブジェクト (範囲のフォント、塗りつぶし、罫線、配置などのプロパティをカプセル化するオブジェクト) を返します。 |
formulas | A1 スタイル表記の数式を表します。 セルに数式がない場合は、代わりに値が返されます。 |
formulas |
ユーザーの言語と数値書式ロケールで、A1 スタイル表記の数式を表します。 たとえば、英語の数式 "=SUM(A1, 1.5)" は、ドイツ語では "=SUMME(A1; 1,5)" になります。 セルに数式がない場合は、代わりに値が返されます。 |
formulasR1C1 | R1C1 スタイル表記の数式を表します。 セルに数式がない場合は、代わりに値が返されます。 |
hidden | 現在の範囲内のすべてのセルが非表示かどうかを表します。 値は、 |
hyperlink | 現在の範囲のハイパーリンクを表します。 |
is |
現在の範囲が列全体であるかどうかを表します。 |
is |
現在の範囲が行全体であるかどうかを表します。 |
linked |
各セルのデータ型の状態を表します。 |
number |
指定した範囲の Excel の数値書式コードを表します。 Excel の数値書式の詳細については、「数値書式 コード」を参照してください。 |
number |
ユーザーの言語設定に基づいて、指定した範囲の Excel の数値書式コードを表します。 プロパティの取得または設定時に、Excel では言語や書式の強制は |
row |
範囲に含まれる行の合計数を返します。 |
row |
現在の範囲内のすべての行が非表示になっているかどうかを表します。 値は、 |
row |
範囲に含まれる最初のセルの行番号を返します。 0 を起点とする番号になります。 |
sort | 現在の範囲について、範囲の並べ替えを表します。 |
style | 現在の範囲のスタイルを表します。 セルのスタイルに一貫性がない場合は、 |
text | 指定した範囲のテキスト値。 テキスト値は、セルの幅には依存しません。 Excel UI で発生する数値記号 (#) の置換は、API によって返されるテキスト値には影響しません。 |
values | 指定した範囲の Raw 値を表します。 返されるデータは、文字列、数値、またはブール値のいずれかです。 エラーが含まれているセルは、エラー文字列を返します。 返される値が正符号 ("+")、マイナス ("-")、または等号 ("=") で始まる場合、Excel はこの値を数式として解釈します。 |
value |
各セル内のデータの種類を指定します。 |
worksheet | 現在の範囲を含んでいるワークシート。 |
メソッド
auto |
指定したオートフィル ロジックを使用して、現在の範囲からターゲット範囲までの範囲を入力します。 変換先の範囲は 詳細については、「 オートフィルとフラッシュ フィルを使用する」を参照してください。 |
auto |
指定したオートフィル ロジックを使用して、現在の範囲からターゲット範囲までの範囲を入力します。 変換先の範囲は 詳細については、「 オートフィルとフラッシュ フィルを使用する」を参照してください。 |
calculate() | ワークシート上のセルの範囲を計算します。 |
clear(apply |
範囲の値、書式、塗りつぶし、罫線などをクリアします。 |
clear(apply |
範囲の値、書式、塗りつぶし、罫線などをクリアします。 |
convert |
データ型を持つ範囲セルをテキストに変換します。 |
convert |
範囲セルをワークシート内のリンクされたデータ型に変換します。 |
copy |
セル データまたは書式をソース範囲または |
copy |
セル データまたは書式をソース範囲または |
delete(shift) | 範囲に関連付けられているセルを削除します。 |
delete(shift |
範囲に関連付けられているセルを削除します。 |
find(text, criteria) | 指定された条件に基づいて指定された文字列を見つけます。 現在の範囲が 1 つのセルより大きい場合、検索はその範囲に制限されます。それ以外の場合、検索はそのセルの後から始まるシート全体をカバーします。 |
find |
指定された条件に基づいて指定された文字列を見つけます。 現在の範囲が 1 つのセルより大きい場合、検索はその範囲に制限されます。それ以外の場合、検索はそのセルの後から始まるシート全体をカバーします。 一致が見つからない場合、このメソッドは プロパティが に設定されたオブジェクトを |
flash |
現在の範囲にフラッシュフィルを実行します。 パターンを検出すると、フラッシュ フィルによってデータが自動的に塗りつぶされるため、パターンを見つけるには、範囲が 1 つの列範囲で、周囲にデータが含まれている必要があります。 |
get |
現在 |
get |
指定した範囲を包含する、最小の Range オブジェクトを取得します。 たとえば、 |
get |
行と列の番号に基づいて、1 つのセルを含んだ範囲オブジェクトを取得します。 セルは、ワークシートのグリッド内に留まる限り、親範囲の範囲外にすることができます。 返されるセルは、範囲の左上のセルを基準に配置されます。 |
get |
2D 配列を返します。各セルのフォント、塗りつぶし、罫線、配置などのプロパティ データをカプセル化します。 |
get |
範囲に含まれる列を 1 つ取得します。 |
get |
一次元配列を返します。各列のフォント、塗りつぶし、罫線、配置などのプロパティ データをカプセル化します。 指定された列内の列間で一貫性のないプロパティについては、null が返されます。 |
get |
現在 |
get |
現在 |
get |
範囲の列全体を表すオブジェクトを取得します (たとえば、現在の範囲がセル "B4:E11" を表す場合、その |
get |
範囲の行全体を表すオブジェクトを取得します (たとえば、現在の範囲がセル "B4:E11" を表す場合、その |
get |
範囲を base64 でエンコードされた png イメージとしてレンダリングします。 重要*: この API は現在、Excel for Macではサポートされていません。 現在の状態については、「 OfficeDev/office-js Issue #235 」を参照してください。 |
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 |
指定した型と値に |
get |
指定した型と値に |
get |
指定した型と値に |
get |
この範囲内の |
get |
範囲と重なるテーブルの集まりを範囲限定で取得します。 |
get |
指定した範囲オブジェクトのうち使用されている範囲を返します。 範囲内に使用されているセルがない場合、この関数はエラーを |
get |
指定した範囲オブジェクトのうち使用されている範囲を返します。 範囲内に使用されているセルがない場合、このメソッドは プロパティが に設定されたオブジェクトを |
get |
現在の範囲の表示されている行を表します。 |
insert(shift) | この範囲を占めるセルまたはセルの範囲をワークシートに挿入し、領域を空けるために他のセルをシフトします。 空き領域の新しい |
insert(shift |
この範囲を占めるセルまたはセルの範囲をワークシートに挿入し、領域を空けるために他のセルをシフトします。 空き領域の新しい |
load(options) | オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
load(property |
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
load(property |
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
merge(across) | 範囲内のセルをワークシートの 1 つの領域に結合します。 |
remove |
列によって指定される範囲から重複する値を削除します。 |
replace |
現在の範囲内で、指定された条件に基づき、指定された文字列を検索し、置換します。 |
select() | Excel UI で指定した範囲を選択します。 |
set(properties, options) | オブジェクトの複数のプロパティを同時に設定します。 適切なプロパティを持つプレーン オブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。 |
set(properties) | 既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。 |
set |
セル プロパティの 2D 配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。 |
set |
列プロパティの 1 次元配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。 |
set |
次の再計算が発生したときに再計算する範囲を設定します。 |
set |
行プロパティの 1 次元配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。 |
show |
アクティブ セルに多数の値が含まれる場合、そのセルのカードを表示します。 |
toJSON() | API オブジェクトが に渡されたときにより便利な出力を提供するために、JavaScript |
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
注釈
conditionalFormats
範囲と交差する の ConditionalFormats
コレクション。
readonly conditionalFormats: Excel.ConditionalFormatCollection;
プロパティ値
注釈
context
オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。
context: RequestContext;
プロパティ値
dataValidation
dataValidation オブジェクトを返します。
readonly dataValidation: Excel.DataValidation;
プロパティ値
注釈
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
注釈
hyperlink
現在の範囲のハイパーリンクを表します。
hyperlink: Excel.RangeHyperlink;
プロパティ値
注釈
例
// 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();
});
isEntireColumn
現在の範囲が列全体であるかどうかを表します。
readonly isEntireColumn: boolean;
プロパティ値
boolean
注釈
isEntireRow
linkedDataTypeState
各セルのデータ型の状態を表します。
readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];
プロパティ値
注釈
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);
});
numberFormatLocal
ユーザーの言語設定に基づいて、指定した範囲の Excel の数値書式コードを表します。 プロパティの取得または設定時に、Excel では言語や書式の強制は numberFormatLocal
実行されません。 返されるテキストは、システム設定で指定された言語に基づいて、ローカル形式の文字列を使用します。
numberFormatLocal: any[][];
プロパティ値
any[][]
注釈
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();
});
}
style
現在の範囲のスタイルを表します。 セルのスタイルに一貫性がない場合は、 null
が返されます。 カスタム スタイルの場合、スタイル名が返されます。 組み込みのスタイルの場合、列挙型の BuiltInStyle
値を表す文字列が返されます。
style: string;
プロパティ値
string
注釈
例
// 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();
});
text
指定した範囲のテキスト値。 テキスト値は、セルの幅には依存しません。 Excel UI で発生する数値記号 (#) の置換は、API によって返されるテキスト値には影響しません。
readonly text: string[][];
プロパティ値
string[][]
注釈
values
指定した範囲の Raw 値を表します。 返されるデータは、文字列、数値、またはブール値のいずれかです。 エラーが含まれているセルは、エラー文字列を返します。 返される値が正符号 ("+")、マイナス ("-")、または等号 ("=") で始まる場合、Excel はこの値を数式として解釈します。
values: any[][];
プロパティ値
any[][]
注釈
valueTypes
各セル内のデータの種類を指定します。
readonly valueTypes: Excel.RangeValueType[][];
プロパティ値
注釈
worksheet
現在の範囲を含んでいるワークシート。
readonly worksheet: Excel.Worksheet;
プロパティ値
注釈
メソッドの詳細
autoFill(destinationRange, autoFillType)
指定したオートフィル ロジックを使用して、現在の範囲からターゲット範囲までの範囲を入力します。 変換先の範囲は null
、ソース範囲を水平方向または垂直方向に拡張できます。 連続しない範囲はサポートされていません。
詳細については、「 オートフィルとフラッシュ フィルを使用する」を参照してください。
autoFill(destinationRange?: Range | string, autoFillType?: Excel.AutoFillType): void;
パラメーター
- destinationRange
-
Excel.Range | string
変換先の範囲をオートフィルします。 変換先の範囲が の場合、 null
周囲のセルに基づいてデータが入力されます (UI の範囲の塗りつぶしハンドルをダブルクリックしたときの動作)。
- autoFillType
- Excel.AutoFillType
オートフィルの種類。 現在の範囲の内容に基づいて、変換先の範囲を入力する方法を指定します。 既定値は "FillDefault" です。
戻り値
void
注釈
[ API セット: ExcelApi 1.9, ExcelApi Preview for null 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();
});
autoFill(destinationRange, autoFillTypeString)
指定したオートフィル ロジックを使用して、現在の範囲からターゲット範囲までの範囲を入力します。 変換先の範囲は null
、ソース範囲を水平方向または垂直方向に拡張できます。 連続しない範囲はサポートされていません。
詳細については、「 オートフィルとフラッシュ フィルを使用する」を参照してください。
autoFill(destinationRange?: Range | string, autoFillTypeString?: "FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"): void;
パラメーター
- destinationRange
-
Excel.Range | string
変換先の範囲をオートフィルします。 変換先の範囲が の場合、 null
周囲のセルに基づいてデータが入力されます (UI の範囲の塗りつぶしハンドルをダブルクリックしたときの動作)。
- autoFillTypeString
-
"FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"
オートフィルの種類。 現在の範囲の内容に基づいて、変換先の範囲を入力する方法を指定します。 既定値は "FillDefault" です。
戻り値
void
注釈
[ API セット: ExcelApi 1.9, ExcelApi Preview for null destinationRange
]
calculate()
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
注釈
convertDataTypeToText()
convertToLinkedDataType(serviceID, languageCulture)
範囲セルをワークシート内のリンクされたデータ型に変換します。
convertToLinkedDataType(serviceID: number, languageCulture: string): void;
パラメーター
- serviceID
-
number
データのクエリに使用されるサービス ID。
- languageCulture
-
string
サービスのクエリを実行する言語カルチャ。
戻り値
void
注釈
copyFrom(sourceRange, copyType, skipBlanks, transpose)
セル データまたは書式をソース範囲または RangeAreas
現在の範囲にコピーします。 変換先の範囲は、ソース範囲または RangeAreas
とは異なるサイズにすることができます。 変換先がソースより小さい場合は、自動的に展開されます。 注: Excel UI のコピー機能と同様に、コピー先の範囲が行または列のソース範囲を超える正確な倍数である場合、ソース コンテンツは複数回レプリケートされます。 たとえば、2x2 範囲を 2x6 範囲にコピーすると、元の 2x2 範囲のコピーが 3 つになります。
copyFrom(sourceRange: Range | RangeAreas | string, copyType?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;
パラメーター
- sourceRange
-
Excel.Range | Excel.RangeAreas | string
コピー元の範囲または RangeAreas
コピー元の範囲。 ソース RangeAreas
に複数の範囲がある場合は、四角形の範囲から完全な行または列を削除して、フォームを作成できる必要があります。
- copyType
- Excel.RangeCopyType
コピーするセル データまたは書式設定の種類。 既定値は "All" です。
- skipBlanks
-
boolean
True を指定すると、ソース範囲の空白セルがスキップされます。 既定値は false です。
- transpose
-
boolean
True の場合は、変換先の範囲内のセルを置き換えます。 既定値は false です。
戻り値
void
注釈
例
// 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();
});
copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)
セル データまたは書式をソース範囲または RangeAreas
現在の範囲にコピーします。 変換先の範囲は、ソース範囲または RangeAreas
とは異なるサイズにすることができます。 変換先がソースより小さい場合は、自動的に展開されます。 注: Excel UI のコピー機能と同様に、コピー先の範囲が行または列のソース範囲を超える正確な倍数である場合、ソース コンテンツは複数回レプリケートされます。 たとえば、2x2 範囲を 2x6 範囲にコピーすると、元の 2x2 範囲のコピーが 3 つになります。
copyFrom(sourceRange: Range | RangeAreas | string, copyTypeString?: "All" | "Formulas" | "Values" | "Formats" | "Link", skipBlanks?: boolean, transpose?: boolean): void;
パラメーター
- sourceRange
-
Excel.Range | Excel.RangeAreas | string
コピー元の範囲または RangeAreas
コピー元の範囲。 ソース RangeAreas
に複数の範囲がある場合は、四角形の範囲から完全な行または列を削除して、フォームを作成できる必要があります。
- copyTypeString
-
"All" | "Formulas" | "Values" | "Formats" | "Link"
コピーするセル データまたは書式設定の種類。 既定値は "All" です。
- skipBlanks
-
boolean
True を指定すると、ソース範囲の空白セルがスキップされます。 既定値は false です。
- transpose
-
boolean
True の場合は、変換先の範囲内のセルを置き換えます。 既定値は false です。
戻り値
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
注釈
find(text, criteria)
指定された条件に基づいて指定された文字列を見つけます。 現在の範囲が 1 つのセルより大きい場合、検索はその範囲に制限されます。それ以外の場合、検索はそのセルの後から始まるシート全体をカバーします。
find(text: string, criteria: Excel.SearchCriteria): Excel.Range;
パラメーター
- text
-
string
検索する文字列。
- criteria
- Excel.SearchCriteria
検索の方向や、検索がセル全体と一致する必要があるか、大文字と小文字が区別されるかなど、追加の検索条件。
戻り値
Range
検索テキストと条件に一致する値を含む最初のセルを表す オブジェクト。
注釈
例
// 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 foundRange = searchRange.find($("#searchText").val().toString(), {
completeMatch: isCompleteMatchToggle,
matchCase: isMatchCaseToggle,
searchDirection: searchDirectionToggle
});
foundRange.load("address");
await context.sync();
console.log(foundRange.address);
});
findOrNullObject(text, criteria)
指定された条件に基づいて指定された文字列を見つけます。 現在の範囲が 1 つのセルより大きい場合、検索はその範囲に制限されます。それ以外の場合、検索はそのセルの後から始まるシート全体をカバーします。 一致が見つからない場合、このメソッドは プロパティが に設定されたオブジェクトをisNullObject
true
返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
findOrNullObject(text: string, criteria: Excel.SearchCriteria): Excel.Range;
パラメーター
- text
-
string
検索する文字列。
- criteria
- Excel.SearchCriteria
検索の方向や、検索がセル全体と一致する必要があるか、大文字と小文字が区別されるかなど、追加の検索条件。
戻り値
Range
検索条件に一致した 。
注釈
例
// 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 foundRange = searchRange.findOrNullObject($("#searchText").val().toString(), {
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);
}
});
flashFill()
現在の範囲にフラッシュフィルを実行します。 パターンを検出すると、フラッシュ フィルによってデータが自動的に塗りつぶされるため、パターンを見つけるには、範囲が 1 つの列範囲で、周囲にデータが含まれている必要があります。
flashFill(): void;
戻り値
void
注釈
getAbsoluteResizedRange(numRows, numColumns)
現在Range
のRange
オブジェクトと同じ左上のセルを持ち、指定した行数と列数を持つオブジェクトを取得します。
getAbsoluteResizedRange(numRows: number, numColumns: number): Excel.Range;
パラメーター
- numRows
-
number
新しい範囲サイズの行数。
- numColumns
-
number
新しい範囲サイズの列数。
戻り値
注釈
getBoundingRect(anotherRange)
指定した範囲を包含する、最小の Range オブジェクトを取得します。 たとえば、 GetBoundingRect
"B2:C5" と "D10:E15" の は "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);
});
getCellProperties(cellPropertiesLoadOptions)
2D 配列を返します。各セルのフォント、塗りつぶし、罫線、配置などのプロパティ データをカプセル化します。
getCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;
パラメーター
- cellPropertiesLoadOptions
- Excel.CellPropertiesLoadOptions
読み込むセル プロパティを表す オブジェクト。
戻り値
各項目が対応するセルの要求されたプロパティを表す 2D 配列。
注釈
例
// 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();
// Define the cell properties to get by setting the matching LoadOptions to true.
const propertiesToGet = cell.getCellProperties({
address: true,
format: {
fill: {
color: true
},
font: {
color: true
}
},
style: true
});
// Sync to get the data from the workbook.
await context.sync();
const cellProperties = propertiesToGet.value[0][0];
console.log(
`Address: ${cellProperties.address}\nStyle: ${cellProperties.style}\nFill Color: ${cellProperties.format.fill.color}\nFont Color: ${cellProperties.format.font.color}`);
});
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
});
getColumnProperties(columnPropertiesLoadOptions)
一次元配列を返します。各列のフォント、塗りつぶし、罫線、配置などのプロパティ データをカプセル化します。 指定された列内の列間で一貫性のないプロパティについては、null が返されます。
getColumnProperties(columnPropertiesLoadOptions: ColumnPropertiesLoadOptions): OfficeExtension.ClientResult<ColumnProperties[]>;
パラメーター
- columnPropertiesLoadOptions
- Excel.ColumnPropertiesLoadOptions
読み込む列プロパティを表す オブジェクト。
戻り値
各項目が対応する列の要求されたプロパティを表す配列。
注釈
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);
});
getImage()
範囲を base64 でエンコードされた png イメージとしてレンダリングします。 重要*: この API は現在、Excel for Macではサポートされていません。 現在の状態については、「 OfficeDev/office-js Issue #235 」を参照してください。
getImage(): OfficeExtension.ClientResult<string>;
戻り値
OfficeExtension.ClientResult<string>
注釈
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
});
getRowProperties(rowPropertiesLoadOptions)
一次元配列を返します。各行のフォント、塗りつぶし、罫線、配置などのプロパティ データをカプセル化します。 特定の行内の各セル間で一貫性のないプロパティの場合は、 null
が返されます。
getRowProperties(rowPropertiesLoadOptions: RowPropertiesLoadOptions): OfficeExtension.ClientResult<RowProperties[]>;
パラメーター
- rowPropertiesLoadOptions
- Excel.RowPropertiesLoadOptions
読み込む行プロパティを表す オブジェクト。
戻り値
各項目が、対応する行の要求されたプロパティを表す配列。
注釈
getRowsAbove(count)
現在 Range
のオブジェクトの上にある特定の数の行を取得します。
getRowsAbove(count?: number): Excel.Range;
パラメーター
- count
-
number
オプション。 結果の範囲に含める行の数です。 通常、正の数値を使用して現在の範囲外に範囲を作成します。 負の数値を使用して、現在の範囲内に範囲を作成することもできます。 既定値は 1 です。
戻り値
注釈
getRowsBelow(count)
現在 Range
のオブジェクトの下にある特定の数の行を取得します。
getRowsBelow(count?: number): Excel.Range;
パラメーター
- count
-
number
オプション。 結果の範囲に含める行の数です。 通常、正の数値を使用して現在の範囲外に範囲を作成します。 負の数値を使用して、現在の範囲内に範囲を作成することもできます。 既定値は 1 です。
戻り値
注釈
getSpecialCells(cellType, cellValueType)
指定した型と値に RangeAreas
一致するすべてのセルを表す 1 つまたは複数の四角形の範囲を含むオブジェクトを取得します。 特殊なセルが見つからない場合は、 ItemNotFound
エラーがスローされます。
getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;
パラメーター
- cellType
- Excel.SpecialCellType
含めるセルの種類。
- cellValueType
- Excel.SpecialCellValueType
が または formulas
のconstants
場合cellType
、この引数を使用して、結果に含めるセルの種類を決定します。 これらの値を組み合わせて、複数の型を返すことができます。 この引数を省略すると、すべての定数および数式が対象になります。
戻り値
注釈
例
// 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();
});
getSpecialCells(cellTypeString, cellValueTypeString)
指定した型と値に RangeAreas
一致するすべてのセルを表す 1 つまたは複数の四角形の範囲を含むオブジェクトを取得します。 特殊なセルが見つからない場合は、 ItemNotFound
エラーがスローされます。
getSpecialCells(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;
パラメーター
- cellTypeString
-
"ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible"
含めるセルの種類。
- cellValueTypeString
-
"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"
が または formulas
のconstants
場合cellType
、この引数を使用して、結果に含めるセルの種類を決定します。 これらの値を組み合わせて、複数の型を返すことができます。 この引数を省略すると、すべての定数および数式が対象になります。
戻り値
注釈
getSpecialCellsOrNullObject(cellType, cellValueType)
指定した型と値に RangeAreas
一致するすべてのセルを表す 1 つ以上の範囲を含むオブジェクトを取得します。 特殊なセルが見つからない場合、このメソッドは プロパティが に設定されたオブジェクトをisNullObject
true
返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;
パラメーター
- cellType
- Excel.SpecialCellType
含めるセルの種類。
- cellValueType
- Excel.SpecialCellValueType
が または formulas
のconstants
場合cellType
、この引数を使用して、結果に含めるセルの種類を決定します。 これらの値を組み合わせて、複数の型を返すことができます。 この引数を省略すると、すべての定数および数式が対象になります。
戻り値
注釈
getSpecialCellsOrNullObject(cellTypeString, cellValueTypeString)
指定した型と値に RangeAreas
一致するすべてのセルを表す 1 つ以上の範囲を含むオブジェクトを取得します。 特殊なセルが見つからない場合、このメソッドは プロパティが に設定されたオブジェクトをisNullObject
true
返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。
getSpecialCellsOrNullObject(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;
パラメーター
- cellTypeString
-
"ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible"
含めるセルの種類。
- cellValueTypeString
-
"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"
が または formulas
のconstants
場合cellType
、この引数を使用して、結果に含めるセルの種類を決定します。 これらの値を組み合わせて、複数の型を返すことができます。 この引数を省略すると、すべての定数および数式が対象になります。
戻り値
注釈
getSurroundingRegion()
この範囲内の Range
左上のセルの周囲の領域を表す オブジェクトを返します。 周囲の領域は、この範囲に相対の空白の行と空白の列の任意の組み合わせで囲まれた範囲です。
getSurroundingRegion(): Excel.Range;
戻り値
注釈
getTables(fullyContained)
範囲と重なるテーブルの集まりを範囲限定で取得します。
getTables(fullyContained?: boolean): Excel.TableScopedCollection;
パラメーター
- fullyContained
-
boolean
の場合 true
は、範囲の境界内に完全に含まれるテーブルのみが返されます。 既定値は です false
。
戻り値
注釈
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();
});
removeDuplicates(columns, includesHeader)
列によって指定される範囲から重複する値を削除します。
removeDuplicates(columns: number[], includesHeader: boolean): Excel.RemoveDuplicatesResult;
パラメーター
- columns
-
number[]
重複を含む可能性がある範囲内の列。 少なくとも 1 つの列を指定する必要があります。 0 を起点とする番号になります。
- includesHeader
-
boolean
True を指定すると、入力データにヘッダーが含まれます。 既定値は false です。
戻り値
削除された行数と残りの一意の行数を格納する結果のオブジェクト。
注釈
例
// 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, replacement, criteria)
現在の範囲内で、指定された条件に基づき、指定された文字列を検索し、置換します。
replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;
パラメーター
- text
-
string
検索する文字列。
- replacement
-
string
元の文字列を置き換える文字列。
- criteria
- Excel.ReplaceCriteria
追加の置き換え条件。
戻り値
OfficeExtension.ClientResult<number>
実行された置換の数。
注釈
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();
});
setCellProperties(cellPropertiesData)
セル プロパティの 2D 配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。
setCellProperties(cellPropertiesData: SettableCellProperties[][]): void;
パラメーター
- cellPropertiesData
各セルで設定するプロパティを表す 2D 配列。
戻り値
void
注釈
例
// 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();
// Creating the SettableCellProperties objects to use for the range.
// In your add-in, these should be created once, outside the function.
const topHeaderProps: Excel.SettableCellProperties = {
// The style property takes a string matching the name of an Excel style.
// Built-in style names are listed in the `BuiltInStyle` enum.
// Note that a style will overwrite any formatting,
// so do not use the format property with the style property.
style: "Heading1"
};
const headerProps: Excel.SettableCellProperties = {
// Any subproperties of format that are not set will not be changed when these cell properties are set.
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
}
}
}
};
const range = sheet.getRange("A1:E5");
// You can use empty JSON objects to avoid changing a cell's properties.
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();
});
setColumnProperties(columnPropertiesData)
列プロパティの 1 次元配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。
setColumnProperties(columnPropertiesData: SettableColumnProperties[]): void;
パラメーター
- columnPropertiesData
各列に設定するプロパティを表す配列。
戻り値
void
注釈
setDirty()
setRowProperties(rowPropertiesData)
行プロパティの 1 次元配列に基づいて範囲を更新し、フォント、塗りつぶし、罫線、配置などをカプセル化します。
setRowProperties(rowPropertiesData: SettableRowProperties[]): void;
パラメーター
- rowPropertiesData
各行に設定するプロパティを表す配列。
戻り値
void
注釈
showCard()
toJSON()
API オブジェクトが に渡されたときにより便利な出力を提供するために、JavaScript toJSON()
メソッドを JSON.stringify()
オーバーライドします。 (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
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示