Excel.Range class

参考

包:: excel

Range 表示一组或多个连续单元格，例如单元格、行、列或单元格块。若要详细了解如何在整个 API 中使用区域，请从 Excel JavaScript API 中的范围开始。

扩展: OfficeExtension.ClientObject

注解

示例

// 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“) 。
addressLocal	表示用户语言中指定范围的范围引用。
cellCount	指定区域中的单元格数。如果单元格数超过 2^31-1 (2,147,483,647)，此 API 返回 -1。
columnCount	指定区域中的列总数。
columnHidden	表示当前范围中的所有列是否处于隐藏状态。 `true`当一个区域中的所有列都隐藏时，值。 `false`当区域中没有列处于隐藏状态时，该值为。 `null`当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时，该值表示。
columnIndex	指定区域中第一个单元格的列号。从零开始编制索引。
context	与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。
format	返回一个格式对象，其中封装了区域的字体、填充、边框、对齐方式和其他属性。
formulas	表示采用 A1 表示法的公式。如果单元格没有公式，则返回其值。
formulasLocal	表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果单元格没有公式，则返回其值。
formulasR1C1	表示采用 R1C1 样式表示法的公式。如果单元格没有公式，则返回其值。
hidden	表示当前区域中的所有单元格是否处于隐藏状态。值是 `true` 隐藏区域中的所有单元格时。 `false`当区域中没有单元格被隐藏时，值。 `null`当某个区域中的某些单元格处于隐藏状态，而同一区域中的其他单元格未隐藏时，值表示。
numberFormat	表示给定区域的 Excel 数字格式代码。有关 Excel 数字格式的详细信息，请参阅数字格式代码。
rowCount	返回区域中的总行数。
rowHidden	表示当前范围中的所有行是否处于隐藏状态。值是 `true` 隐藏范围中的所有行时。 `false`当区域中没有隐藏行时，值。 `null`当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时，该值表示。
rowIndex	返回区域中第一个单元格的行编号。从零开始编制索引。
sort	表示当前 range 的区域排序。
text	指定区域的文本值。文本值与单元格宽度无关。 Excel UI 中发生的数字符号 (#) 替换不会影响 API 返回的文本值。
values	表示指定区域的原始值。返回的数据可以是字符串、数字或布尔值。包含错误的单元格将返回错误字符串。如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。
valueTypes	指定每个单元格中的数据类型。
worksheet	包含当前区域的工作表。

方法

clear(applyTo)	清除区域值、格式、填充、边框等。
clear(applyToString)	清除区域值、格式、填充、边框等。
delete(shift)	删除与区域相关的单元格。
delete(shiftString)	删除与区域相关的单元格。
getBoundingRect(anotherRange)	获取包含指定区域的最小 range 对象。例如， `GetBoundingRect` “B2：C5”和“D10：E15”的为“B2：E15”。
getCell(row, column)	根据行和列编号获取包含单个单元格的 range 对象。单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。返回的单元格位于相对于区域左上角的单元格的位置。
getColumn(column)	获取范围中包含的列。
getColumnsAfter(count)	获取当前 `Range` 对象右侧的一定数量的列。
getColumnsBefore(count)	获取当前 `Range` 对象左侧的一定数量的列。
getEntireColumn()	获取一个对象，该对象表示区域 (的整个列，例如，如果当前区域表示单元格“B4：E11”，则它是 `getEntireColumn` 表示列“B：E”) 的区域。
getEntireRow()	获取一个对象，该对象表示区域 (的整行，例如，如果当前区域表示单元格“B4：E11”，则它是 `GetEntireRow` 表示行“4：11”) 的区域。
getIntersection(anotherRange)	获取表示指定区域的矩形交集的 range 对象。
getIntersectionOrNullObject(anotherRange)	获取表示指定区域的矩形交集的 range 对象。如果未找到交集，则此方法返回一个对象，其 `isNullObject` 属性设置为 `true`。有关详细信息，请参阅 *OrNullObject 方法和属性。
getLastCell()	获取区域内的最后一个单元格。例如，“B2:D5”的最后一个单元格是“D5”。
getLastColumn()	获取区域内的最后一列。例如，“B2:D5”的最后一列是“D2:D5”。
getLastRow()	获取区域内的最后一行。例如，“B2:D5”的最后一行是“B5:D5”。
getOffsetRange(rowOffset, columnOffset)	获取表示与指定区域偏移的区域的对象。返回的区域的尺寸将与此区域一致。如果强制在工作表网格的边界之外生成区域，将引发错误。
getResizedRange(deltaRows, deltaColumns)	获取与 `Range` 当前 `Range` 对象类似的对象，但其右下角展开 (或按行和列数收缩) 。
getRow(row)	获取范围中包含的行。
getRowsAbove(count)	获取当前 `Range` 对象上方的一定行数。
getRowsBelow(count)	获取当前 `Range` 对象下面的特定行数。
getUsedRange(valuesOnly)	返回指定 range 对象的所用区域。如果区域中没有使用的单元格，则此函数将引发错误 `ItemNotFound` 。
getUsedRangeOrNullObject(valuesOnly)	返回指定 range 对象的所用区域。如果区域中没有已用单元格，则此方法返回一个对象，其 `isNullObject` 属性设置为 `true`。有关详细信息，请参阅 *OrNullObject 方法和属性。
getVisibleView()	表示当前 range 对象的可见行。
insert(shift)	将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。返回现在空白处的新 `Range` 对象。
insert(shiftString)	将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。返回现在空白处的新 `Range` 对象。
load(options)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNames)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNamesAndPaths)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
merge(across)	将范围单元格合并到工作表的一个区域内。
select()	在 Excel UI 中选择指定的区域。
set(properties, options)	同时设置对象的多个属性。可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。
set(properties)	基于现有的已加载对象，同时对对象设置多个属性。
toJSON()	重写 JavaScript `toJSON()` 方法，以便在将 API 对象传递给 `JSON.stringify()`时提供更有用的输出。 `JSON.stringify` (，反过来又调用`toJSON`传递给它的对象的方法。) 而原始 Excel.Range 对象是 API 对象，`toJSON`该方法返回一个纯 JavaScript 对象， (类型为 `Excel.Interfaces.RangeData`) ，其中包含原始对象中加载的任何子属性的浅表副本。
track()	根据文档中的相应更改来跟踪对象，以便进行自动调整。此调用是 context.trackedObjects.add (thisObject) 的简写。如果跨 `.sync` 调用和在“.run”批处理的顺序执行之外使用此对象，并在设置属性或调用对象方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将该对象添加到跟踪的对象集合。
unmerge()	将范围单元格取消合并为各个单元格。
untrack()	释放与此对象关联的内存（如果先前已跟踪过）。此调用是 context.trackedObjects.remove (thisObject) 的简写。拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。在内存释放生效之前，需要调用。`context.sync()`

属性详细信息

address

指定 A1 样式中的区域引用。地址值包含工作表引用 (例如“Sheet1！A1：B4“) 。

readonly address: string;

属性值

string

注解

[ API 集：ExcelApi 1.1 ]

addressLocal

表示用户语言中指定范围的范围引用。

readonly addressLocal: string;

属性值

string

注解

[ API 集：ExcelApi 1.1 ]

cellCount

指定区域中的单元格数。如果单元格数超过 2^31-1 (2,147,483,647)，此 API 返回 -1。

readonly cellCount: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

columnCount

指定区域中的列总数。

readonly columnCount: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

columnHidden

表示当前范围中的所有列是否处于隐藏状态。 true当一个区域中的所有列都隐藏时，值。 false当区域中没有列处于隐藏状态时，该值为。 null当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时，该值表示。

columnHidden: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.2 ]

columnIndex

指定区域中第一个单元格的列号。从零开始编制索引。

readonly columnIndex: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

context

与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

Excel.RequestContext

format

返回一个格式对象，其中封装了区域的字体、填充、边框、对齐方式和其他属性。

readonly format: Excel.RangeFormat;

属性值

Excel.RangeFormat

注解

[ API 集：ExcelApi 1.1 ]

formulas

表示采用 A1 表示法的公式。如果单元格没有公式，则返回其值。

formulas: any[][];

属性值

any[][]

注解

[ API 集：ExcelApi 1.1 ]

formulasLocal

表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果单元格没有公式，则返回其值。

formulasLocal: any[][];

属性值

any[][]

注解

[ API 集：ExcelApi 1.1 ]

formulasR1C1

表示采用 R1C1 样式表示法的公式。如果单元格没有公式，则返回其值。

formulasR1C1: any[][];

属性值

any[][]

注解

[ API 集：ExcelApi 1.2 ]

hidden

表示当前区域中的所有单元格是否处于隐藏状态。值是 true 隐藏区域中的所有单元格时。 false当区域中没有单元格被隐藏时，值。 null当某个区域中的某些单元格处于隐藏状态，而同一区域中的其他单元格未隐藏时，值表示。

readonly hidden: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.2 ]

numberFormat

表示给定区域的 Excel 数字格式代码。有关 Excel 数字格式的详细信息，请参阅数字格式代码。

numberFormat: any[][];

属性值

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);
});

rowCount

返回区域中的总行数。

readonly rowCount: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

rowHidden

表示当前范围中的所有行是否处于隐藏状态。值是 true 隐藏范围中的所有行时。 false当区域中没有隐藏行时，值。 null当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时，该值表示。

rowHidden: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.2 ]

rowIndex

返回区域中第一个单元格的行编号。从零开始编制索引。

readonly rowIndex: number;

属性值

number

注解

[ API 集：ExcelApi 1.1 ]

sort

表示当前 range 的区域排序。

readonly sort: Excel.RangeSort;

属性值

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();
    });
}

text

指定区域的文本值。文本值与单元格宽度无关。 Excel UI 中发生的数字符号 (#) 替换不会影响 API 返回的文本值。

readonly text: string[][];

属性值

string[][]

注解

[ API 集：ExcelApi 1.1 ]

values

表示指定区域的原始值。返回的数据可以是字符串、数字或布尔值。包含错误的单元格将返回错误字符串。如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。

values: any[][];

属性值

any[][]

注解

[ API 集：ExcelApi 1.1 ]

valueTypes

指定每个单元格中的数据类型。

readonly valueTypes: Excel.RangeValueType[][];

属性值

Excel.RangeValueType[][]

注解

[ API 集：ExcelApi 1.1 ]

worksheet

包含当前区域的工作表。

readonly worksheet: Excel.Worksheet;

属性值

Excel.Worksheet

注解

[ API 集：ExcelApi 1.1 ]

方法详细信息

clear(applyTo)

清除区域值、格式、填充、边框等。

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

参数

applyTo: Excel.ClearApplyTo

可选。确定清除操作的类型。有关详细信息，请参阅 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(applyToString)

清除区域值、格式、填充、边框等。

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

参数

applyToString: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"

可选。确定清除操作的类型。有关详细信息，请参阅 Excel.ClearApplyTo。

void

注解

[ API 集：ExcelApi 1.1 ]

delete(shift)

删除与区域相关的单元格。

delete(shift: Excel.DeleteShiftDirection): void;

参数

shift: Excel.DeleteShiftDirection

指定移动单元格的方式。有关详细信息，请参阅 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(shiftString)

删除与区域相关的单元格。

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

参数

shiftString: "Up" | "Left"

指定移动单元格的方式。有关详细信息，请参阅 Excel.DeleteShiftDirection。

void

注解

[ API 集：ExcelApi 1.1 ]

getBoundingRect(anotherRange)

获取包含指定区域的最小 range 对象。例如， GetBoundingRect “B2：C5”和“D10：E15”的为“B2：E15”。

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

参数

anotherRange: Excel.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
});

getCell(row, column)

根据行和列编号获取包含单个单元格的 range 对象。单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。返回的单元格位于相对于区域左上角的单元格的位置。

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

参数

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);
});

getColumn(column)

获取范围中包含的列。

getColumn(column: number): Excel.Range;

参数

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
});

getColumnsAfter(count)

获取当前 Range 对象右侧的一定数量的列。

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

参数

count: number

可选。生成的范围中要包含的列数。一般来说，使用正数可以在当前范围之外创建一个范围。也可以使用负数在当前范围之内创建一个范围。默认值为 1。

Excel.Range

注解

[ API 集：ExcelApi 1.2 ]

getColumnsBefore(count)

获取当前 Range 对象左侧的一定数量的列。

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

参数

count: number

Excel.Range

注解

[ API 集：ExcelApi 1.2 ]

getEntireColumn()

获取一个对象，该对象表示区域 (的整个列，例如，如果当前区域表示单元格“B4：E11”，则它是 getEntireColumn 表示列“B：E”) 的区域。

getEntireColumn(): Excel.Range;

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);
});

getEntireRow()

获取一个对象，该对象表示区域 (的整行，例如，如果当前区域表示单元格“B4：E11”，则它是 GetEntireRow 表示行“4：11”) 的区域。

getEntireRow(): Excel.Range;

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);
});

getIntersection(anotherRange)

获取表示指定区域的矩形交集的 range 对象。

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

参数

anotherRange: Excel.Range | string

将用于确定区域交集的 range 对象或区域地址。

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
});

getIntersectionOrNullObject(anotherRange)

获取表示指定区域的矩形交集的 range 对象。如果未找到交集，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

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

参数

anotherRange: Excel.Range | string

将用于确定区域交集的 range 对象或区域地址。

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();
});

getLastCell()

获取区域内的最后一个单元格。例如，“B2:D5”的最后一个单元格是“D5”。

getLastCell(): Excel.Range;

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
});

getLastColumn()

获取区域内的最后一列。例如，“B2:D5”的最后一列是“D2:D5”。

getLastColumn(): Excel.Range;

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
});

getLastRow()

获取区域内的最后一行。例如，“B2:D5”的最后一行是“B5:D5”。

getLastRow(): Excel.Range;

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
});

getOffsetRange(rowOffset, columnOffset)

获取表示与指定区域偏移的区域的对象。返回的区域的尺寸将与此区域一致。如果强制在工作表网格的边界之外生成区域，将引发错误。

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

参数

rowOffset: number

区域偏移的行数（正数、负数或 0）。正值表示向下偏移，负值表示向上偏移。

columnOffset: number

区域偏移的列数（正数、负数或 0）。正值表示向右偏移，负值表示向左偏移。

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
});

getResizedRange(deltaRows, deltaColumns)

获取与 Range 当前 Range 对象类似的对象，但其右下角展开 (或按行和列数收缩) 。

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

参数

deltaRows: number

相对于当前范围，展开右下角的行数。使用正数可展开范围，使用负数可合拢范围。

deltaColumns: number

相对于当前范围展开右下角的列数。使用正数可展开范围，使用负数可合拢范围。

Excel.Range

注解

[ API 集：ExcelApi 1.2 ]

getRow(row)

获取范围中包含的行。

getRow(row: number): Excel.Range;

参数

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
});

getRowsAbove(count)

获取当前 Range 对象上方的一定行数。

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

参数

count: number

可选。生成的范围中要包含的行数。一般来说，使用正数可以在当前范围之外创建一个范围。也可以使用负数在当前范围之内创建一个范围。默认值为 1。

Excel.Range

注解

[ API 集：ExcelApi 1.2 ]

getRowsBelow(count)

获取当前 Range 对象下面的特定行数。

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

参数

count: number

Excel.Range

注解

[ API 集：ExcelApi 1.2 ]

getUsedRange(valuesOnly)

返回指定 range 对象的所用区域。如果区域中没有使用的单元格，则此函数将引发错误 ItemNotFound 。

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

参数

valuesOnly: boolean

仅将有值的单元格视为已使用的单元格。 [Api 集：ExcelApi 1.2]

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();
});

getUsedRangeOrNullObject(valuesOnly)

返回指定 range 对象的所用区域。如果区域中没有已用单元格，则此方法返回一个对象，其 isNullObject 属性设置为 true。有关详细信息，请参阅 *OrNullObject 方法和属性。

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

参数

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()

表示当前 range 对象的可见行。

getVisibleView(): Excel.RangeView;

Excel.RangeView

注解

[ API 集：ExcelApi 1.3 ]

insert(shift)

将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。返回现在空白处的新 Range 对象。

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

参数

shift: Excel.InsertShiftDirection

指定移动单元格的方式。有关详细信息，请参阅 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();
});

insert(shiftString)

将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。返回现在空白处的新 Range 对象。

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

参数

shiftString: "Down" | "Right"

指定移动单元格的方式。有关详细信息，请参阅 Excel.InsertShiftDirection。

Excel.Range

注解

[ API 集：ExcelApi 1.1 ]

load(options)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

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

参数

options: Excel.Interfaces.RangeLoadOptions

提供要加载对象的属性的选项。

Excel.Range

load(propertyNames)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

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

参数

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);
});

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

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

参数

propertyNamesAndPaths: { select?: string; expand?: string; }

propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。

Excel.Range

merge(across)

将范围单元格合并到工作表的一个区域内。

merge(across?: boolean): void;

参数

across: boolean

可选。设置为 true 将指定区域的每一行中的单元格合并为单独的合并单元格。默认值 false为。

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.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

注解

[ 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(); 
});

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()

重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来又调用toJSON传递给它的对象的方法。) 而原始 Excel.Range 对象是 API 对象，toJSON该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.RangeData) ，其中包含原始对象中加载的任何子属性的浅表副本。

toJSON(): Excel.Interfaces.RangeData;

Excel.Interfaces.RangeData

track()

根据文档中的相应更改来跟踪对象，以便进行自动调整。此调用是 context.trackedObjects.add (thisObject) 的简写。如果跨 .sync 调用和在“.run”批处理的顺序执行之外使用此对象，并在设置属性或调用对象方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将该对象添加到跟踪的对象集合。

track(): Excel.Range;

Excel.Range

unmerge()

将范围单元格取消合并为各个单元格。

unmerge(): void;

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(); 
});

untrack()

释放与此对象关联的内存（如果先前已跟踪过）。此调用是 context.trackedObjects.remove (thisObject) 的简写。拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。在内存释放生效之前，需要调用。context.sync()

untrack(): Excel.Range;

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();
});

通过

Excel.Range class

注解

示例

属性

方法

属性详细信息

address

属性值

注解

addressLocal

属性值

注解

cellCount

属性值

注解

columnCount

属性值

注解

columnHidden

属性值

注解

columnIndex

属性值

注解

context

属性值

format

属性值

注解

formulas

属性值

注解

formulasLocal

属性值

注解

formulasR1C1

属性值

注解

hidden

属性值

注解

numberFormat

属性值

注解

示例

rowCount

属性值

注解

rowHidden

属性值

注解

rowIndex

属性值

注解

sort

属性值

注解

示例

text

属性值

注解

values

属性值

注解

valueTypes

属性值

注解

worksheet

属性值

注解

方法详细信息

clear(applyTo)

参数

返回

注解

示例

clear(applyToString)

参数

返回