Localizar células especiais dentro de um intervalo com a API JavaScript do Excel

  • Artigo

Este artigo fornece exemplos de código que encontram células especiais dentro de um intervalo 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).

Localizar intervalos com células especiais

Os métodos Range.getSpecialCells e Range.getSpecialCellsOrNullObject encontram intervalos com base nas características das respetivas células e nos tipos de valores das respetivas células. Os dois métodos retornam RangeAreas objetos. Aqui estão as assinaturas dos métodos do arquivo de tipos de dados TypeScript:

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

O seguinte exemplo de código utiliza o getSpecialCells método para localizar todas as células com fórmulas. Sobre este código, observe:

  • Ele limita a parte da planilha que precisa ser pesquisada chamando primeiro Worksheet.getUsedRange e chamando getSpecialCells para apenas esse intervalo.
  • O método getSpecialCells retorna um objeto RangeAreas, então todas as células com fórmulas serão coloridas de rosa, mesmo que não sejam todas contíguas.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaRanges = usedRange.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaRanges.format.fill.color = "pink";

    await context.sync();
});

Se nenhuma célula com característica destino existe no intervalo, getSpecialCells exibe um erro ItemNotFound. Isso desvia o fluxo de controle para um catch bloco, se houver um. Se não existir um catch bloco, o erro para o método .

Se você espera que células com característica direcionada sempre deveriam existir, provavelmente desejará o código para gerar um erro se as células não estiverem lá. Se for um cenário válido que não há uma ou mais células correspondentes, o código deve verificar se há essa possibilidade e tratar normalmente sem enviar um erro. Você pode obter esse comportamento com o getSpecialCellsOrNullObject método e sua propriedade retornada isNullObject. O seguinte exemplo de código utiliza este padrão. Sobre este código, observe:

  • O getSpecialCellsOrNullObject método devolve sempre um objeto proxy, pelo que nunca null está no sentido javaScript comum. Mas se nenhuma célula de correspondência for encontrada, as propriedades do objetoisNullObject serão definida como true.
  • context.sync Chama antes de testar a isNullObject propriedade. Esse é um requisito com todos os métodos e propriedades *OrNullObject, pois sempre terá que carregar e sincronizar as propriedades na ordem para lê-la. No entanto, não é necessário carregar explicitamente a isNullObject propriedade. É carregado automaticamente pelo context.sync mesmo se load não for chamado no objeto. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).
  • Você pode testar esse código selecionando primeiro um intervalo sem células de fórmula e executando-o. Selecione um intervalo que tem pelo menos uma célula com uma fórmula e execute novamente.
await Excel.run(async (context) => {
    let range = context.workbook.getSelectedRange();
    let formulaRanges = range.getSpecialCellsOrNullObject(Excel.SpecialCellType.formulas);
    await context.sync();
        
    if (formulaRanges.isNullObject) {
        console.log("No cells have formulas");
    }
    else {
        formulaRanges.format.fill.color = "pink";
    }
    
    await context.sync();
});

Para simplificar, todos os outros exemplos de código neste artigo utilizam o getSpecialCells método em vez de getSpecialCellsOrNullObject.

Restrinja as células de destino com tipos de valor de célula

As Range.getSpecialCells() e Range.getSpecialCellsOrNullObject() métodos aceitam um segundo parâmetro opcional usado para restringir ainda mais as células de destino. Este segundo parâmetro é uma Excel.SpecialCellValueType você usar para especificar que você quer apenas células que contêm determinados tipos de valores.

Observação

O Excel.SpecialCellValueType parâmetro só pode ser usado se a Excel.SpecialCellType está Excel.SpecialCellType.formulas ou Excel.SpecialCellType.constants.

Teste para um tipo de valor da célula única

O Excel.SpecialCellValueType enumeração com esses quatro tipos básicos (além dos outros valores combinados descritos nesta seção posterior):

  • Excel.SpecialCellValueType.errors
  • Excel.SpecialCellValueType.logical (ou seja, booliano)
  • Excel.SpecialCellValueType.numbers
  • Excel.SpecialCellValueType.text

O seguinte exemplo de código localiza células especiais que são constantes numéricas e colorem essas células cor-de-rosa. Sobre este código, observe:

  • Só realça as células que têm um valor de número literal. Não realça as células que têm uma fórmula (mesmo que o resultado seja um número) ou uma célula booleana, texto ou estado do erro.
  • Para testar o código, certifique-se de que a planilha tenha algumas células com valores numéricos literais, algumas com outros tipos de valores literais e algumas com fórmulas.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let constantNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.constants,
        Excel.SpecialCellValueType.numbers);
    constantNumberRanges.format.fill.color = "pink";

    await context.sync();
});

Teste para vários tipos de valores de célula

Às vezes, você precisa operar com mais de um tipo de valor de célula, como todas as células com valor de texto e com valor booliano ("Lógico"). (Excel.SpecialCellValueType.logical). O Excel.SpecialCellValueType enumeração tem valores com tipos combinado. Por exemplo, Excel.SpecialCellValueType.logicalText segmentará todas as células boolianas e todos os valores de texto. Excel.SpecialCellValueType.all é o valor padrão, que não limita os tipos de valor da célula retornados. O seguinte código de exemplo colore todas as células com fórmulas que produzem um valor numérico ou booleano.

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaLogicalNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.formulas,
        Excel.SpecialCellValueType.logicalNumbers);
    formulaLogicalNumberRanges.format.fill.color = "pink";

    await context.sync();
});

Confira também