ExcelScript.Range interface

参考

包:: ExcelScript

Range 表示一组或多个连续单元格，例如单元格、行、列或单元格块。

注解

示例

/**
 * This script logs the address of the used range in the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current, active worksheet.
  let currentWorksheet = workbook.getActiveWorksheet();

  // Get the range containing all the cells with data or formatting.
  let usedRange = currentWorksheet.getUsedRange();

  // Log the range's address to the console.
  console.log(usedRange.getAddress());
}

方法

addConditionalFormat(type)	将新的条件格式添加到集合的第一个/最高优先级。
autoFill(destinationRange, autoFillType)	使用指定的自动填充逻辑填充从当前范围到目标范围的范围。目标范围可以是 `null` 或可以水平或垂直扩展源范围。不支持不连续的范围。
calculate()	计算工作表上的单元格区域。
clear(applyTo)	清除区域值、格式、填充、边框等。
clearAllConditionalFormats()	清除当前指定区域中处于活动状态的所有条件格式。
convertDataTypeToText()	将数据类型为文本的区域单元格。
copyFrom(sourceRange, copyType, skipBlanks, transpose)	将单元格数据或格式从源区域或 `RangeAreas` 复制到当前区域。目标范围的大小可以不同于源范围或 `RangeAreas`。如果目标小于源，则会自动扩展。注意：与 Excel UI 中的复制功能一样，如果目标范围正好大于行或列中源范围的倍数，则会多次复制源内容。例如，将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。
delete(shift)	删除与区域相关的单元格。
find(text, criteria)	根据指定的条件查找给定的字符串。如果当前区域大于单个单元格，则搜索将限制为该范围，否则搜索将涵盖从该单元格之后开始的整个工作表。如果没有匹配项，则此方法返回 `undefined`。
flashFill()	对当前范围执行快速填充。快速填充在感知模式时自动填充数据，因此范围必须是单个列范围，并且周围有数据才能找到模式。
getAbsoluteResizedRange(numRows, numColumns)	获取一个 `Range` 对象，该对象具有与当前 `Range` 对象相同的左上角单元格，但具有指定的行数和列数。
getAddress()	指定 A1 样式中的区域引用。地址值包含工作表引用 (例如“Sheet1！A1：B4“) 。
getAddressLocal()	表示用户语言中指定范围的范围引用。
getBoundingRect(anotherRange)	获取包含指定区域的最小 range 对象。例如， `GetBoundingRect` “B2：C5”和“D10：E15”的为“B2：E15”。
getCell(row, column)	根据行和列编号获取包含单个单元格的 range 对象。单元格可以位于其父区域的边界之外，只要它保留在工作表网格中。返回的单元格位于相对于区域左上角的单元格的位置。
getCellCount()	指定区域中的单元格数。如果单元格数超过 2^31-1 (2,147,483,647)，此 API 返回 -1。
getColumn(column)	获取范围中包含的列。
getColumnCount()	指定区域中的列总数。
getColumnHidden()	表示当前范围中的所有列是否处于隐藏状态。 `true`当一个区域中的所有列都隐藏时，值。 `false`当区域中没有列处于隐藏状态时，该值为。 `null`当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时，该值表示。
getColumnIndex()	指定区域中第一个单元格的列号。从零开始编制索引。
getColumnsAfter(count)	获取当前 `Range` 对象右侧的一定数量的列。
getColumnsBefore(count)	获取当前 `Range` 对象左侧的一定数量的列。
getConditionalFormat(id)	返回由其 ID 标识的条件格式。如果条件格式对象不存在，则此方法返回 `undefined`。
getConditionalFormats()	与范围相交的的集合 `ConditionalFormats` 。
getDataValidation()	返回数据有效性对象。
getDirectPrecedents()	返回一个 `WorkbookRangeAreas` 对象，该对象表示包含同一工作表中或跨多个工作表的指定区域的所有直接引用单元格的区域。
getEntireColumn()	获取一个对象，该对象表示区域 (的整个列，例如，如果当前区域表示单元格“B4：E11”，则它是 `getEntireColumn` 表示列“B：E”) 的区域。
getEntireRow()	获取一个对象，该对象表示区域 (的整行，例如，如果当前区域表示单元格“B4：E11”，则它是 `GetEntireRow` 表示行“4：11”) 的区域。
getExtendedRange(direction, activeCell)	返回一个 range 对象，该对象包括当前范围以及范围边缘，具体取决于提供的方向。这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。
getFormat()	返回一个格式对象，其中封装了区域的字体、填充、边框、对齐方式和其他属性。
getFormula()	表示 A1 样式表示法中的单元格公式。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。
getFormulaLocal()	以用户的语言和数字格式区域设置，表示 A1 样式表示法的单元格公式。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。
getFormulaR1C1()	表示 R1C1 样式表示法中的单元格公式。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。
getFormulas()	表示采用 A1 表示法的公式。如果单元格没有公式，则返回其值。
getFormulasLocal()	表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果单元格没有公式，则返回其值。
getFormulasR1C1()	表示采用 R1C1 样式表示法的公式。如果单元格没有公式，则返回其值。
getHasSpill()	表示所有单元格是否都具有溢出边框。 `true`如果所有单元格都有溢出边框，或者`false`所有单元格都没有溢出边框，则返回。 `null`如果区域中有和没有溢出边框的单元格，则返回。
getHeight()	返回从范围上边缘到范围下边缘的 100% 缩放的距离（以磅为单位）。
getHidden()	表示当前区域中的所有单元格是否处于隐藏状态。值是 `true` 隐藏区域中的所有单元格时。 `false`当区域中没有单元格被隐藏时，值。 `null`当某个区域中的某些单元格处于隐藏状态，而同一区域中的其他单元格未隐藏时，值表示。
getHyperlink()	表示当前范围的超链接。
getImage()	将范围呈现为 base64 编码的 png 图像。
getIntersection(anotherRange)	获取表示指定区域的矩形交集的 range 对象。如果未找到交集，则此方法返回 `undefined`。
getIsEntireColumn()	表示当前区域是否为整列。
getIsEntireRow()	表示当前区域是否为整行。
getLastCell()	获取区域内的最后一个单元格。例如，“B2:D5”的最后一个单元格是“D5”。
getLastColumn()	获取区域内的最后一列。例如，“B2:D5”的最后一列是“D2:D5”。
getLastRow()	获取区域内的最后一行。例如，“B2:D5”的最后一行是“B5:D5”。
getLeft()	返回从工作表左边缘到区域左边缘的 100% 缩放的距离（以磅为单位）。
getLinkedDataTypeState()	表示单元格的数据类型状态。
getLinkedDataTypeStates()	表示每个单元格的数据类型状态。
getMergedAreas()	返回一个 `RangeAreas` 对象，该对象代表此区域中的合并区域。请注意，如果此范围内的合并区域计数超过 512，则此方法将无法返回结果。 `RangeAreas`如果该对象不存在，则此函数返回 `undefined`。
getNumberFormat()	表示给定区域的 Excel 数字格式代码单元格。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。
getNumberFormatCategories()	表示每个单元格的数字格式的类别。
getNumberFormatCategory()	指定区域中第一个单元格的数字格式类别 (行索引为 0，列索引为 0) 表示。
getNumberFormatLocal()	表示基于用户语言设置的给定区域的 Excel 数字格式代码单元格。获取或设置 `numberFormatLocal` 属性时，Excel 不执行任何语言或格式强制。任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。
getNumberFormats()	表示给定区域的 Excel 数字格式代码。
getNumberFormatsLocal()	表示基于用户语言设置的给定区域的 Excel 数字格式代码。获取或设置 `numberFormatLocal` 属性时，Excel 不执行任何语言或格式强制。任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。
getOffsetRange(rowOffset, columnOffset)	获取表示与指定区域偏移的区域的对象。返回的区域的尺寸将与此区域一致。如果强制在工作表网格的边界之外生成区域，将引发错误。
getPivotTables(fullyContained)	获取与区域重叠的数据透视表的作用域集合。
getPredefinedCellStyle()	表示当前区域的样式。如果单元格的样式不一致， `null` 将返回。对于自定义样式，将返回样式名称。对于内置样式，将返回表示枚举中的 `BuiltInStyle` 值的字符串。
getRangeEdge(direction, activeCell)	返回一个 range 对象，该对象是与提供的方向对应的数据区域边缘单元格。这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。
getResizedRange(deltaRows, deltaColumns)	获取与 `Range` 当前 `Range` 对象类似的对象，但其右下角展开 (或按行和列数收缩) 。
getRow(row)	获取范围中包含的行。
getRowCount()	返回区域中的总行数。
getRowHidden()	表示当前范围中的所有行是否处于隐藏状态。值是 `true` 隐藏范围中的所有行时。 `false`当区域中没有隐藏行时，值。 `null`当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时，该值表示。
getRowIndex()	返回区域中第一个单元格的行编号。从零开始编制索引。
getRowsAbove(count)	获取当前 `Range` 对象上方的一定行数。
getRowsBelow(count)	获取当前 `Range` 对象下面的特定行数。
getSavedAsArray()	表示是否将所有单元格另存为数组公式。 `true`如果所有单元格都另存为数组公式，或者`false`所有单元格不另存为数组公式，则返回。 `null`如果某些单元格将保存为数组公式，而有些单元格则不保存，则返回。
getSort()	表示当前 range 的区域排序。
getSpecialCells(cellType, cellValueType)	`RangeAreas`获取由一个或多个区域组成的对象，该对象表示与指定类型和值匹配的所有单元格。如果未找到任何特殊单元格，则此方法返回 `undefined`。
getSpillingToRange()	获取 Range 对象，它在调用定位单元格时包含溢出区域。如果区域不是定位点单元格或找不到溢出区域，则此方法返回 `undefined`。
getSpillParent()	获取包含要溢出到的单元格的定位单元格的范围对象。如果它不是溢出的单元格，或者提供了多个单元格，则此方法返回 `undefined`。
getSurroundingRegion()	返回一个 `Range` 对象，该对象代表此区域中左上角单元格的周围区域。周围区域是由相对于该区域的空白行和空白列的任何组合所限定的区域。
getTables(fullyContained)	获取与区域重叠的限定范围的表格集合。
getText()	表示指定范围的 Text 值。文本值与单元格宽度无关。在 Excel UI 中替代 # 符号不会影响 API 返回的文本值。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。
getTexts()	指定区域的文本值。文本值与单元格宽度无关。 Excel UI 中发生的数字符号 (#) 替换不会影响 API 返回的文本值。
getTop()	返回从工作表上边缘到区域上边缘的 100% 缩放的距离（以磅为单位）。
getUsedRange(valuesOnly)	返回指定 range 对象的所用区域。如果区域中没有使用单元格，则此方法返回 `undefined`。
getValue()	表示指定范围的原始值。返回的数据可能是字符串、数字，也可能是布尔值。包含错误的单元格将返回错误字符串。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。
getValues()	表示指定区域的原始值。返回的数据可以是字符串、数字或布尔值。包含错误的单元格将返回错误字符串。如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。
getValueType()	表示单元格中的数据类型。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。
getValueTypes()	指定每个单元格中的数据类型。
getVisibleView()	表示当前 range 对象的可见行。
getWidth()	返回从范围的左边缘到范围右边缘的 100% 缩放的距离（以磅为单位）。
getWorksheet()	包含当前区域的工作表。
group(groupOption)	组大纲的列和行。
hideGroupDetails(groupOption)	隐藏行或列组的详细信息。
insert(shift)	将单个单元格或一系列单元格插入到工作表中取代此区域，并移动其他单元格以留出空间。返回现在空白处的新 `Range` 对象。
merge(across)	将范围单元格合并到工作表的一个区域内。
moveTo(destinationRange)	将单元格值、格式和公式从当前区域移动到目标区域，替换这些单元格中的旧信息。如果目标范围小于当前范围，则会自动扩展。不会更改目标区域中超出原始区域区域的任何单元格。
removeDuplicates(columns, includesHeader)	从列指定的区域中删除重复值。
replaceAll(text, replacement, criteria)	根据当前区域内指定的条件查找并替换给定的字符串。
select()	在 Excel UI 中选择指定的区域。
setColumnHidden(columnHidden)	表示当前范围中的所有列是否处于隐藏状态。 `true`当一个区域中的所有列都隐藏时，值。 `false`当区域中没有列处于隐藏状态时，该值为。 `null`当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时，该值表示。
setDirty()	设置下一次重新计算发生时要重新计算的区域。
setFormula(formula)	以 A1 样式表示法设置单元格公式。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。
setFormulaLocal(formulaLocal)	在用户的语言和数字格式区域设置中，以 A1 样式表示法设置单元格公式。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。
setFormulaR1C1(formulaR1C1)	以 R1C1 样式表示法设置单元格公式。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。
setFormulas(formulas)	表示采用 A1 表示法的公式。如果单元格没有公式，则返回其值。
setFormulasLocal(formulasLocal)	表示采用 A1 样式表示法的公式，使用用户的语言和数字格式区域设置。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果单元格没有公式，则返回其值。
setFormulasR1C1(formulasR1C1)	表示采用 R1C1 样式表示法的公式。如果单元格没有公式，则返回其值。
setHyperlink(hyperlink)	表示当前范围的超链接。
setNumberFormat(numberFormat)	设置给定区域的单元格 Excel 数字格式代码。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。
setNumberFormatLocal(numberFormatLocal)	根据用户的语言设置，设置给定区域的 Excel 数字格式代码。获取或设置 `numberFormatLocal` 属性时，Excel 不执行任何语言或格式强制。任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。
setNumberFormats(numberFormats)	表示给定区域的 Excel 数字格式代码。
setNumberFormatsLocal(numberFormatsLocal)	表示基于用户语言设置的给定区域的 Excel 数字格式代码。获取或设置 `numberFormatLocal` 属性时，Excel 不执行任何语言或格式强制。任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。
setPredefinedCellStyle(predefinedCellStyle)	表示当前区域的样式。
setRowHidden(rowHidden)	表示当前范围中的所有行是否处于隐藏状态。值是 `true` 隐藏范围中的所有行时。 `false`当区域中没有隐藏行时，值。 `null`当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时，该值表示。
setValue(value)	设置指定范围的原始值。所设置的数据可以是字符串、数字或布尔值。 `null` (Excel) 中未设置或覆盖 value 将被忽略。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。
setValues(values)	设置指定范围的原始值。提供的数据可以是字符串、数字或布尔值。如果提供的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。
showCard()	显示活动单元格的卡片（如果该单元格具有富值内容）。
showGroupDetails(groupOption)	显示行或列组的详细信息。
ungroup(groupOption)	取消对大纲的列和行的分组。
unmerge()	将范围单元格取消合并为各个单元格。

方法详细信息

addConditionalFormat(type)

将新的条件格式添加到集合的第一个/最高优先级。

addConditionalFormat(type: ConditionalFormatType): ConditionalFormat;

参数

type: ExcelScript.ConditionalFormatType

要添加的条件格式的类型。有关详细信息，请参阅 ExcelScript.ConditionalFormatType。

ExcelScript.ConditionalFormat

示例

/**
 * This sample applies conditional formatting to the currently used range in the worksheet. 
 * The conditional formatting is a green fill for the top 10% of values.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the used range in the worksheet.
  let range = selectedSheet.getUsedRange();

  // Set the fill color to green for the top 10% of values in the range.
  let conditionalFormat = range.addConditionalFormat(ExcelScript.ConditionalFormatType.topBottom)
  conditionalFormat.getTopBottom().getFormat().getFill().setColor("green");
  conditionalFormat.getTopBottom().setRule({
    rank: 10, // The percentage threshold.
    type: ExcelScript.ConditionalTopBottomCriterionType.topPercent // The type of the top/bottom condition.
  });
}

autoFill(destinationRange, autoFillType)

使用指定的自动填充逻辑填充从当前范围到目标范围的范围。目标范围可以是 null 或可以水平或垂直扩展源范围。不支持不连续的范围。

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

参数

destinationRange: ExcelScript.Range | string

要自动填充的目标范围。如果目标区域为 null，则会根据周围的单元格填充数据 (这是双击 UI 的区域填充句柄) 时的行为。

autoFillType: ExcelScript.AutoFillType

自动填充的类型。根据当前范围的内容指定如何填充目标范围。默认值为“FillDefault”。

void

示例

/**
 * This script uses the autofill feature to complete a table.
 * See https://support.microsoft.com/office/74e31bdd-d993-45da-aa82-35a236c5b5db
 * for examples of autofill scenarios.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current, active worksheet.
  let currentWorksheet = workbook.getActiveWorksheet();

  // Get the data range that shows the pattern.
  let dataRange = currentWorksheet.getRange("C2:C3");

  // Autofill the connected range. C2:C3 are filled in. C4:C14 are blank.
  // This uses the default behavior to match a pattern with the table's contents.
  dataRange.autoFill("C2:C14");
}

calculate()

计算工作表上的单元格区域。

calculate(): void;

void

示例

/**
 * This script recalculates the used range of a specific worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Only recalculate if the calculation mode is not set to automatic.
  if (workbook.getApplication().getCalculationMode() !== ExcelScript.CalculationMode.automatic) {
    // Get the used range from a worksheet named "Monthly Report".
    const sheet = workbook.getWorksheet("Monthly Report");
    const range = sheet.getUsedRange();
    console.log(`Calculating ${range.getAddress()}`);

    // Force all the used cells in that worksheet to calculate.
    sheet.getUsedRange().calculate();
  }
}

clear(applyTo)

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

clear(applyTo?: ClearApplyTo): void;

参数

applyTo: ExcelScript.ClearApplyTo

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

void

示例

/**
 * This script removes all the formatting from the selected range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the selected range.
  let range = workbook.getSelectedRange();

  // Clear all the formatting in that range.
  range.clear(ExcelScript.ClearApplyTo.formats);
}

clearAllConditionalFormats()

清除当前指定区域中处于活动状态的所有条件格式。

clearAllConditionalFormats(): void;

void

convertDataTypeToText()

将数据类型为文本的区域单元格。

convertDataTypeToText(): void;

void

copyFrom(sourceRange, copyType, skipBlanks, transpose)

将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。目标范围的大小可以不同于源范围或 RangeAreas。如果目标小于源，则会自动扩展。注意：与 Excel UI 中的复制功能一样，如果目标范围正好大于行或列中源范围的倍数，则会多次复制源内容。例如，将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。

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

参数

sourceRange: ExcelScript.Range | ExcelScript.RangeAreas | string

要从中复制的源范围或 RangeAreas 。当源 RangeAreas 具有多个区域时，必须能够通过从矩形区域中删除完整的行或列来创建其窗体。

copyType: ExcelScript.RangeCopyType

要复制的单元格数据或格式的类型。默认值为“All”。

skipBlanks: boolean

如果跳过源区域中的空白单元格，则为 True。默认为 false。

transpose: boolean

如此如果转置目标区域中的单元格。默认为 false。

void

示例

/**
 * This script copies a table from one worksheet to a new worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the worksheet named "TableTemplate".
  let base = workbook.getWorksheet("TableTemplate");
  
  // Get the range to be copied based on the first table.
  let tableRange = base.getTables()[0].getRange();

  // Get the area in a new worksheet for the new table.
  let newWorksheet = workbook.addWorksheet();
  let newRange = newWorksheet.getRangeByIndexes(0,0, tableRange.getRowCount(), tableRange.getColumnCount());

  // Copy the existing data into the new range.
  newRange.copyFrom(tableRange);
}

delete(shift)

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

delete(shift: DeleteShiftDirection): void;

参数

shift: ExcelScript.DeleteShiftDirection

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

void

示例

/**
 * This sample creates a sample range, then deletes
 * "A1" using different DeleteShiftDirection values.
 */
function main(workbook: ExcelScript.Workbook) {
  // Add sample data to better visualize the delete changes.
  const currentSheet = workbook.getActiveWorksheet();
  currentSheet.getRange("A1:D4").setValues([
    [1,2,3,4],
    [5,6,7,8],
    [9,10,11,12],
    [13,14,15,16]]);

  // Delete A1 and shift the cells from the right to fill the space.
  // The value being deleted is 1.
  currentSheet.getRange("A1").delete(ExcelScript.DeleteShiftDirection.left);

  // Delete A1 and shift the cells from the bottom to fill the space.
  // The value being deleted is 2.
  currentSheet.getRange("A1").delete(ExcelScript.DeleteShiftDirection.up);

  // Log the sample range. The values should be:
  /*
    5, 3, 4, "",
    9, 6, 7, 8,
    13, 10, 11, 12,
    "", 14, 15, 16
  */
  console.log(currentSheet.getRange("A1:D4").getValues()); 
}

find(text, criteria)

根据指定的条件查找给定的字符串。如果当前区域大于单个单元格，则搜索将限制为该范围，否则搜索将涵盖从该单元格之后开始的整个工作表。如果没有匹配项，则此方法返回 undefined。

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

参数

text: string

要查找的字符串。

criteria: ExcelScript.SearchCriteria

其他搜索条件，包括搜索方向以及搜索是否需要匹配整个单元格还是区分大小写。

ExcelScript.Range

示例

/**
 * This script searches through a table column and finds cells marked "no change". 
 * Those cells have "no change" replaced with the value from the cell to the left.
 * This script uses Range.find instead of Worksheet.findAll 
 * to limit the search to a specific range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range of a table named "Orders".
  let table = workbook.getTable("Orders");
  let range = table.getColumnByName("March").getRange();

  // Find all cells with the value "no change".
  let cellToOverwrite = range.find("no change", { completeMatch: true });
  while (cellToOverwrite) {
    let cellToCopyFrom = cellToOverwrite.getOffsetRange(0,-1);
    cellToOverwrite.setValue(cellToCopyFrom.getValue());
    cellToOverwrite = range.find("no change", { completeMatch: true });
  }
}

flashFill()

对当前范围执行快速填充。快速填充在感知模式时自动填充数据，因此范围必须是单个列范围，并且周围有数据才能找到模式。

flashFill(): void;

void

示例

/**
 * This script uses the Flash Fill feature to complete a table.
 * See https://support.microsoft.com/office/3f9bcf1e-db93-4890-94a0-1578341f73f7
 * for the example table.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current, active worksheet.
  let currentWorksheet = workbook.getActiveWorksheet();

  // Get the data range with a pattern and cells to fill. C2 is filled in. C3:C6 are blank.
  let dataRange = currentWorksheet.getRange("C2:C6");

  // Flash fill the connected range. 
  dataRange.flashFill();
}

getAbsoluteResizedRange(numRows, numColumns)

获取一个 Range 对象，该对象具有与当前 Range 对象相同的左上角单元格，但具有指定的行数和列数。

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

参数

numRows: number

新范围大小的行数。

numColumns: number

新范围大小的列数。

ExcelScript.Range

getAddress()

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

getAddress(): string;

string

示例

/**
 * This script logs the address of the used range in each worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Iterate over every worksheet in the workbook.
  workbook.getWorksheets().forEach((sheet) => {
    // Get the used range for a single worksheet.
    let range = sheet.getUsedRange();

    // Print the address of the used range to the console.
    console.log(range.getAddress());
  });
}

getAddressLocal()

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

getAddressLocal(): string;

string

getBoundingRect(anotherRange)

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

getBoundingRect(anotherRange: Range | string): Range;

参数

anotherRange: ExcelScript.Range | string

范围对象、地址或范围名称。

ExcelScript.Range

示例

/**
 * This script gets the bounding range of two existing ranges and puts a border around it.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let sheet = workbook.getActiveWorksheet();

  // Create two range objects for the sample.
  let range1 = sheet.getRange("B2:C5");
  let range2 = sheet.getRange("D10:E15");

  // Get the rectangular range that fully includes both ranges.
  let boundingRectangle = range1.getBoundingRect(range2);

  // Add a border around the whole bounding range (B2:E15).
  let format = boundingRectangle.getFormat();
  format.getRangeBorder(ExcelScript.BorderIndex.edgeTop).setStyle(ExcelScript.BorderLineStyle.continuous); // Top border
  format.getRangeBorder(ExcelScript.BorderIndex.edgeBottom).setStyle(ExcelScript.BorderLineStyle.continuous); // Bottom border
  format.getRangeBorder(ExcelScript.BorderIndex.edgeLeft).setStyle(ExcelScript.BorderLineStyle.continuous); // Left border
  format.getRangeBorder(ExcelScript.BorderIndex.edgeRight).setStyle(ExcelScript.BorderLineStyle.continuous); // Right border
}

getCell(row, column)

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

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

参数

row: number

要检索的单元格的行号。从零开始编制索引。

column: number

要检索的单元格的列号。从零开始编制索引。

ExcelScript.Range

getCellCount()

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

getCellCount(): number;

number

getColumn(column)

获取范围中包含的列。

getColumn(column: number): Range;

参数

column: number

要检索的区域的列号。从零开始编制索引。

ExcelScript.Range

getColumnCount()

指定区域中的列总数。

getColumnCount(): number;

number

示例

/**
 * This sample provides the count of negative numbers that are present
 * in the used range of the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the working range.
  let usedRange = workbook.getActiveWorksheet().getUsedRange();
  let rowCount = usedRange.getRowCount();
  let columnCount = usedRange.getColumnCount();

  // Save the values locally to avoid repeatedly asking the workbook.
  let usedRangeValues = usedRange.getValues();

  // Start the negative number counter.
  let negativeCount = 0;

  // Iterate over the entire range looking for negative numbers.
  for (let i = 0; i < rowCount; i++) {
    for (let j = 0; j < columnCount; j++) {
      if (usedRangeValues[i][j] < 0) {
        negativeCount++;
      }
    }
  }

  // Log the negative number count to the console.
  console.log(negativeCount);
}

getColumnHidden()

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

getColumnHidden(): boolean;

boolean

getColumnIndex()

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

getColumnIndex(): number;

number

getColumnsAfter(count)

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

getColumnsAfter(count?: number): Range;

参数

count: number

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

ExcelScript.Range

getColumnsBefore(count)

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

getColumnsBefore(count?: number): Range;

参数

count: number

ExcelScript.Range

getConditionalFormat(id)

返回由其 ID 标识的条件格式。如果条件格式对象不存在，则此方法返回 undefined。

getConditionalFormat(id: string): ConditionalFormat | undefined;

参数

id: string

条件格式的 ID。

ExcelScript.ConditionalFormat | undefined

getConditionalFormats()

与范围相交的的集合 ConditionalFormats 。

getConditionalFormats(): ConditionalFormat[];

ExcelScript.ConditionalFormat[]

getDataValidation()

返回数据有效性对象。

getDataValidation(): DataValidation;

ExcelScript.DataValidation

示例

/**
 * This script creates a drop-down selection list for a cell. It uses the existing values of the selected range as the choices for the list.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the values for data validation.
  let selectedRange = workbook.getSelectedRange();
  let rangeValues = selectedRange.getValues();

  // Convert the values into a comma-delimited string.
  let dataValidationListString = "";
  rangeValues.forEach((rangeValueRow) => {
    rangeValueRow.forEach((value) => {
      dataValidationListString += value + ",";
    });
  });

  // Clear the old range.
  selectedRange.clear(ExcelScript.ClearApplyTo.contents);

  // Apply the data validation to the first cell in the selected range.
  let targetCell = selectedRange.getCell(0,0);
  let dataValidation = targetCell.getDataValidation();

  // Set the content of the drop-down list.
  dataValidation.setRule({
      list: {
        inCellDropDown: true,
        source: dataValidationListString
      }
    });
}

getDirectPrecedents()

返回一个 WorkbookRangeAreas 对象，该对象表示包含同一工作表中或跨多个工作表的指定区域的所有直接引用单元格的区域。

getDirectPrecedents(): WorkbookRangeAreas;

ExcelScript.WorkbookRangeAreas

示例

/**
 * This script finds the direct precedents of the active cell.
 * It changes the font and color of those precedent cells. 
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active cell.
  const selected = workbook.getActiveCell();
  
  // Get the cells that are direct precedents of the current cell.
  const precedents : ExcelScript.WorkbookRangeAreas = selected.getDirectPrecedents();

  // Set the font to bold and the fill color to orange for all the precedent cells.
  precedents.getRanges().forEach(range => {
    range.getFormat().getFill().setColor("orange");
    range.getFormat().getFont().setBold(true);
  });
}

getEntireColumn()

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

getEntireColumn(): Range;

ExcelScript.Range

getEntireRow()

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

getEntireRow(): Range;

ExcelScript.Range

getExtendedRange(direction, activeCell)

返回一个 range 对象，该对象包括当前范围以及范围边缘，具体取决于提供的方向。这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。

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

参数

direction: ExcelScript.KeyboardDirection

活动单元格的方向。

activeCell: ExcelScript.Range | string

此区域中的活动单元格。默认情况下，活动单元格是区域的左上角单元格。如果活动单元格不在此范围内，则会引发错误。

ExcelScript.Range

示例

/**
 * This script makes the font bold on all the contiguous cells between 
 * A1 and the bottom of the used range of the first column.
 */
function main(workbook: ExcelScript.Workbook)
{
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get every cell that's used between A1 and the end of the column.
  // This recreates the Ctrl+Shift+Down arrow key behavior.
  let firstCell = selectedSheet.getRange("A1");
  let firstColumn = firstCell.getExtendedRange(ExcelScript.KeyboardDirection.down);

  // Set the font to bold in that range.
  firstColumn.getFormat().getFont().setBold(true);
}

getFormat()

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

getFormat(): RangeFormat;

ExcelScript.RangeFormat

示例

/**
 * This script gives the total row of a table a green color fill.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first table in the workbook.
  let table = workbook.getTables()[0];

  // Get the range for the total row of the table.
  let totalRange = table.getTotalRowRange();

  // Set the fill color to green.
  totalRange.getFormat().getFill().setColor("green");
}

getFormula()

表示 A1 样式表示法中的单元格公式。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。

getFormula(): string;

string

示例

/*
 * This script sets a cell's formula, 
 * then displays how Excel stores the cell's formula and value separately.
 */
function main(workbook: ExcelScript.Workbook) {
  let selectedSheet = workbook.getActiveWorksheet();

  // Set A1 to 2.
  let a1 = selectedSheet.getRange("A1");
  a1.setValue(2);

  // Set B1 to the formula =(2*A1), which should equal 4.
  let b1 = selectedSheet.getRange("B1")
  b1.setFormula("=(2*A1)");

  // Log the current results for `getFormula` and `getValue` at B1.
  console.log(`B1 - Formula: ${b1.getFormula()} | Value: ${b1.getValue()}`);
}

getFormulaLocal()

以用户的语言和数字格式区域设置，表示 A1 样式表示法的单元格公式。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。

getFormulaLocal(): string;

string

getFormulaR1C1()

表示 R1C1 样式表示法中的单元格公式。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。

getFormulaR1C1(): string;

string

getFormulas()

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

getFormulas(): string[][];

string[][]

getFormulasLocal()

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

getFormulasLocal(): string[][];

string[][]

getFormulasR1C1()

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

getFormulasR1C1(): string[][];

string[][]

getHasSpill()

表示所有单元格是否都具有溢出边框。 true如果所有单元格都有溢出边框，或者false所有单元格都没有溢出边框，则返回。 null如果区域中有和没有溢出边框的单元格，则返回。

getHasSpill(): boolean;

boolean

getHeight()

返回从范围上边缘到范围下边缘的 100% 缩放的距离（以磅为单位）。

getHeight(): number;

number

getHidden()

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

getHidden(): boolean;

boolean

getHyperlink()

表示当前范围的超链接。

getHyperlink(): RangeHyperlink;

ExcelScript.RangeHyperlink

示例

/**
 * This sample clears all of the hyperlinks from the current worksheet
 * and removes the usual hyperlink formatting.
 */
function main(workbook: ExcelScript.Workbook, sheetName: string = 'Sheet1') {
  // Get the active worksheet. 
  let sheet = workbook.getWorksheet(sheetName);

  // Get the used range to operate on.
  // For large ranges (over 10000 entries), consider splitting the operation into batches for performance.
  const targetRange = sheet.getUsedRange(true);
  console.log(`Target Range to clear hyperlinks from: ${targetRange.getAddress()}`);

  const rowCount = targetRange.getRowCount();
  const colCount = targetRange.getColumnCount();
  console.log(`Searching for hyperlinks in ${targetRange.getAddress()} which contains ${(rowCount * colCount)} cells`);

  // Go through each individual cell looking for a hyperlink. 
  // This allows us to limit the formatting changes to only the cells with hyperlink formatting.
  let clearedCount = 0;
  for (let i = 0; i < rowCount; i++) {
    for (let j = 0; j < colCount; j++) {
      const cell = targetRange.getCell(i, j);
      const hyperlink = cell.getHyperlink();
      if (hyperlink) {
        cell.clear(ExcelScript.ClearApplyTo.hyperlinks);
        cell.getFormat().getFont().setUnderline(ExcelScript.RangeUnderlineStyle.none);
        cell.getFormat().getFont().setColor('Black');
        clearedCount++;
      }
    }
  }

  console.log(`Done. Cleared hyperlinks from ${clearedCount} cells`);
}

getImage()

将范围呈现为 base64 编码的 png 图像。

getImage(): string;

string

getIntersection(anotherRange)

获取表示指定区域的矩形交集的 range 对象。如果未找到交集，则此方法返回 undefined。

getIntersection(anotherRange: Range | string): Range;

参数

anotherRange: ExcelScript.Range | string

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

ExcelScript.Range

getIsEntireColumn()

表示当前区域是否为整列。

getIsEntireColumn(): boolean;

boolean

getIsEntireRow()

表示当前区域是否为整行。

getIsEntireRow(): boolean;

boolean

getLastCell()

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

getLastCell(): Range;

ExcelScript.Range

getLastColumn()

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

getLastColumn(): Range;

ExcelScript.Range

getLastRow()

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

getLastRow(): Range;

ExcelScript.Range

getLeft()

返回从工作表左边缘到区域左边缘的 100% 缩放的距离（以磅为单位）。

getLeft(): number;

number

getLinkedDataTypeState()

表示单元格的数据类型状态。

getLinkedDataTypeState(): LinkedDataTypeState;

ExcelScript.LinkedDataTypeState

getLinkedDataTypeStates()

表示每个单元格的数据类型状态。

getLinkedDataTypeStates(): LinkedDataTypeState[][];

ExcelScript.LinkedDataTypeState[][]

getMergedAreas()

返回一个 RangeAreas 对象，该对象代表此区域中的合并区域。请注意，如果此范围内的合并区域计数超过 512，则此方法将无法返回结果。 RangeAreas如果该对象不存在，则此函数返回 undefined。

getMergedAreas(): RangeAreas;

ExcelScript.RangeAreas

getNumberFormat()

表示给定区域的 Excel 数字格式代码单元格。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。

getNumberFormat(): string;

string

getNumberFormatCategories()

表示每个单元格的数字格式的类别。

getNumberFormatCategories(): NumberFormatCategory[][];

ExcelScript.NumberFormatCategory[][]

示例

/**
 * This script finds cells in a table column that are not formatted as currency
 * and sets the fill color to red.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the "Cost" column from the "Expenses" table.
  const table = workbook.getTable("Expenses");
  const costColumn = table.getColumnByName("Cost");
  const costColumnRange = costColumn.getRangeBetweenHeaderAndTotal();

  // Get the number format categories for the column's range.
  const numberFormatCategories = costColumnRange.getNumberFormatCategories();

  // If any cell in the column doesn't have a currency format, make the cell red.
  numberFormatCategories.forEach((category, index) =>{
    if (category[0] != ExcelScript.NumberFormatCategory.currency) {
      costColumnRange.getCell(index, 0).getFormat().getFill().setColor("red");
    }
  }); 
}

getNumberFormatCategory()

指定区域中第一个单元格的数字格式类别 (行索引为 0，列索引为 0) 表示。

getNumberFormatCategory(): NumberFormatCategory;

ExcelScript.NumberFormatCategory

getNumberFormatLocal()

表示基于用户语言设置的给定区域的 Excel 数字格式代码单元格。获取或设置 numberFormatLocal 属性时，Excel 不执行任何语言或格式强制。任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。

getNumberFormatLocal(): string;

string

getNumberFormats()

表示给定区域的 Excel 数字格式代码。

getNumberFormats(): string[][];

string[][]

getNumberFormatsLocal()

表示基于用户语言设置的给定区域的 Excel 数字格式代码。获取或设置 numberFormatLocal 属性时，Excel 不执行任何语言或格式强制。任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。

getNumberFormatsLocal(): string[][];

string[][]

getOffsetRange(rowOffset, columnOffset)

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

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

参数

rowOffset: number

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

columnOffset: number

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

ExcelScript.Range

示例

/**
 * This script gets adjacent cells using relative references.
 * Note that if the active cell is on the top row, part of the script fails, 
 * because it references the cell above the currently selected one.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the currently active cell in the workbook.
  let activeCell = workbook.getActiveCell();
  console.log(`The active cell's address is: ${activeCell.getAddress()}`);

  // Get the cell to the right of the active cell and set its value and color.
  let rightCell = activeCell.getOffsetRange(0,1);
  rightCell.setValue("Right cell");
  console.log(`The right cell's address is: ${rightCell.getAddress()}`);
  rightCell.getFormat().getFont().setColor("Magenta");
  rightCell.getFormat().getFill().setColor("Cyan");

  // Get the cell to the above of the active cell and set its value and color.
  // Note that this operation will fail if the active cell is in the top row.
  let aboveCell = activeCell.getOffsetRange(-1, 0);
  aboveCell.setValue("Above cell");
  console.log(`The above cell's address is: ${aboveCell.getAddress()}`);
  aboveCell.getFormat().getFont().setColor("White");
  aboveCell.getFormat().getFill().setColor("Black");
}

getPivotTables(fullyContained)

获取与区域重叠的数据透视表的作用域集合。

getPivotTables(fullyContained?: boolean): PivotTable[];

参数

fullyContained: boolean

如果 true为，则仅返回完全包含在范围边界中的数据透视表。默认值 false为。

ExcelScript.PivotTable[]

getPredefinedCellStyle()

表示当前区域的样式。如果单元格的样式不一致， null 将返回。对于自定义样式，将返回样式名称。对于内置样式，将返回表示枚举中的 BuiltInStyle 值的字符串。

getPredefinedCellStyle(): string;

string

getRangeEdge(direction, activeCell)

返回一个 range 对象，该对象是与提供的方向对应的数据区域边缘单元格。这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。

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

参数

direction: ExcelScript.KeyboardDirection

活动单元格的方向。

activeCell: ExcelScript.Range | string

此区域中的活动单元格。默认情况下，活动单元格是区域的左上角单元格。如果活动单元格不在此范围内，则会引发错误。

ExcelScript.Range

示例

/**
 * This script adds the value "Total" after the end of the first column.
 */
function main(workbook: ExcelScript.Workbook)
{
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the last used cell at the end of the column.
  // This recreates the Ctrl+Down arrow key behavior.
  let firstCell = selectedSheet.getRange("A1");
  let firstColumn = selectedSheet.getRange("A1").getRangeEdge(ExcelScript.KeyboardDirection.down);
  let cellAfter = firstColumn.getOffsetRange(1, 0);

  // Set the value of the cell after the current end of the used column to "Total".
  cellAfter.setValue("Total");
}

getResizedRange(deltaRows, deltaColumns)

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

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

参数

deltaRows: number

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

deltaColumns: number

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

ExcelScript.Range

示例

/**
 * This script copies the formatting in the active cell to the neighboring cells.
 * Note that this script only works when the active cell isn't on an edge of the worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active cell.
  let activeCell = workbook.getActiveCell();

  // Get the cell that's one row above and one column to the left of the active cell.
  let cornerCell = activeCell.getOffsetRange(-1,-1);

  // Get a range that includes all the cells surrounding the active cell.
  let surroundingRange = cornerCell.getResizedRange(2, 2)

  // Copy the formatting from the active cell to the new range.
  surroundingRange.copyFrom(
    activeCell, /* The source range. */
    ExcelScript.RangeCopyType.formats /* What to copy. */
  );
}

getRow(row)

获取范围中包含的行。

getRow(row: number): Range;

参数

row: number

要检索的区域的行号。从零开始编制索引。

ExcelScript.Range

getRowCount()

返回区域中的总行数。

getRowCount(): number;

number

示例

/**
 * This sample provides the count of negative numbers that are present
 * in the used range of the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the working range.
  let usedRange = workbook.getActiveWorksheet().getUsedRange();
  let rowCount = usedRange.getRowCount();
  let columnCount = usedRange.getColumnCount();

  // Save the values locally to avoid repeatedly asking the workbook.
  let usedRangeValues = usedRange.getValues();

  // Start the negative number counter.
  let negativeCount = 0;

  // Iterate over the entire range looking for negative numbers.
  for (let i = 0; i < rowCount; i++) {
    for (let j = 0; j < columnCount; j++) {
      if (usedRangeValues[i][j] < 0) {
        negativeCount++;
      }
    }
  }

  // Log the negative number count to the console.
  console.log(negativeCount);
}

getRowHidden()

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

getRowHidden(): boolean;

boolean

getRowIndex()

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

getRowIndex(): number;

number

getRowsAbove(count)

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

getRowsAbove(count?: number): Range;

参数

count: number

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

ExcelScript.Range

getRowsBelow(count)

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

getRowsBelow(count?: number): Range;

参数

count: number

ExcelScript.Range

getSavedAsArray()

表示是否将所有单元格另存为数组公式。 true如果所有单元格都另存为数组公式，或者false所有单元格不另存为数组公式，则返回。 null如果某些单元格将保存为数组公式，而有些单元格则不保存，则返回。

getSavedAsArray(): boolean;

boolean

getSort()

表示当前 range 的区域排序。

getSort(): RangeSort;

ExcelScript.RangeSort

getSpecialCells(cellType, cellValueType)

RangeAreas获取由一个或多个区域组成的对象，该对象表示与指定类型和值匹配的所有单元格。如果未找到任何特殊单元格，则此方法返回 undefined。

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

参数

cellType: ExcelScript.SpecialCellType

要包含的单元格类型。

cellValueType: ExcelScript.SpecialCellValueType

如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。这些值可以组合在一起以返回多个类型。默认情况下，将选择所有常量或公式，无论类型如何。

ExcelScript.RangeAreas

示例

/**
 * This sample gets all the blank cells in the current worksheet's used range. It then highlights all those cells with a yellow background.
 */
function main(workbook: ExcelScript.Workbook) {
    // Get the current used range.
    let range = workbook.getActiveWorksheet().getUsedRange();
    
    // Get all the blank cells.
    let blankCells = range.getSpecialCells(ExcelScript.SpecialCellType.blanks);
    // Highlight the blank cells with a yellow background.
    blankCells.getFormat().getFill().setColor("yellow");
}

getSpillingToRange()

获取 Range 对象，它在调用定位单元格时包含溢出区域。如果区域不是定位点单元格或找不到溢出区域，则此方法返回 undefined。

getSpillingToRange(): Range;

ExcelScript.Range

getSpillParent()

获取包含要溢出到的单元格的定位单元格的范围对象。如果它不是溢出的单元格，或者提供了多个单元格，则此方法返回 undefined。

getSpillParent(): Range;

ExcelScript.Range

getSurroundingRegion()

返回一个 Range 对象，该对象代表此区域中左上角单元格的周围区域。周围区域是由相对于该区域的空白行和空白列的任何组合所限定的区域。

getSurroundingRegion(): Range;

ExcelScript.Range

getTables(fullyContained)

获取与区域重叠的限定范围的表格集合。

getTables(fullyContained?: boolean): Table[];

参数

fullyContained: boolean

如果 true为，则仅返回完全包含在范围边界内的表。默认值 false为。

ExcelScript.Table[]

getText()

表示指定范围的 Text 值。文本值与单元格宽度无关。在 Excel UI 中替代 # 符号不会影响 API 返回的文本值。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。

getText(): string;

string

getTexts()

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

getTexts(): string[][];

string[][]

getTop()

返回从工作表上边缘到区域上边缘的 100% 缩放的距离（以磅为单位）。

getTop(): number;

number

getUsedRange(valuesOnly)

返回指定 range 对象的所用区域。如果区域中没有使用单元格，则此方法返回 undefined。

getUsedRange(valuesOnly?: boolean): Range;

参数

valuesOnly: boolean

仅将有值的单元格视为已使用的单元格。

ExcelScript.Range

getValue()

表示指定范围的原始值。返回的数据可能是字符串、数字，也可能是布尔值。包含错误的单元格将返回错误字符串。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。

getValue(): string | number | boolean;

string | number | boolean

示例

/**
 * This sample reads the value of A1 and prints it to the console.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the value of cell A1.
  let range = selectedSheet.getRange("A1");
  
  // Print the value of A1.
  console.log(range.getValue());
}

getValues()

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

getValues(): (string | number | boolean)[][];

(string | number | boolean)[][]

getValueType()

表示单元格中的数据类型。如果区域包含多个单元格，则将返回第一个单元格中的数据 (行索引为 0，列索引为 0) 表示。

getValueType(): RangeValueType;

ExcelScript.RangeValueType

示例

/**
 * This script formats rows in a worksheet based on the first value in that row. 
 * If it's the boolean value TRUE, the row is bolded. 
 * If it's FALSE, nothing is changed. 
 * If the value type isn't a boolean, the row is italicized.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the used range in the active worksheet.
  const sheet = workbook.getActiveWorksheet();
  const usedRange = sheet.getUsedRange();

  // Get the values in the first column.
  const firstColumnValues = usedRange.getColumn(0).getValues();

  // Look at the first cell in each row.
  const rowCount = usedRange.getRowCount();
  for (let i = 0; i < rowCount; i++) {
    // Get the type of the first cell to make sure it's a boolean.
    let firstValueType = usedRange.getCell(i, 0).getValueType();

    // Set the bold or italic of the row as described earlier.
    if (firstValueType === ExcelScript.RangeValueType.boolean) {
      if (firstColumnValues[i][0] as boolean === true) {
        usedRange.getRow(i).getFormat().getFont().setBold(true);
      } else {
        usedRange.getRow(i).getFormat().getFont().setBold(false);
      }
    } else {
      usedRange.getRow(i).getFormat().getFont().setItalic(true);
    }
  }
}

getValueTypes()

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

getValueTypes(): RangeValueType[][];

ExcelScript.RangeValueType[][]

getVisibleView()

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

getVisibleView(): RangeView;

ExcelScript.RangeView

示例

/**
 * This script copies values and formatting from the 
 * visible range of a table in Sheet1 into Sheet2.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the filtered data from Sheet1.
  const currentSheet = workbook.getWorksheet("Sheet1");
  const table = currentSheet.getTables()[0];
  const visibleTableRange: ExcelScript.RangeView = table.getRange().getVisibleView();
  const source = currentSheet.getRanges(visibleTableRange.getCellAddresses().toString());

  // Copy the data into the other sheet.
  const otherSheet = workbook.getWorksheet("Sheet2");
  const otherRangeCorner = otherSheet.getRange("A1");
  otherRangeCorner.copyFrom(source, ExcelScript.RangeCopyType.all);
}

getWidth()

返回从范围的左边缘到范围右边缘的 100% 缩放的距离（以磅为单位）。

getWidth(): number;

number

getWorksheet()

包含当前区域的工作表。

getWorksheet(): Worksheet;

ExcelScript.Worksheet

group(groupOption)

组大纲的列和行。

group(groupOption: GroupOption): void;

参数

groupOption: ExcelScript.GroupOption

指定如何按行或列对区域进行分组。 InvalidArgument当组选项不同于范围isEntireRow或isEntireColumn属性 (即range.isEntireRow为 true 且groupOption为“ByColumns”或range.isEntireColumn为 true 且groupOption为“ByRows”) 时，将引发错误。

void

示例

/**
 * This script creates a two-level column-based outline on Sheet1.
 */
function main(workbook: ExcelScript.Workbook) {
  // Group columns A-F in the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const firstLevel = sheet.getRange("A:F");
  firstLevel.group(ExcelScript.GroupOption.byColumns);
  
  // Create a second level to the outline by grouping subsections.
  sheet.getRange("A:B").group(ExcelScript.GroupOption.byColumns);
  sheet.getRange("D:E").group(ExcelScript.GroupOption.byColumns);
}

hideGroupDetails(groupOption)

隐藏行或列组的详细信息。

hideGroupDetails(groupOption: GroupOption): void;

参数

groupOption: ExcelScript.GroupOption

指定是隐藏分组行的详细信息还是分组列的详细信息。

void

insert(shift)

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

insert(shift: InsertShiftDirection): Range;

参数

shift: ExcelScript.InsertShiftDirection

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

ExcelScript.Range

示例

/**
 * This script inserts headers at the top of the worksheet.
 */
function main(workbook: ExcelScript.Workbook)
{
  let currentSheet = workbook.getActiveWorksheet();

  // Create headers for 3 columns.
  let myHeaders = [["NAME", "ID", "ROLE"]];

  // Add a blank first row and push existing data down a row.
  let firstRow = currentSheet.getRange("1:1");
  firstRow.insert(ExcelScript.InsertShiftDirection.down);

  // Add the headers.
  currentSheet.getRange("A1:C1").setValues(myHeaders);
}

merge(across)

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

merge(across?: boolean): void;

参数

across: boolean

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

void

示例

/**
 * This script merges a group of cells into a single region.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active worksheet.
  const selectedSheet = workbook.getActiveWorksheet();

  // Merge cells A1 through A4.
  const range = selectedSheet.getRange("A1:A4");
  range.merge();
}

moveTo(destinationRange)

将单元格值、格式和公式从当前区域移动到目标区域，替换这些单元格中的旧信息。如果目标范围小于当前范围，则会自动扩展。不会更改目标区域中超出原始区域区域的任何单元格。

moveTo(destinationRange: Range | string): void;

参数

destinationRange: ExcelScript.Range | string

destinationRange 指定将移动此区域中的信息的区域。

void

removeDuplicates(columns, includesHeader)

从列指定的区域中删除重复值。

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

参数

columns: number[]

范围内可能包含重复项的列。至少需要指定一列。从零开始编制索引。

includesHeader: boolean

如果输入数据包含标头，则为 True。默认为 false。

ExcelScript.RemoveDuplicatesResult

示例

/**
 * This script removes duplicate rows from a range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the used range of the active worksheet.
  const usedRange = workbook.getActiveWorksheet().getUsedRange();

  // Remove any row that has a same value in the 0-indexed column as a previous row.
  const removedResults = usedRange.removeDuplicates([0], true);

  // Log the count of removed rows.
  console.log(`Rows removed: ${removedResults.getRemoved()}.`);
}

replaceAll(text, replacement, criteria)

根据当前区域内指定的条件查找并替换给定的字符串。

replaceAll(
            text: string,
            replacement: string,
            criteria: ReplaceCriteria
        ): number;

参数

text: string

要查找的字符串。

replacement: string

替换原始字符串的字符串。

criteria: ExcelScript.ReplaceCriteria

其他替换条件。

number

示例

/**
 * This script searches through a table column and replaces  
 * cells marked "monthly special" with "parsnip".
 * This script uses Range.replaceAll instead of Worksheet.replaceAll
 * to limit the search to a specific range.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range of a table named "Orders".
  let table = workbook.getTable("Orders");
  let range = table.getColumnByName("Vegetable").getRange();
  
  // Change the value of any cells with the value "monthly special".
  range.replaceAll("monthly special", "parsnip", {completeMatch: true});
}

select()

在 Excel UI 中选择指定的区域。

select(): void;

void

示例

/**
 * This script selects the first row of a table.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the first table on the current worksheet.
  const sheet = workbook.getActiveWorksheet()
  const table = sheet.getTables()[0];

  // Get the first data row in the table.
  const row = table.getRangeBetweenHeaderAndTotal().getRow(0);

  // Select the first data row.
  row.select();
}

setColumnHidden(columnHidden)

setColumnHidden(columnHidden: boolean): void;

参数

columnHidden: boolean

void

setDirty()

设置下一次重新计算发生时要重新计算的区域。

setDirty(): void;

void

setFormula(formula)

以 A1 样式表示法设置单元格公式。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。

setFormula(formula: string): void;

参数

formula: string

void

示例

/*
 * This script sets a cell's formula, 
 * then displays how Excel stores the cell's formula and value separately.
 */
function main(workbook: ExcelScript.Workbook) {
  let selectedSheet = workbook.getActiveWorksheet();

  // Set A1 to 2.
  let a1 = selectedSheet.getRange("A1");
  a1.setValue(2);

  // Set B1 to the formula =(2*A1), which should equal 4.
  let b1 = selectedSheet.getRange("B1")
  b1.setFormula("=(2*A1)");

  // Log the current results for `getFormula` and `getValue` at B1.
  console.log(`B1 - Formula: ${b1.getFormula()} | Value: ${b1.getValue()}`);
}

setFormulaLocal(formulaLocal)

在用户的语言和数字格式区域设置中，以 A1 样式表示法设置单元格公式。例如，英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。

setFormulaLocal(formulaLocal: string): void;

参数

formulaLocal: string

void

setFormulaR1C1(formulaR1C1)

以 R1C1 样式表示法设置单元格公式。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。

setFormulaR1C1(formulaR1C1: string): void;

参数

formulaR1C1: string

void

setFormulas(formulas)

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

setFormulas(formulas: string[][]): void;

参数

formulas: string[][]

void

示例

/**
 * This script sets the values of a range, then adds SUM formulas to calculate
 * the totals for each row of that range. 
 */
function main(workbook: ExcelScript.Workbook)
{
  let currentSheet = workbook.getActiveWorksheet();

  // Set the values of a range.
  let values = [[1, 2, 4], [8, 16, 32], [64, 128, 256]];
  let valueRange = currentSheet.getRange("A1:C3");
  valueRange.setValues(values);

  // Set the formulas of a range.
  let formulas = [["=SUM(A1:C1)"], ["=SUM(A2:C2)"], ["=SUM(A3:C3)"]];
  let formulaRange = currentSheet.getRange("D1:D3");
  formulaRange.setFormulas(formulas);
}

setFormulasLocal(formulasLocal)

setFormulasLocal(formulasLocal: string[][]): void;

参数

formulasLocal: string[][]

void

setFormulasR1C1(formulasR1C1)

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

setFormulasR1C1(formulasR1C1: string[][]): void;

参数

formulasR1C1: string[][]

void

setHyperlink(hyperlink)

表示当前范围的超链接。

setHyperlink(hyperlink: RangeHyperlink): void;

参数

hyperlink: ExcelScript.RangeHyperlink

void

示例

/** 
 * This script inserts a hyperlink to the first cell of the last worksheet in the workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active cell.
  let cell = workbook.getActiveCell();

  // Get the last worksheet in the workbook.
  // Note that this might be the current sheet if there's only one worksheet.
  let lastSheet = workbook.getLastWorksheet();

  // Get sheet name. 
  let linkedSheetName = lastSheet.getName();
  console.log(`Setting hyperlink of ${cell.getAddress()} to the ${linkedSheetName} sheet's A1 cell`);

  // Set the text for the hyperlink.
  let value = `Click to go to: ${linkedSheetName}`;

  // Create the hyperlink using that cell's value.
  cell.setHyperlink({
    textToDisplay: value.toString(),
    screenTip: `Navigate to ${linkedSheetName}`,
    documentReference: `${linkedSheetName}!A1`
  });
}

setNumberFormat(numberFormat)

设置给定区域的单元格 Excel 数字格式代码。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。

setNumberFormat(numberFormat: string): void;

参数

numberFormat: string

void

示例

/**
 * This script sets the number format in column C to show the data as a percentage.
 */
function main(workbook: ExcelScript.Workbook) {
  const  selectedSheet = workbook.getActiveWorksheet();
  
  // Set number format for column C to a percentage that rounds to the nearest percentage point.
  selectedSheet.getRange("C:C").setNumberFormat("0%");
}

setNumberFormatLocal(numberFormatLocal)

根据用户的语言设置，设置给定区域的 Excel 数字格式代码。获取或设置 numberFormatLocal 属性时，Excel 不执行任何语言或格式强制。任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。

setNumberFormatLocal(numberFormatLocal: string): void;

参数

numberFormatLocal: string

void

示例

/**
 * This script sets the number format in column D to show the data as a percentage with a decimal.
 */
function main(workbook: ExcelScript.Workbook) {
  const  selectedSheet = workbook.getActiveWorksheet();
  
  // Set number format for column D to a percentage that rounds to the nearest tenth of a percentage.
  selectedSheet.getRange("D:D").setNumberFormatLocal("0.0%");
}

setNumberFormats(numberFormats)

表示给定区域的 Excel 数字格式代码。

setNumberFormats(numberFormats: string[][]): void;

参数

numberFormats: string[][]

void

setNumberFormatsLocal(numberFormatsLocal)

setNumberFormatsLocal(numberFormatsLocal: string[][]): void;

参数

numberFormatsLocal: string[][]

void

setPredefinedCellStyle(predefinedCellStyle)

表示当前区域的样式。

setPredefinedCellStyle(predefinedCellStyle: string): void;

参数

predefinedCellStyle: string

void

setRowHidden(rowHidden)

setRowHidden(rowHidden: boolean): void;

参数

rowHidden: boolean

void

setValue(value)

设置指定范围的原始值。所设置的数据可以是字符串、数字或布尔值。 null (Excel) 中未设置或覆盖 value 将被忽略。如果区域包含多个单元格，则给定区域中的每个单元格都将使用输入数据进行更新。

setValue(value: any): void;

参数

value: any

void

setValues(values)

设置指定范围的原始值。提供的数据可以是字符串、数字或布尔值。如果提供的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头，Excel 会将此值解释为公式。

setValues(values: (string | number | boolean)[][]): void;

参数

values: (string | number | boolean)[][]

void

示例

/**
 * This sample inserts some pre-loaded data into a range.
 * It also shows how to get a range that fits the data.
 */
 function main(workbook: ExcelScript.Workbook) {
   // Get the active cell.
   let currentCell = workbook.getActiveCell();
   
   // Calculate the range needed to fit the given data.
   let targetRange = currentCell.getResizedRange(DATA.length - 1, DATA[0].length - 1);

   // Set range values to the data.
   targetRange.setValues(DATA);

   // Autofit the columns so the worksheet is readable. 
   targetRange.getFormat().autofitColumns();
 }

 /* 
  * This sample's data is in a static 2-dimensional array.
  * You could also get the input from other ranges or sources.
  * Note that each row must have the same number of columns to be valid. 
  */
 const DATA = [
   ['Date', 'Salesperson', 'Product', 'Amount']
   , ['3/2/2020', 'Anne', 'Pizza', '$1400']
   , ['3/2/2020', 'Mariya', 'Pizza', '$1700']
   , ['3/7/2020', 'Mark', 'Sandwiches', '$1010']
   , ['3/24/2020', 'Anne', 'Pizza', '$750']
   , ['3/28/2020', 'Mark', 'Salads', '$510']
   , ['4/17/2020', 'Laura', 'Salads', '$900']
   , ['4/17/2020', 'Mariya', 'Salads', '$1600']
   , ['4/28/2020', 'Laura', 'Sandwiches', '$680']
 ];

showCard()

显示活动单元格的卡片（如果该单元格具有富值内容）。

showCard(): void;

void

showGroupDetails(groupOption)

显示行或列组的详细信息。

showGroupDetails(groupOption: GroupOption): void;

参数

groupOption: ExcelScript.GroupOption

指定是显示分组行的详细信息还是分组列的详细信息。

void

ungroup(groupOption)

取消对大纲的列和行的分组。

ungroup(groupOption: GroupOption): void;

参数

groupOption: ExcelScript.GroupOption

指定如何按行或列取消组合区域。

void

unmerge()

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

unmerge(): void;

void

示例

/**
 * This script unmerges every used cell in the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the active worksheet.
  const selectedSheet = workbook.getActiveWorksheet();

  // Separate all regions into single cells in the currently used range.
  const range = selectedSheet.getUsedRange();
  range.unmerge();
}