通过

在 Office 脚本中使用内置 JavaScript 对象

  • 项目

JavaScript 提供了多个可在 Office 脚本中使用的内置对象，无论你是在 JavaScript 还是 TypeScript 中编写脚本， (JavaScript) 超集。 本文介绍如何在 Office 脚本 for Excel 中使用一些内置 JavaScript 对象。

注意

有关所有内置 JavaScript 对象的完整列表，请参阅 Mozilla 的标准内置对象 一文。

Array

Array 对象提供了一种使用脚本中的数组的标准化方法。 虽然数组是标准 JavaScript 构造，但它们在两个主要方面与 Office 脚本相关：范围和集合。

使用范围

区域包含多个直接映射到该区域中单元格的二维数组。 这些数组包含有关该区域中每个单元格的特定信息。 例如， Range.getValues 返回这些单元格中的所有值， (二维数组的行和列映射到该工作表子节的行和列) 。 Range.getFormulas 和 Range.getNumberFormats 是返回数组的其他常用方法，如 Range.getValues。

以下脚本在 A1：D4 范围中搜索包含“$”的任何数字格式。 脚本将这些单元格中的填充颜色设置为“黄色”。

function main(workbook: ExcelScript.Workbook) {
  // Get the range From A1 to D4.
  let range = workbook.getActiveWorksheet().getRange("A1:D4");

  // Get the number formats for each cell in the range.
  let rangeNumberFormats = range.getNumberFormats();
  // Iterate through the arrays of rows and columns corresponding to those in the range.
  rangeNumberFormats.forEach((rowItem, rowIndex) => {
    rangeNumberFormats[rowIndex].forEach((columnItem, columnIndex) => {
      // Treat the numberFormat as a string so we can do text comparisons.
      let columnItemText = columnItem as string;
      if (columnItemText.indexOf("$") >= 0) {
        // Set the cell's fill to yellow.
        range.getCell(rowIndex, columnIndex).getFormat().getFill().setColor("yellow");
      }
    });
  });
}

使用集合

集合中包含许多 Excel 对象。 集合由 Office 脚本 API 管理，并公开为数组。 例如，工作表中的所有 Shapes 都包含在 方法Worksheet.getShapes返回的 中Shape[]。 可以使用此数组从集合中读取值，也可以从父对象的 方法访问特定对象 get* 。

注意

不要手动在这些集合数组中添加或删除对象。 对 add 父对象使用方法， delete 对集合类型对象使用 方法。 例如，使用 Worksheet.addTable 方法将 Table 添加到工作表，并使用 Table.delete删除 Table 。

以下脚本记录当前工作表中每个形状的类型。

function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the shapes in this worksheet.
  let shapes = selectedSheet.getShapes();

  // Log the type of every shape in the collection.
  shapes.forEach((shape) => {
    console.log(shape.getType());
  });
}

以下脚本删除当前工作表中最早的形状。

function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the first (oldest) shape in the worksheet.
  // Note that this script will thrown an error if there are no shapes.
  let shape = selectedSheet.getShapes()[0];

  // Remove the shape from the worksheet.
  shape.delete();
}

日期

Date 对象提供了一种在脚本中使用日期的标准化方法。 Date.now() 生成具有当前日期和时间的对象，这在将时间戳添加到脚本的数据条目时很有用。

以下脚本将当前日期添加到工作表。 请注意，通过使用 toLocaleDateString 方法，Excel 会将值识别为日期，并自动更改单元格的数字格式。

function main(workbook: ExcelScript.Workbook) {
  // Get the range for cell A1.
  let range = workbook.getActiveWorksheet().getRange("A1");

  // Get the current date and time.
  let date = new Date(Date.now());

  // Set the value at A1 to the current date, using a localized string.
  range.setValue(date.toLocaleDateString());
}

示例的“ 使用日期 ”部分包含更多与日期相关的脚本。

数学

Math 对象为常见数学运算提供方法和常量。 这些函数在 Excel 中也提供了许多函数，而无需使用工作簿的计算引擎。 这样，脚本就不必查询工作簿，从而提高了性能。

以下脚本使用 Math.min 查找并记录 A1：D4 范围中的最小数字。 请注意，此示例假定整个范围仅包含数字，而不包含字符串。

function main(workbook: ExcelScript.Workbook) {
  // Get the range from A1 to D4.
  let comparisonRange = workbook.getActiveWorksheet().getRange("A1:D4");

  // Load the range's values.
  let comparisonRangeValues = comparisonRange.getValues();

  // Set the minimum values as the first value.
  let minimum = comparisonRangeValues[0][0];

  // Iterate over each row looking for the smallest value.
  comparisonRangeValues.forEach((rowItem, rowIndex) => {
    // Iterate over each column looking for the smallest value.
    comparisonRangeValues[rowIndex].forEach((columnItem) => {
      // Use `Math.min` to set the smallest value as either the current cell's value or the previous minimum.
      minimum = Math.min(minimum, columnItem);
    });
  });

  console.log(minimum);
}

不支持使用外部 JavaScript 库

Office 脚本不支持使用外部第三方库。 脚本只能使用内置 JavaScript 对象和 Office 脚本 API。

另请参阅