Trabalhar simultaneamente com vários intervalos em suplementos do Excel

Você pode aplicar operações ou definir propriedades em vários intervalos ao mesmo tempo, mesmo que eles não sejam contíguos. Isso torna o código mais curto e eficiente quando comparado ao acesso a cada intervalo separadamente.

Principais pontos

• Use RangeAreas para ler ou definir a mesma coisa em vários intervalos separados em uma chamada.
• Uma propriedade é null a menos que todos os intervalos de membros compartilhem o mesmo valor.
• Defina uma propriedade uma vez no RangeAreas objeto em vez de fazer um loop, a menos que cada intervalo precise de uma lógica diferente.
• Evite objetos grandes RangeAreas feitos de muitas células únicas. Restringir primeiro com getSpecialCells ou outros filtros.
• Tenha cuidado com colunas ou linhas inteiras. Para obter mais detalhes, consulte Leitura ou gravação em um intervalo não associado.

RangeAreas

Um objeto RangeAreas representa um conjunto de intervalos que podem não se tocar. Ele compartilha muitos membros com Range, com algumas diferenças em como os valores são retornados.

Exemplos:

• address Retorna uma cadeia de caracteres delimitada por vírgula de todos os endereços.
• dataValidation Retorna um único objeto somente se cada intervalo tiver a mesma regra, caso contrário, retorna null.
• cellCount é o total de células em todos os intervalos.
• calculate Recalcula todas as células no conjunto.
• getEntireColumn e getEntireRow retorne uma nova RangeAreas abrangência de colunas ou linhas completas para cada membro.
• copyFrom Aceita A Range ou A RangeAreas como fonte.

Lista completa de membros do intervalo que também estão disponíveis em RangeAreas

Propriedades

Familiarize-se com as Propriedades de leitura do RangeAreas antes de escrever o código que lê as propriedades listadas. Existem sutilezas para o que é retornado.

• address
• addressLocal
• cellCount
• conditionalFormats
• context
• dataValidation
• format
• isEntireColumn
• isEntireRow
• style
• worksheet

Métodos

• calculate()
• clear()
• convertDataTypeToText()
• convertToLinkedDataType()
• copyFrom()
• getEntireColumn()
• getEntireRow()
• getIntersection()
• getIntersectionOrNullObject()
• getOffsetRange() (nomeado getOffsetRangeAreas no RangeAreas objeto)
• getSpecialCells()
• getSpecialCellsOrNullObject()
• getTables()
• getUsedRange() (nomeado getUsedRangeAreas no RangeAreas objeto)
• getUsedRangeOrNullObject() (nomeado getUsedRangeAreasOrNullObject no RangeAreas objeto)
• load()
• set()
• setDirty()
• toJSON()
• track()
• untrack()

Métodos e propriedades específicos do RangeArea

O tipo RangeAreas tem alguns métodos e propriedades que não estão no objeto Range. A seguir está uma seleção deles.

• areas: O objeto RangeCollection que contém todos os intervalos representados pelo objeto RangeAreas. O objeto RangeCollection também é novidade e é semelhante a outros objetos do conjunto do Excel. É uma propriedade items que é uma matriz de objetos Range que representam os intervalos.
• areaCount: O número total de intervalos em RangeAreas.
• getOffsetRangeAreas: Funciona como Range.getOffsetRange, exceto pelo fato de que o RangeAreas é retornado e contém os intervalos que são todos os deslocamentos de um dos intervalos do RangeAreas original.

Criar RangeAreas

Você pode criar um RangeAreas objeto de várias maneiras. A lista a seguir inclui alguns exemplos.

• Ligue Worksheet.getRanges() e encaminhe-o em uma cadeia de caracteres com endereços de intervalo separado por vírgula. Se algum intervalo que você deseja incluir tiver sido feito em um NamedItem, você poderá incluir o nome, em vez do endereço, cadeia de caracteres.
• Chame Range.getSpecialCells() e retorne um RangeAreas objeto com células de um tipo específico, como células que contêm fórmulas, validação de dados ou formatação condicional.
• Chamar Workbook.getSelectedRanges(). Esse método retornará um RangeAreas representando todos os intervalos selecionados na planilha ativa no momento.

Quando você tiver um objeto RangeAreas, você pode criar outros usando os métodos de objeto que retornam RangeAreas como getOffsetRangeAreas e getIntersection.

Definir as propriedades em vários intervalos

Definir uma propriedade em um RangeAreas objeto define a propriedade correspondente em todos os intervalos no conjunto RangeAreas.areas.

A seguir, um exemplo de configuração de uma propriedade em vários intervalos. A função realça os intervalos F3:F5 e H3:H5.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let rangeAreas = sheet.getRanges("F3:F5, H3:H5");
    rangeAreas.format.fill.color = "pink";

    await context.sync();
});

Este exemplo se aplica a cenários nos quais você pode codificar os endereços de intervalo para os quais você passa para getRanges ou facilmente calculá-los no tempo de execução. Alguns dos cenários em que isso pode ser verdadeiro incluem:

• O código é executado no contexto de um modelo conhecido.
• O código é executado no contexto de dados importados, em que o esquema dos dados é conhecido.

Combinar RangeAreas com getSpecialCells

Filtre RangeAreas apenas as células que correspondem a um critério, como fórmulas, antes de aplicar formatação ou validação.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // Two discontiguous vertical bands.
    const targets = sheet.getRanges("A1:A100, C1:C100");

    // Narrow to only the formula cells within those bands.
    const formulaCells = targets.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaCells.format.fill.color = "lightYellow";
    await context.sync();
});

Obter células especiais de vários intervalos

As getSpecialCells e getSpecialCellsOrNullObject métodos no RangeAreas objeto funciona analogamente para métodos de mesmo nome no Range objeto. Esses métodos retornam as células com característica especificada de todos os intervalos no RangeAreas.areas conjunto. Para obter mais detalhes sobre células especiais, consulte Localizar células especiais em um intervalo.

Ao chamar as getSpecialCells ou getSpecialCellsOrNullObject método em um RangeAreas objeto:

• Se você passar Excel.SpecialCellType.sameConditionalFormat como o primeiro parâmetro, o método retorna todas as células com a mesma formatação condicional que a célula superior esquerda do primeiro intervalo no RangeAreas.areas conjunto.
• Se você passar Excel.SpecialCellType.sameDataValidation como o primeiro parâmetro, o método retorna todas as células com a regra de validação de dados que a célula superior esquerda do primeiro intervalo no RangeAreas.areas conjunto.

Ler propriedades de RangeAreas

A leitura de valores de propriedade RangeAreas requer cuidados, porque uma determinada propriedade pode ter valores diferentes para intervalos diferentes dentro deRangeAreas. A regra geral é que, se um valor consistente puder ser retornado, ele será retornado. Por exemplo, no código a seguir, o código RGB para rosa (#FFC0CB) e true será registrado no console porque ambos os RangeAreas intervalos no objeto têm um preenchimento rosa e ambos são colunas inteiras.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();

    // The ranges are the F column and the H column.
    let rangeAreas = sheet.getRanges("F:F, H:H");  
    rangeAreas.format.fill.color = "pink";

    rangeAreas.load("format/fill/color, isEntireColumn");
    await context.sync();

    console.log(rangeAreas.format.fill.color); // #FFC0CB
    console.log(rangeAreas.isEntireColumn); // true
});

Como os valores das propriedades podem ser diferentes, lembre-se destas regras simples.

• As propriedades booleanas são true apenas se forem verdadeiras em todos os intervalos, caso contrário, serão false.
• address Sempre retorna a cadeia de caracteres endereços delimitados por vírgulas.
• Outras propriedades são null , a menos que todos os intervalos compartilhem o mesmo valor.

Por exemplo, o código a seguir cria um RangeAreas no qual apenas um intervalo é uma coluna inteira e apenas um é preenchido com rosa. O console mostrará null para a cor de preenchimento false para a propriedade isEntireRow e "Planilha1! F3:F5, Planilha1! H:H"(supondo que o nome da planilha seja "Planilha1") para a propriedadeaddress.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let rangeAreas = sheet.getRanges("F3:F5, H:H");

    let pinkColumnRange = sheet.getRange("H:H");
    pinkColumnRange.format.fill.color = "pink";

    rangeAreas.load("format/fill/color, isEntireColumn, address");
    await context.sync();

    console.log(rangeAreas.format.fill.color); // null
    console.log(rangeAreas.isEntireColumn); // false
    console.log(rangeAreas.address); // "Sheet1!F3:F5, Sheet1!H:H"
});

Confira também

• Referência da API JavaScript do Excel
• Ler ou gravar em um intervalo grande usando a API JavaScript do Excel
• Leia ou grave em um intervalo não associado usando a API JavaScript do Excel