Cortar, copiar e colar intervalos com a API JavaScript do Excel

  • Artigo

Este artigo fornece exemplos de código que cortam, copiam e colam intervalos com a API JavaScript do Excel. Para obter a lista completa de propriedades e métodos suportados pelo Range objeto, consulte Excel.Range class (Classe Excel.Range).

Observação

A API JavaScript do Excel não tem um objeto ou classe "Célula". Em vez disso, a API JavaScript do Excel define todas as células do Excel como objetos Range. Uma célula individual na interface do usuário do Excel se traduz em um objeto Range com uma célula na API JavaScript do Excel. Um único objeto Range também pode conter várias células contíguas. Confira Trabalhar com células usando a API JavaScript do Excel para saber mais.

Dica

Para experimentar as APIs cortar, copiar e colar deste artigo num exemplo completo, abra o Laboratório de Scripts no Excel e selecione Copiar e colar intervalos na nossa biblioteca de Exemplos .

Copy and paste

O método Range.copyFrom replica as ações Copiar e Colar da IU do Excel. O destino é o Range objeto que copyFrom é chamado. A fonte a ser copiada é passada como um intervalo ou um endereço de cadeia de caracteres que representa um intervalo.

O exemplo a seguir copia dados de A1:E1 para o intervalo que começa em G1 (que acaba sendo colado em G1:K1).

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    // Copy everything from "A1:E1" into "G1" and the cells afterwards ("G1:K1").
    sheet.getRange("G1").copyFrom("A1:E1");
    await context.sync();
});

Range.copyFrom tem três parâmetros opcionais.

copyFrom(sourceRange: Range | RangeAreas | string, copyType?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;

copyType especifica quais dados são copiados da origem para o destino.

  • Excel.RangeCopyType.formulas transfere as fórmulas nas células de origem e preserva o posicionamento relativo dos intervalos dessas fórmulas. As entradas que não sejam uma fórmula são copiadas no seu estado original.
  • Excel.RangeCopyType.values copia os valores dos dados e, no caso de fórmulas, o resultado da fórmula.
  • Excel.RangeCopyType.formats copia a formatação do intervalo incluindo a fonte, cor e outras configurações de formato, mas nenhum valor.
  • Excel.RangeCopyType.all (a opção predefinida) copia dados e formatação, preservando as fórmulas das células, se forem encontradas.

skipBlanks define se as células em branco são copiadas para o destino. Quando for verdadeiro, copyFrom ignora células em branco no intervalo de origem. As células ignoradas não substituem os dados existentes de suas células correspondentes no intervalo de destino. O padrão é false.

transpose determina se os dados são transpostos, ou seja, suas linhas e colunas são alternadas para o local de origem. Um intervalo transposto invertido na diagonal principal, portanto as linhas 1, 2 e 3 se tornarão as colunas A, B e C.

O exemplo de código e as imagens a seguir demonstram esse comportamento em um cenário simples.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    // Copy a range, omitting the blank cells so existing data is not overwritten in those cells.
    sheet.getRange("D1").copyFrom("A1:C1",
        Excel.RangeCopyType.all,
        true, // skipBlanks
        false); // transpose
    // Copy a range, including the blank cells which will overwrite existing data in the target cells.
    sheet.getRange("D2").copyFrom("A2:C2",
        Excel.RangeCopyType.all,
        false, // skipBlanks
        false); // transpose
    await context.sync();
});

Dados antes de o intervalo ser copiado e colado

Dados no Excel antes da execução do método de cópia do intervalo.

Os dados após o intervalo são copiados e colados

Dados no Excel após a execução do método de cópia do intervalo.

Cortar e colar (mover) células

O método Range.moveTo move as células para uma nova localização no livro. Este comportamento de movimento de células funciona da mesma forma que quando as células são movidas ao arrastar o limite do intervalo ou ao efetuar as ações Cortar e Colar . Tanto a formatação como os valores do intervalo são movidos para a localização especificada como o destinationRange parâmetro .

O seguinte exemplo de código move um intervalo com o Range.moveTo método . Tenha em atenção que, se o intervalo de destino for inferior à origem, será expandido para abranger o conteúdo de origem.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.getRange("F1").values = [["Moved Range"]];

    // Move the cells "A1:E1" to "G1" (which fills the range "G1:K1").
    sheet.getRange("A1:E1").moveTo("G1");
    await context.sync();
});

Confira também