ExcelScript.Range interface

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

addConditionalFormat(type: ConditionalFormatType): 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.
  });
}

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

autoFill(
            destinationRange?: Range | string,
            autoFillType?: AutoFillType
        ): 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(): 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?: 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(): void;

返回

清除区域中单元格的值，并特别考虑包含控件的单元格。 如果区域仅包含空白值和设置为默认值的控件，则会删除值和控件格式。 否则，这会将包含控件的单元格设置为默认值，并清除区域中其他单元格的值。

clearOrResetContents(): void;

返回

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

convertDataTypeToText(): void;

返回

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

copyFrom(
            sourceRange: Range | RangeAreas | string,
            copyType?: RangeCopyType,
            skipBlanks?: boolean,
            transpose?: boolean
        ): 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: 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()); 
}

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

find(text: string, criteria: SearchCriteria): 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(): 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();
}

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

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

参数

返回

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

getAddress(): 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(): string;

返回

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

getBoundingRect(anotherRange: Range | string): 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
}

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

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

参数

返回

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

getCellCount(): number;

返回

获取范围中包含的列。

getColumn(column: number): Range;

参数

返回

指定区域中的列总数。

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

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

getColumnHidden(): boolean;

返回

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

getColumnIndex(): number;

返回

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

getColumnsAfter(count?: number): Range;

参数

返回

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

getColumnsBefore(count?: number): Range;

参数

返回

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

getConditionalFormat(id: string): ConditionalFormat | undefined;

参数

返回

与范围相交的 的 集合 ConditionalFormats 。

getConditionalFormats(): ConditionalFormat[];

返回

访问应用于此区域的单元格控件。 如果区域有多个单元格控件，则返回 EmptyCellControl。

getControl(): CellControl;

返回

返回数据有效性对象。

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

返回一个 WorkbookRangeAreas 对象，该对象表示包含同一工作表中或多个工作表中指定区域的所有依赖单元格的区域。 ItemNotFound如果未找到依赖项，则引发错误。

getDependents(): WorkbookRangeAreas;

返回

返回一个 对象，该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有直接依赖单元格的区域。 ItemNotFound如果未找到依赖项，则引发错误。

getDirectDependents(): WorkbookRangeAreas;

返回

返回一个 WorkbookRangeAreas 对象，该对象表示包含同一工作表中或跨多个工作表的指定区域的所有直接引用单元格的区域。 ItemNotFound如果未找到任何先例，则引发错误。

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

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

getEntireColumn(): Range;

返回

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

getEntireRow(): Range;

返回

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

getExtendedRange(
            direction: KeyboardDirection,
            activeCell?: Range | string
        ): 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(): 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");
}

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

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

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

getFormulaLocal(): string;

返回

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

getFormulaR1C1(): string;

返回

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

getFormulas(): string[][];

返回

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

getFormulasLocal(): string[][];

返回

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

getFormulasR1C1(): string[][];

返回

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

getHasSpill(): boolean;

返回

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

getHeight(): number;

返回

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

getHidden(): boolean;

返回

表示当前范围的超链接。

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

将范围呈现为 Base64 编码的 PNG 图像。

getImage(): string;

返回

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

getIntersection(anotherRange: Range | string): Range;

参数

返回

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

getIsEntireColumn(): boolean;

返回

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

getIsEntireRow(): boolean;

返回

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

getLastCell(): Range;

返回

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

getLastColumn(): Range;

返回

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

getLastRow(): Range;

返回

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

getLeft(): number;

返回

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

getLinkedDataTypeState(): LinkedDataTypeState;

返回

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

getLinkedDataTypeStates(): LinkedDataTypeState[][];

返回

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

getMergedAreas(): RangeAreas;

返回

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

getNumberFormat(): string;

返回

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

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

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

getNumberFormatCategory(): NumberFormatCategory;

返回

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

getNumberFormatLocal(): string;

返回

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

getNumberFormats(): string[][];

返回

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

getNumberFormatsLocal(): string[][];

返回

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

getOffsetRange(rowOffset: number, columnOffset: number): 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?: boolean): PivotTable[];

参数

返回

返回一个 对象，该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有前置单元格的区域。 ItemNotFound如果未找到任何先例，则引发错误。

getPrecedents(): WorkbookRangeAreas;

返回

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

getPredefinedCellStyle(): string;

返回

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

getRangeEdge(
            direction: KeyboardDirection,
            activeCell?: Range | string
        ): 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");
}

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

getResizedRange(deltaRows: number, deltaColumns: number): 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: number): Range;

参数

返回

返回区域中的总行数。

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

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

getRowHidden(): boolean;

返回

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

getRowIndex(): number;

返回

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

getRowsAbove(count?: number): Range;

参数

返回

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

getRowsBelow(count?: number): Range;

参数

返回

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

getSavedAsArray(): boolean;

返回

表示当前 range 的区域排序。

getSort(): RangeSort;

返回

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

getSpecialCells(
            cellType: SpecialCellType,
            cellValueType?: SpecialCellValueType
        ): 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");
}

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

getSpillingToRange(): Range;

返回

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

getSpillParent(): Range;

返回

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

getSurroundingRegion(): Range;

返回

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

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

参数

返回

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

getText(): string;

返回

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

getTexts(): string[][];

返回

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

getTop(): number;

返回

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

getUsedRange(valuesOnly?: boolean): Range;

参数

返回

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

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

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

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

返回

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

getValueType(): 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(): RangeValueType[][];

返回

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

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

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

getWidth(): number;

返回

包含当前区域的工作表。

getWorksheet(): Worksheet;

返回

对大纲的列和行进行分组。

group(groupOption: GroupOption): 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: GroupOption): void;

参数

返回

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

insert(shift: InsertShiftDirection): 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?: boolean): 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: Range | string): void;

参数

返回

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

removeDuplicates(
            columns: number[],
            includesHeader: boolean
        ): 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: string,
            replacement: string,
            criteria: 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});
}

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

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

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

setColumnHidden(columnHidden: boolean): void;

参数

返回

访问应用于此区域的单元格控件。 如果区域有多个单元格控件，则返回 EmptyCellControl。

setControl(control: CellControl): void;

参数

返回

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

setDirty(): void;

返回

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

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

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

setFormulaLocal(formulaLocal: string): void;

参数

返回

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

setFormulaR1C1(formulaR1C1: string): void;

参数

返回

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

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

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

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

参数

返回

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

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

参数

返回

表示当前范围的超链接。

setHyperlink(hyperlink: 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`
  });
}

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

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

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

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

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

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

参数

返回

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

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

参数

返回

表示当前区域的样式。

setPredefinedCellStyle(predefinedCellStyle: string): void;

参数

返回

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

setRowHidden(rowHidden: boolean): void;

参数

返回

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

setValue(value: any): void;

参数

返回

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

setValues(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(): void;

返回

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

showGroupDetails(groupOption: GroupOption): void;

参数

返回

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

ungroup(groupOption: GroupOption): void;

参数

返回

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

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