Usar objetos JavaScript internos em Scripts do Office

Artigo
04/07/2023

O JavaScript fornece vários objetos internos que você pode usar em seus Scripts do Office, independentemente de você estar fazendo scripts em JavaScript ou TypeScript (um superconjunto de JavaScript). Este artigo descreve como usar alguns dos objetos JavaScript internos em Scripts do Office para Excel.

Observação

Para obter uma lista completa de todos os objetos JavaScript internos, consulte o artigo Objetos internos Standard da Mozilla.

Matriz

O objeto Array fornece uma maneira padronizada de trabalhar com matrizes em seu script. Embora as matrizes sejam construções JavaScript padrão, elas se relacionam com scripts do Office de duas maneiras principais: intervalos e coleções.

Trabalhar com intervalos

Os intervalos contêm várias matrizes bidimensionais que mapeiam diretamente para as células nesse intervalo. Essas matrizes contêm informações específicas sobre cada célula nesse intervalo. Por exemplo, Range.getValues retorna todos os valores nessas células (com as linhas e colunas do mapeamento de matriz bidimensional para as linhas e colunas dessa subseção de planilha). Range.getFormulas e Range.getNumberFormats são outros métodos usados com frequência que retornam matrizes como Range.getValues.

O script a seguir pesquisa o intervalo A1:D4 para qualquer formato de número que contenha um "$". O script define a cor de preenchimento nessas células como "amarela".

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

Trabalhar com coleções

Muitos objetos do Excel estão contidos em uma coleção. A coleção é gerenciada pela API de Scripts do Office e exposta como uma matriz. Por exemplo, todas as formas em uma planilha estão contidas em um Shape[] que é retornado pelo Worksheet.getShapes método. Você pode usar essa matriz para ler valores da coleção ou acessar objetos específicos dos métodos do get* objeto pai.

Observação

Não adicione ou remova manualmente objetos dessas matrizes de coleção. Use os add métodos nos objetos pai e nos delete métodos nos objetos do tipo de coleção. Por exemplo, adicione uma Tabela a uma planilha com o Worksheet.addTable método e remova o uso de TableTable.delete.

O script a seguir registra o tipo de cada forma na planilha atual.

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

O script a seguir exclui a forma mais antiga da planilha atual.

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

Data

O objeto Date fornece uma maneira padronizada de trabalhar com datas em seu script. Date.now() gera um objeto com a data e hora atuais, o que é útil ao adicionar carimbos de data/hora à entrada de dados do script.

O script a seguir adiciona a data atual à planilha. Observe que, usando o método, o toLocaleDateString Excel reconhece o valor como uma data e altera o formato de número da célula automaticamente.

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

A seção Trabalhar com datas dos exemplos tem mais scripts relacionados à data.

Matemática

O objeto Math fornece métodos e constantes para operações matemáticas comuns. Elas fornecem várias funções também disponíveis no Excel, sem a necessidade de usar o mecanismo de cálculo da pasta de trabalho. Isso salva o script de ter que consultar a pasta de trabalho, o que melhora o desempenho.

O script a seguir usa Math.min para localizar e registrar o menor número no intervalo A1:D4 . Observe que esse exemplo pressupõe que todo o intervalo contém apenas números, não cadeias de caracteres.

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

Não há suporte para o uso de bibliotecas JavaScript externas

Os Scripts do Office não dão suporte ao uso de bibliotecas externas de terceiros. Seu script só pode usar os objetos JavaScript internos e as APIs de Scripts do Office.

Partilhar via