Compartilhar via

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

Chame as APIs JavaScript do Excel a partir das suas funções personalizadas para obter dados de intervalo e obter mais contexto para os seus cálculos. Chamar APIs JavaScript do Excel através de uma função personalizada pode ser útil quando:

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

Importante

Para chamar as APIs JavaScript do Excel a partir da sua função personalizada, terá de utilizar um runtime partilhado. Utilize o gerador Yeoman para Suplementos do Office para instalar funções personalizadas do Excel através de um projeto de Runtime Partilhado ou consulte Configurar o seu Suplemento do Office para utilizar um runtime partilhado para saber mais.

Exemplo de código

Para chamar as APIs JavaScript do Excel a partir de uma função personalizada, primeiro precisa de um contexto. Utilize o objeto Excel.RequestContext para obter um contexto. Em seguida, utilize o contexto para chamar as APIs de que precisa no livro.

O seguinte exemplo de código mostra como utilizar Excel.RequestContext para obter um valor de uma célula no livro. Neste exemplo, o address parâmetro é transmitido para o método Excel JavaScript API Worksheet.getRange e tem de ser introduzido como uma cadeia. Por exemplo, a função personalizada introduzida na IU do Excel tem de seguir o padrão =CONTOSO.GETRANGEVALUE("A1"), em "A1" que é o endereço da célula a partir da qual obter 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 da chamada de APIs JavaScript do Excel através de uma função personalizada

Um suplemento de funções personalizadas pode chamar APIs JavaScript do Excel, mas deve ter cuidado com as APIs a que chama. Não chame APIs JavaScript do Excel a partir de uma função personalizada que altere as células fora da célula que executa a função personalizada. Alterar outras células ou o ambiente do Excel pode resultar num fraco desempenho, tempos limite e ciclos infinitos na aplicação Excel. Isto significa que as suas funções personalizadas não devem efetuar nenhum dos seguintes procedimentos:

  • Inserir, eliminar ou formatar células na folha de cálculo.
  • Alterar o valor de outra célula.
  • Mover, mudar o nome, eliminar ou adicionar folhas a um livro.
  • Adicionar nomes a um livro.
  • Definir propriedades.
  • Altere qualquer uma das opções de ambiente do Excel, como o modo de cálculo ou as vistas de ecrã.

O 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 realizar operações de escrita noutras células. Em vez disso, faça alterações a outras células ou ao ambiente do Excel a partir do contexto de um botão do friso ou de um painel de tarefas. Além disso, os cálculos de funções personalizadas não devem ser executados enquanto estiver a ocorrer um recálculo do Excel, uma vez que este cenário cria resultados imprevisíveis.

Próximas etapas

Confira também

  • Last updated on