Share via

Chamar APIs JavaScript do Excel de uma função personalizada

  • Artigo

Chame APIs JavaScript do Excel de suas funções personalizadas para obter dados de intervalo e obter mais contexto para seus cálculos. Chamar APIs JavaScript do Excel por meio de uma função personalizada pode ser útil quando:

  • Uma função personalizada precisa obter informações do Excel antes do cálculo. Essas informações podem incluir propriedades de documento, formatos de intervalo, partes XML personalizadas, um nome de pasta de trabalho ou outras informações específicas do Excel.
  • Uma função personalizada definirá o formato de número da célula para os valores retornados após o cálculo.

Importante

Para chamar APIs JavaScript do Excel de sua função personalizada, você precisará usar um runtime compartilhado. Use o gerador Yeoman para suplementos do Office para instalar uma Função Personalizada do Excel usando um projeto de Runtime Compartilhado ou consulte Configurar seu Suplemento do Office para usar um runtime compartilhado para saber mais.

Exemplo de código

Para chamar APIs JavaScript do Excel de uma função personalizada, primeiro você precisa de um contexto. Use o objeto Excel.RequestContext para obter um contexto. Em seguida, use o contexto para chamar as APIs necessárias na pasta de trabalho.

O exemplo de código a seguir mostra como usar Excel.RequestContext para obter um valor de uma célula na pasta de trabalho. Neste exemplo, o address parâmetro é passado para o método Worksheet.getRange da API JavaScript do Excel e deve ser inserido como uma cadeia de caracteres. Por exemplo, a função personalizada inserida na interface do usuário do Excel deve seguir o padrão =CONTOSO.GETRANGEVALUE("A1"), em "A1" que é o endereço da célula da qual recuperar o valor.

/**
 * @customfunction
 * @param {string} address The address of the cell from which to retrieve the value.
 * @returns The value of the cell at the input address.
 **/
async function getRangeValue(address) {
 // Retrieve the context object. 
 const context = new Excel.RequestContext();
 
 // Use the context object to access the cell at the input address. 
 const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
 range.load("values");
 await context.sync();
 
 // Return the value of the cell at the input address.
 return range.values[0][0];
}

Limitações de chamar APIs JavaScript do Excel por meio de uma função personalizada

Um suplemento de funções personalizadas pode chamar APIs JavaScript do Excel, mas você deve ter cuidado com quais APIs ela chama. Não chame APIs JavaScript do Excel de uma função personalizada que altere células fora da célula que executa a função personalizada. A alteração de outras células ou o ambiente do Excel pode resultar em desempenho ruim, tempo limite e loops infinitos no aplicativo Excel. Isso significa que suas funções personalizadas não devem fazer nenhum dos seguintes procedimentos:

  • Inserir, excluir ou formatar células na planilha.
  • Altere o valor de outra célula.
  • Mover, renomear, excluir ou adicionar planilhas a uma pasta de trabalho.
  • Adicione nomes a uma pasta de trabalho.
  • Defina propriedades.
  • Altere qualquer uma das opções de ambiente do Excel, como modo de cálculo ou exibições de tela.

Seu suplemento de funções personalizadas pode ler informações de células fora da célula que executa a função personalizada, mas não deve executar operações de gravação em outras células. Em vez disso, faça alterações em outras células ou no ambiente do Excel a partir do contexto de um botão de faixa de opções ou de um painel de tarefas. Além disso, os cálculos de função personalizados não devem ser executados enquanto uma recalculação do Excel está ocorrendo, pois esse cenário cria resultados imprevisíveis.

Próximas etapas

Confira também