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

Chame APIs JavaScript do Excel de uma função personalizada quando seu cálculo precisar de dados de pasta de trabalho que não são passados como um parâmetro. Por exemplo, uma função personalizada pode ler propriedades de documentos, valores ou formatos de intervalo, partes XML personalizadas ou o nome da pasta de trabalho.

Mantenha essas chamadas somente leitura. Uma função personalizada que altera outras células ou o ambiente do Excel pode causar baixo desempenho, tempos limite ou loops de cálculo infinitos.

Antes de começar

Seu suplemento deve usar um tempo de execução compartilhado antes que uma função personalizada possa chamar APIs JavaScript do Excel. Crie um projeto de funções personalizadas do Excel com o Kit de Ferramentas de Agentes do Microsoft 365 ou configure um suplemento existente para usar um tempo de execução compartilhado.

Obter um valor da pasta de trabalho

Crie um objeto Excel.RequestContext para acessar a pasta de trabalho. Carregue as propriedades de que a função precisa, chame context.sync()e retorne o resultado.

A função personalizada a seguir usa Worksheet.getRange para ler um valor de célula. O address parâmetro deve ser uma cadeia de caracteres. Por exemplo, insira =CONTOSO.GETRANGEVALUE("A1") em uma célula para retornar o valor da célula A1.

/**
 * @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 sobre quais APIs ele chama. Não chame APIs JavaScript do Excel de uma função personalizada que altera células fora da célula que executa a função personalizada. A alteração de outras células ou do ambiente do Excel pode resultar em baixo desempenho, tempos limite e loops infinitos no aplicativo Excel. Isso significa que suas funções personalizadas não devem fazer o seguinte:

  • Insira, exclua ou formate células na planilha.
  • Alterar o valor de outra célula.
  • Mover, renomear, excluir ou adicionar planilhas a uma pasta de trabalho.
  • Adicionar nomes a uma pasta de trabalho.
  • Definir propriedades.
  • Altere qualquer uma das opções de ambiente do Excel, como o modo de cálculo ou as 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 da faixa de opções ou de um painel de tarefas. Além disso, os cálculos de função personalizada não devem ser executados enquanto um recálculo do Excel está ocorrendo, pois esse cenário cria resultados imprevisíveis.

Próximas etapas

Confira também

  • Last updated on