Excel.Range class
Range 表示一组或多个连续单元格，例如单元格、行、列或单元格块。 若要详细了解如何在整个 API 中使用区域，请从 Excel JavaScript API 中的范围开始。
- Extends
注解
属性
| address | 指定 A1 样式中的区域引用。 地址值包含工作表引用 (例如“Sheet1！A1：B4“) 。 |
| address |
表示用户语言中指定范围的范围引用。 |
| cell |
指定区域中的单元格数。 如果单元格数超过 2^31-1 (2,147,483,647)，此 API 返回 -1。 |
| column |
指定区域中的列总数。 |
| column |
表示当前范围中的所有列是否处于隐藏状态。 |
| column |
指定区域中第一个单元格的列号。 从零开始编制索引。 |
| context | 与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。 |
| format | 返回一个格式对象，其中封装了区域的字体、填充、边框、对齐方式和其他属性。 |
| formulas | 表示采用 A1 表示法的公式。 如果单元格没有公式，则返回其值。 |
| formulas |
表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。 例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。 如果单元格没有公式，则返回其值。 |
| formulasR1C1 | 表示采用 R1C1 样式表示法的公式。 如果单元格没有公式，则返回其值。 |
| hidden | 表示当前区域中的所有单元格是否处于隐藏状态。 值是 |
| number |
表示给定区域的 Excel 数字格式代码。 有关 Excel 数字格式的详细信息，请参阅 数字格式代码。 |
| row |
返回区域中的总行数。 |
| row |
表示当前范围中的所有行是否处于隐藏状态。 值是 |
| row |
返回区域中第一个单元格的行编号。 从零开始编制索引。 |
| sort | 表示当前 range 的区域排序。 |
| text | 指定区域的文本值。 文本值与单元格宽度无关。 Excel UI 中发生的数字符号 (#) 替换不会影响 API 返回的文本值。 |
| values | 表示指定区域的原始值。 返回的数据可以是字符串、数字或布尔值。 包含错误的单元格将返回错误字符串。 如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。 |
| value |
指定每个单元格中的数据类型。 |
| worksheet | 包含当前区域的工作表。 |
方法
| clear(apply |
清除区域值、格式、填充、边框等。 |
| clear(apply |
清除区域值、格式、填充、边框等。 |
| delete(shift) | 删除与区域相关的单元格。 |
| delete(shift |
删除与区域相关的单元格。 |
| get |
获取包含指定区域的最小 range 对象。 例如， |
| get |
根据行和列编号获取包含单个单元格的 range 对象。 单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。 返回的单元格位于相对于区域左上角的单元格的位置。 |
| get |
获取范围中包含的列。 |
| get |
获取当前 |
| get |
获取当前 |
| get |
获取一个 对象，该对象表示区域 (的整个列，例如，如果当前区域表示单元格“B4：E11”，则它是 |
| get |
获取一个对象，该对象表示区域 (的整行，例如，如果当前区域表示单元格“B4：E11”，则它是 |
| get |
获取表示指定区域的矩形交集的 range 对象。 |
| get |
获取区域内的最后一个单元格。 例如，“B2:D5”的最后一个单元格是“D5”。 |
| get |
获取区域内的最后一列。 例如，“B2:D5”的最后一列是“D2:D5”。 |
| get |
获取区域内的最后一行。 例如，“B2:D5”的最后一行是“B5:D5”。 |
| get |
获取表示与指定区域偏移的区域的对象。 返回的区域的尺寸将与此区域一致。 如果强制在工作表网格的边界之外生成区域，将引发错误。 |
| get |
获取与 |
| get |
获取范围中包含的行。 |
| get |
获取当前 |
| get |
获取当前 |
| get |
返回指定 range 对象的所用区域。 如果区域中没有使用的单元格，则此函数将引发错误 |
| get |
表示当前 range 对象的可见行。 |
| insert(shift) | 将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。 返回现在空白处的新 |
| insert(shift |
将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。 返回现在空白处的新 |
| load(options) | 将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| merge(across) | 将范围单元格合并到工作表的一个区域内。 |
| select() | 在 Excel UI 中选择指定的区域。 |
| set(properties, options) | 同时设置对象的多个属性。 可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。 |
| set(properties) | 基于现有的已加载对象，同时对对象设置多个属性。 |
| toJSON() | 重写 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
context
format
返回一个格式对象，其中封装了区域的字体、填充、边框、对齐方式和其他属性。
readonly format: Excel.RangeFormat;属性值
注解
formulas
formulasLocal
表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。 例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。 如果单元格没有公式，则返回其值。
formulasLocal: any[][];属性值
any[][]
注解
formulasR1C1
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
sort
表示当前 range 的区域排序。
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
表示指定区域的原始值。 返回的数据可以是字符串、数字或布尔值。 包含错误的单元格将返回错误字符串。 如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。
values: any[][];属性值
any[][]
注解
valueTypes
指定每个单元格中的数据类型。
readonly valueTypes: Excel.RangeValueType[][];属性值
注解
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 对象。 例如， 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)
根据行和列编号获取包含单个单元格的 range 对象。 单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。 返回的单元格位于相对于区域左上角的单元格的位置。
getCell(row: number, column: number): Excel.Range;参数
- row
-
number
要检索的单元格的行号。 从零开始编制索引。
- column
-
number
要检索的单元格的列号。 从零开始编制索引。
返回
注解
示例
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
要检索的区域的列号。 从零开始编制索引。
返回
注解
示例
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)
获取表示指定区域的矩形交集的 range 对象。
getIntersection(anotherRange: Range | string): Excel.Range;参数
- anotherRange
-
Excel.Range | string
将用于确定区域交集的 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
});
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)
获取范围中包含的行。
getRow(row: number): Excel.Range;参数
- row
-
number
要检索的区域的行号。 从零开始编制索引。
返回
注解
示例
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)
返回指定 range 对象的所用区域。 如果区域中没有使用的单元格，则此函数将引发错误 ItemNotFound 。
getUsedRange(valuesOnly?: boolean): Excel.Range;参数
- valuesOnly
-
boolean
仅将有值的单元格视为已使用的单元格。 [Api 集：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();
});
getVisibleView()
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)
将范围单元格合并到工作表的一个区域内。
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()
重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 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();
});
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈