Использование встроенных объектов JavaScript в сценариях Office

Статья
04/07/2023

JavaScript предоставляет несколько встроенных объектов, которые можно использовать в сценариях Office, независимо от того, выполняете ли вы скрипты в JavaScript или TypeScript (надмножество JavaScript). В этой статье описывается использование некоторых встроенных объектов JavaScript в скриптах Office для Excel.

Примечание.

Полный список всех встроенных объектов 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 содержатся в коллекции. Коллекция управляется API сценариев Office и предоставляется в виде массива. Например, все фигуры на листе содержатся в объекте Shape[] , возвращаемом методом Worksheet.getShapes . Этот массив можно использовать для чтения значений из коллекции или получить доступ к определенным объектам из методов родительского объекта get* .

Примечание.

Не добавляйте и не удаляйте объекты из этих массивов коллекций вручную. Используйте методы add для родительских объектов и delete методы для объектов типа коллекции. Например, добавьте таблицу на лист с Worksheet.addTable помощью метода и удалите с Table помощью Table.delete.

Следующий скрипт регистрирует тип каждой фигуры на текущем листе.

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 и API скриптов Office.

Поделиться через