Obter precedentes e dependentes de fórmula usando a API JavaScript do Excel

  • Artigo

As fórmulas do Excel geralmente contêm referências a outras células na mesma planilha ou pasta de trabalho. Essas referências entre células são conhecidas como "precedentes" e "dependentes". Um precedente é uma célula que fornece dados para uma fórmula. Um dependente é uma célula que contém uma fórmula que se refere a outras células. Para saber mais sobre recursos na interface do usuário do Excel relacionados a precedentes e dependentes, como Rastrear Precedentes e Dependentes de Rastreamento, consulte Exibir as relações entre fórmulas e células.

Uma célula precedente pode ter suas próprias células precedentes. Cada célula precedente nesta cadeia de precedentes ainda é um precedente da célula original. A mesma relação existe para dependentes. Qualquer célula afetada por outra célula é dependente dessa célula. Um "precedente direto" é o primeiro grupo anterior de células nessa sequência, semelhante ao conceito de pais em uma relação pai-filho. Um "dependente direto" é o primeiro grupo dependente de células em uma sequência, semelhante às crianças em uma relação pai-filho.

Este artigo fornece exemplos de código que recuperam os precedentes e dependentes de fórmulas usando a API JavaScript do Excel. Para obter a lista completa de propriedades e métodos compatíveis com o Range objeto, consulte Objeto range (API JavaScript para Excel).

Obter os precedentes de uma fórmula

Localize as células precedentes de uma fórmula com Range.getPrecedents. Range.getPrecedents retorna um WorkbookRangeAreas objeto. Este objeto contém os endereços de todos os precedentes na pasta de trabalho. Ele tem um objeto separado RangeAreas para cada planilha que contém pelo menos um precedente de fórmula. Para saber mais sobre o RangeAreas objeto, confira Trabalhar com vários intervalos simultaneamente em suplementos do Excel.

Para localizar apenas as células precedentes diretas de uma fórmula, use Range.getDirectPrecedents. Range.getDirectPrecedents funciona como Range.getPrecedents e retorna um WorkbookRangeAreas objeto que contém os endereços de precedentes diretos.

A captura de tela a seguir mostra o resultado da seleção do botão Rastrear Precedentes na interface do usuário do Excel. Este botão desenha uma seta das células precedentes para a célula selecionada. A célula selecionada, E3, contém a fórmula "=C3 * D3", portanto, C3 e D3 são células precedentes. Ao contrário do botão interface do usuário do Excel, os getPrecedents métodos e getDirectPrecedents não desenham setas.

Seta rastreando células precedentes na interface do usuário do Excel.

Importante

Os getPrecedents métodos e getDirectPrecedents não recuperam células precedentes entre pastas de trabalho.

O exemplo de código a seguir mostra como trabalhar com os Range.getPrecedents métodos e Range.getDirectPrecedents . O exemplo obtém os precedentes para o intervalo ativo e, em seguida, altera a cor de fundo dessas células precedentes. A cor de fundo das células precedentes diretas é definida como amarela e a cor de fundo das outras células precedentes é definida como laranja.

// This code sample shows how to find and highlight the precedents 
// and direct precedents of the currently selected cell.
await Excel.run(async (context) => {
  let range = context.workbook.getActiveCell();
  // Precedents are all cells that provide data to the selected formula.
  let precedents = range.getPrecedents();
  // Direct precedents are the parent cells, or the first preceding group of cells that provide data to the selected formula.    
  let directPrecedents = range.getDirectPrecedents();

  range.load("address");
  precedents.areas.load("address");
  directPrecedents.areas.load("address");
  
  await context.sync();

  console.log(`All precedent cells of ${range.address}:`);
  
  // Use the precedents API to loop through all precedents of the active cell.
  for (let i = 0; i < precedents.areas.items.length; i++) {
    // Highlight and print out the address of all precedent cells.
    precedents.areas.items[i].format.fill.color = "Orange";
    console.log(`  ${precedents.areas.items[i].address}`);
  }

  console.log(`Direct precedent cells of ${range.address}:`);

  // Use the direct precedents API to loop through direct precedents of the active cell.
  for (let i = 0; i < directPrecedents.areas.items.length; i++) {
    // Highlight and print out the address of each direct precedent cell.
    directPrecedents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directPrecedents.areas.items[i].address}`);
  }
});

Obter os dependentes de uma fórmula

Localize as células dependentes de uma fórmula com Range.getDependents. Assim como Range.getPrecedents, Range.getDependents também retorna um WorkbookRangeAreas objeto. Esse objeto contém os endereços de todos os dependentes na pasta de trabalho. Ele tem um objeto separado RangeAreas para cada planilha que contém pelo menos uma fórmula dependente. Para obter mais informações sobre como trabalhar com o RangeAreas objeto, consulte Trabalhar com vários intervalos simultaneamente em suplementos do Excel.

Para localizar apenas as células dependentes diretas de uma fórmula, use Range.getDirectDependents. Range.getDirectDependents funciona como Range.getDependents e retorna um WorkbookRangeAreas objeto que contém os endereços de dependentes diretos.

A captura de tela a seguir mostra o resultado da seleção do botão Rastrear Dependentes na interface do usuário do Excel. Este botão desenha uma seta da célula selecionada para células dependentes. A célula selecionada, D3, tem a célula E3 como dependente. O E3 contém a fórmula "=C3 * D3". Ao contrário do botão interface do usuário do Excel, os getDependents métodos e getDirectDependents não desenham setas.

Seta rastreando células dependentes na interface do usuário do Excel.

Importante

Os getDependents métodos e getDirectDependents não recuperam células dependentes entre pastas de trabalho.

O exemplo de código a seguir mostra como trabalhar com os Range.getDependents métodos e Range.getDirectDependents . O exemplo obtém os dependentes para o intervalo ativo e, em seguida, altera a cor de fundo dessas células dependentes. A cor de fundo das células dependentes diretas é definida como amarela e a cor de fundo das outras células dependentes é definida como laranja.

// This code sample shows how to find and highlight the dependents 
// and direct dependents of the currently selected cell.
await Excel.run(async (context) => {
    let range = context.workbook.getActiveCell();
    // Dependents are all cells that contain formulas that refer to other cells.
    let dependents = range.getDependents();  
    // Direct dependents are the child cells, or the first succeeding group of cells in a sequence of cells that refer to other cells.
    let directDependents = range.getDirectDependents();

    range.load("address");
    dependents.areas.load("address");    
    directDependents.areas.load("address");
    
    await context.sync();

    console.log(`All dependent cells of ${range.address}:`);
    
    // Use the dependents API to loop through all dependents of the active cell.
    for (let i = 0; i < dependents.areas.items.length; i++) {
      // Highlight and print out the addresses of all dependent cells.
      dependents.areas.items[i].format.fill.color = "Orange";
      console.log(`  ${dependents.areas.items[i].address}`);
    }

    console.log(`Direct dependent cells of ${range.address}:`);

    // Use the direct dependents API to loop through direct dependents of the active cell.
    for (let i = 0; i < directDependents.areas.items.length; i++) {
      // Highlight and print the address of each dependent cell.
      directDependents.areas.items[i].format.fill.color = "Yellow";
      console.log(`  ${directDependents.areas.items[i].address}`);
    }
});

Confira também