Trabalhar simultaneamente com vários intervalos em suplementos do Excel

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

Principais pontos

Utilize RangeAreas para ler ou definir o mesmo conteúdo em vários intervalos separados numa chamada.
Uma propriedade é null a menos que todos os intervalos de membros partilhem o mesmo valor.
Defina uma propriedade uma vez no RangeAreas objeto em vez de repetir, a menos que cada intervalo precise de lógica diferente.
Evite objetos grandes RangeAreas feitos de muitas células individuais. Reduza primeiro com getSpecialCells ou outros filtros.
Tenha cuidado com colunas ou linhas inteiras. Para obter mais detalhes, consulte Ler ou escrever num intervalo não vinculado.

RangeAreas

Um objeto RangeAreas representa um conjunto de intervalos que podem não tocar. Partilha muitos membros com Range, com algumas diferenças na forma como os valores são devolvidos.

Exemplos:

address devolve uma cadeia delimitada por vírgulas de todos os endereços.
dataValidation devolve um único objeto apenas se cada intervalo tiver a mesma regra, caso contrário, devolve null.
cellCount é o total de células em todos os intervalos.
calculate recalcula todas as células no conjunto.
getEntireColumn e getEntireRow devolvem uma nova RangeAreas expansão de colunas ou linhas completas para cada membro.
copyFrom aceita um Range ou um RangeAreas como a origem.

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() (com o nome getOffsetRangeAreas no RangeAreas objeto)
getSpecialCells()
getSpecialCellsOrNullObject()
getTables()
getUsedRange() (com o nome getUsedRangeAreas no RangeAreas objeto)
getUsedRangeOrNullObject() (com o nome 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. Segue-se uma seleção das mesmas.

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

Pode criar um RangeAreas objeto de várias formas. A lista seguinte 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 devolva um RangeAreas objeto com células de um tipo específico, como células que contenham 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.

Observação

É possível adicionar diretamente intervalos adicionais para um objeto RangeAreas. Por exemplo, o conjunto RangeAreas.areas não tem um métodoadd.

Aviso

Não tente adicionar ou eliminar diretamente membros da RangeAreas.areas.items matriz. Isso levará a um comportamento indesejável no seu código. Por exemplo, é possível enviar um objeto adicional Range para a matriz, mas isso causará erros porque as propriedades e métodos RangeAreas se comportam como se o novo item não estivesse ali. Por exemplo, a propriedade areaCount não inclui intervalos transferidos dessa maneira e o RangeAreas.getItemAt(index) gera um erro se index for maior que areasCount-1. Da mesma forma, excluir um objeto Range na matriz RangeAreas.areas.items obtendo uma referência a ele e chamando seu método Range.delete causa bugs: embora o Rangeobjeto seja excluído, as propriedades e métodos do objeto pai RangeAreas se comportam ou tentam se comportar, como se ele ainda existisse. Por exemplo, se o seu código chamar RangeAreas.calculate, o Office tentará calcular o intervalo, mas haverá erro porque o objeto de intervalo desapareceu.

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 para RangeAreas baixo apenas para 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 dentro de 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 seguinte, o código RGB para cor-de-rosa (#FFC0CB) e true será registado na consola porque ambos os intervalos no RangeAreas objeto têm um preenchimento cor-de-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
});

Uma vez que os valores de propriedade podem ser diferentes, tenha estas regras simples em mente.

As propriedades true booleanas são apenas se forem verdadeiras em todos os intervalos, caso contrário, são false.
address devolve sempre a cadeia de endereços delimitados por vírgulas.
Outras propriedades são, null a menos que todos os intervalos partilhem 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

Comentários

Esta página foi útil?

Last updated on 2025-10-02