Partilhar via

Utilizar objetos JavaScript incorporados em Scripts do Office

O JavaScript fornece vários objetos incorporados que pode utilizar nos seus Scripts do Office, independentemente de estar a criar scripts em JavaScript ou TypeScript (um superconjunto de JavaScript). Este artigo descreve como utilizar alguns dos objetos JavaScript incorporados nos Scripts do Office para Excel.

Observação

Para obter uma lista completa de todos os objetos JavaScript incorporados, veja o artigo Standard objetos incorporados da Mozilla.

Matriz

O objeto Matriz fornece uma forma padronizada de trabalhar com matrizes no script. Embora as matrizes sejam construções JavaScript padrão, estão relacionadas com scripts do Office de duas formas 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. Estas matrizes contêm informações específicas sobre cada célula nesse intervalo. Por exemplo, Range.getValues devolve todos os valores nessas células (com as linhas e colunas do mapeamento de matriz bidimensional para as linhas e colunas dessa subsecção da folha de cálculo). Range.getFormulas e Range.getNumberFormats são outros métodos utilizados frequentemente que devolvem matrizes como Range.getValues.

O script seguinte procura no intervalo A1:D4 qualquer formato de número que contenha um "$". O script define a cor de preenchimento nessas células como "amarelo".

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 numa coleção. A coleção é gerida pela API de Scripts do Office e exposta como uma matriz. Por exemplo, todas as Formas numa folha de cálculo estão contidas numa Shape[] que é devolvida pelo Worksheet.getShapes método . Pode utilizar esta matriz para ler valores da coleção ou pode aceder a objetos específicos a partir dos métodos do get* objeto principal.

Observação

Não adicione nem remova manualmente objetos destas matrizes de coleção. Utilize os add métodos nos objetos principais e os delete métodos nos objetos do tipo coleção. Por exemplo, adicione uma Tabela a uma Folha de Cálculo com o Worksheet.addTable método e remova o Table com Table.delete.

O script seguinte regista o tipo de todas as formas na folha de cálculo 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 seguinte elimina a forma mais antiga na folha de cálculo 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 Data fornece uma forma padronizada de trabalhar com datas no 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 seguinte adiciona a data atual à folha de cálculo. Tenha em atenção que ao utilizar o toLocaleDateString método , o Excel reconhece o valor como uma data e altera automaticamente o formato de número da célula.

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 secção Trabalhar com datas dos exemplos tem mais scripts relacionados com datas.

Matemática

O objeto Matemática fornece métodos e constantes para operações matemáticas comuns. Estas fornecem muitas funções também disponíveis no Excel, sem a necessidade de utilizar o motor de cálculo do livro. Isto impede que o script tenha de consultar o livro, o que melhora o desempenho.

O script seguinte utiliza Math.min para localizar e registar o menor número no intervalo A1:D4 . Tenha em atenção que este exemplo pressupõe que todo o intervalo contém apenas números e não cadeias.

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

A utilização de bibliotecas JavaScript externas não é suportada

Os Scripts do Office não suportam a utilização de bibliotecas externas de terceiros. O script só pode utilizar os objetos JavaScript incorporados e as APIs de Scripts do Office.

Confira também

  • Last updated on