Funções personalizadas síncronas (versão prévia)

Observação

As funções personalizadas síncronas estão disponíveis em visualização pública e estão sujeitas a alterações com base nos comentários. Não use funções personalizadas síncronas em um suplemento de produção.

Para usar esse recurso, você deve usar a versão de visualização da biblioteca da API JavaScript do Office da CDN (Rede de Distribuição de Conteúdo) doOffice.js. O arquivo de definição de tipo da compilação TypeScript e IntelliSense pode ser encontrado na CDN e DefinitelyTyped. Você pode instalar esses tipos com npm install --save-dev @types/office-js-preview.

As funções personalizadas síncronas permitem que os processos de avaliação e formato condicional sejam executados no Excel simultaneamente com a função personalizada. Habilite o suporte síncrono quando sua função personalizada precisar ser executada em conjunto com qualquer um dos processos do Excel listados neste artigo. As funções personalizadas que não dão suporte a operações síncronas retornam um erro como #CALC! ou #VALUE! quando são executadas ao mesmo tempo que esses processos do Excel.

Aviso

As funções personalizadas síncronas não dão suporte a operações de gravação com APIs JavaScript do Office, como usar Range.values para definir um valor de célula. Chamar uma operação de gravação em uma função personalizada síncrona pode fazer com que o Excel congele.

Processos do Excel com suporte de funções personalizadas síncronas

As ações e os processos a seguir funcionam com funções personalizadas síncronas.

Ações de avaliação com suporte

  • Selecionando fórmulas e, em seguida, avaliando fórmula no Excel.
  • Selecionando fórmulas e, em seguida, inserindo função no Excel.
  • No modo de edição de célula, selecionar parte de uma fórmula e usar F9 para ver os resultados parciais do cálculo.
  • O Application.Calculate método no VBA.

Ações de formato condicional com suporte

A lista a seguir se aplica a ações de formatação condicional disparadas pela interface do usuário do Excel e pelas APIs JavaScript do Office.

  • Criar uma nova regra.
  • Editar regras.
  • Exclua regras.
  • Reordenar regras.
  • Altere o intervalo "Aplica-se a".
  • Ative ou desative "Parar se for verdadeiro".
  • Limpar todas as regras.
  • Recortar e colar células que contêm formatação condicional.
  • Copie e cole células que contêm formatação condicional.

Observação

Quando uma função personalizada síncrona leva um tempo significativo para ser concluída, o Excel pode bloquear temporariamente a interface do usuário enquanto aguarda o resultado. Para evitar interrupções prolongadas, o usuário pode cancelar a execução da função a qualquer momento usando a tecla Esc ou selecionando em qualquer lugar fora da célula ou diálogo.

Habilitar o suporte síncrono no suplemento

Para dar suporte a cenários síncronos em seu suplemento, siga as etapas a seguir.

Importante

As funções personalizadas síncronas não podem ser funções de streaming ou voláteis . Se você usar a @supportSync marca com @volatile marcas ou @streaming , o Excel ignorará o suporte síncrono. O suporte volátil ou de streaming tem precedência.

Exemplo de código

O exemplo de código a seguir mostra como criar uma função personalizada síncrona.

/** 
 * A synchronous custom function that takes a cell address and returns the value of that cell.
 * @customfunction
 * @supportSync
 * @param {string} address The address of the cell from which to retrieve the value.
 * @param {CustomFunctions.Invocation} invocation Invocation object.
 * @returns The value of the cell at the input address.
 */ 
export async function getCellValue(address, invocation) {
  const context = new Excel.RequestContext();
  context.setInvocation(invocation); // The `invocation` object must be passed in the `setInvocation` method for synchronous functions.

  const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
  range.load("values");

  await context.sync(); 
  return range.values[0][0];
}

Dica

Para explorar funções personalizadas síncronas em um suplemento completo, consulte Criar funções personalizadas síncronas no Excel (versão prévia) em nosso repositório de exemplos de código de suplementos do Office.

Confira também

  • Last updated on