Avaliação contextual de fórmulas - Referência de desenvolvedor HotXLS

Planilhas XLS clássicas e XLSX expõem a mesma API somente leitura para avaliar texto de fórmula como se ele tivesse sido inserido em uma linha e coluna escolhidas com base um

Avaliação única

function EvaluateFormulaAt(Row, Col: Integer;
  const Formula: WideString): TXLSFormulaEvaluationResult; overload;

function EvaluateFormulaAt(Row, Col: Integer;
  const Formula: WideString;
  ReferenceStyle: TXLSFormulaReferenceStyle;
  const Options: TXLSFormulaEvaluationOptions): TXLSFormulaEvaluationResult; overload;

A planilha fornece o contexto de nomes locais, referências não qualificadas, tabelas e vínculos externos sem alterar a planilha ativa, a seleção, o modelo de células, o cache de fórmulas, o estado de pendência nem o grafo de dependências

xlfrsA1 preserva referências absolutas e mistas enquanto resolve referências relativas a partir da célula de destino; xlfrsR1C1 resolve deslocamentos relativos diretamente desse destino

CELL sem uma referência explícita inspeciona a célula de destino informada; use $A$1 para inspecionar a primeira célula fixa a partir de qualquer destino, enquanto A1 resolve relativamente a esse destino sob o contrato de contexto A1

Os metadados CELL apoiados no modelo e o INFO("recalc") também funcionam por meio de views de pasta de trabalho somente leitura sem alterar sua geração ou os caches de fórmulas armazenados; CELL("width",reference) retém seu array de uma linha e duas colunas, e formatos personalizados não classificados retornam xlfeUnsupportedFunction em vez de um código de formato fabricado; veja metadados CELL e INFO para os limites completos de headless e de localidade

Resultados tipados

FORMULATEXT inspeciona metadados de fórmulas armazenados por meio de ambos os motores de planilha e de views somente leitura sem calcular o alvo inspecionado; GETPIVOTDATA avalia um snapshot destacado do cache existente de uma tabela dinâmica local e respeita os orçamentos de avaliação e o cancelamento; agregados visíveis ausentes permanecem valores tipados #REF!, enquanto modelos de tabela dinâmica incompletos ou sem suporte retornam xlfeUnsupportedFunction; veja inspeção de texto de fórmulas e dados visíveis de tabela dinâmica para os limites de armazenamento, array e cache

TXLSFormulaEvaluationResult retorna Status, o Valuetipado original, IsVolatilee um registro Issue estável contendo status, código nativo e mensagem

TXLSFormulaEvaluationStatus = (xlfeOk, xlfeInvalidArgument,
  xlfeWorksheetUnavailable, xlfeParseError, xlfeUnsupportedFunction,
  xlfeCircularReference, xlfeExternalReferenceDenied, xlfeCancelled,
  xlfeResourceLimit, xlfeFailed, xlfeUnsafeFunctionDenied);

TXLSFormulaEvaluationIssue = record
  Status: TXLSFormulaEvaluationStatus;
  NativeCode: Integer;
  Message: WideString;
end;

Valores de fórmula como #DIV/0!, #REF!, cadeias vazias, matrizes, valores Boolean e datas permanecem valores distinguíveis; falhas de análise, funções não suportadas, referências circulares, referências externas negadas, retornos de chamada inseguros negados, cancelamento, argumentos inválidos, planilhas indisponíveis e esgotamento de recursos usam status explícitos da API Issue.NativeCode carrega o código de erro do motor subjacente e Issue.Message the human-readable description when Status is not xlfeOk

Modelos imutáveis reutilizáveis

function CreateFormulaEvaluationTemplate(Row, Col: Integer;
  const Formula: WideString;
  ReferenceStyle: TXLSFormulaReferenceStyle): IXLSFormulaEvaluationTemplate;

Um modelo compila a fórmula uma vez em sua âncora e expõe EvaluateAt e EvaluateAtWithOptions para avaliações repetidas em células de destino diferentes

Fórmulas A1 e R1C1 comuns reutilizam diretamente a árvore compilada; referências estruturadas A1 cujo significado depende da linha da tabela de destino são resolvidas e compiladas para aquele contexto de destino

Os modelos não mantêm estado gravável de planilha, relatam xlfeWorksheetUnavailable com segurança após a destruição da pasta de trabalho e recaem na recompilação consciente do contexto quando alterações da pasta de trabalho tornam o contexto compilado original obsoleto

Opções de recursos, referências externas e retornos de chamada

AllowExternalReferences	O padrão é true, mas permite somente destinos de espaço de trabalho registrados explicitamente ou caches locais do arquivo e nunca realiza acesso implícito a arquivos ou à rede
AllowUnsafeFormulaCallbacks	O padrão é false e impede que nomes de funções perigosas cheguem a um registro de funções do usuário ou a um retorno de chamada antes que qualquer argumento seja avaliado; a negação retorna `xlfeUnsafeFunctionDenied`
CancelFlag	Ponteiro Boolean opcional verificado antes e depois da avaliação
MaxFormulaLength	O padrão é 8192 unidades de código UTF-16
MaxEvaluationSteps	O padrão é 1,000,000 avaliações de itens de sintaxe
MaxRecursionDepth	O padrão é 256 avaliações de fórmulas aninhadas
MaxArrayBytes	O padrão é 64 MiB para cargas úteis de matrizes geradas

Um máximo zero ou negativo desativa esse limite por chamada; a política de memória de matrizes de toda a pasta de trabalho ainda se aplica, e atingir um limite habilitado retorna xlfeResourceLimit após liberar o estado temporário de avaliação

A sobrecarga que aceita opções explícitas trata AllowUnsafeFormulaCallbacks como autoritativa para essa chamada; a avaliação única padrão e a avaliação de modelo herdam a propriedade da pasta de trabalho de mesmo nome

Exemplo em Delphi

Template := Sheet.CreateFormulaEvaluationTemplate(2, 2,
  '=R[-1]C[-1]+1', xlfrsR1C1);

Result := Template.EvaluateAt(2, 2);
if Result.Status = xlfeOk then
  UseValue(Result.Value);

Options := XLSDefaultFormulaEvaluationOptions;
Options.MaxEvaluationSteps := 10000;
Result := Template.EvaluateAtWithOptions(20, 4, Options);

Exemplo em C++Builder

Lxcalc::_di_IXLSFormulaEvaluationTemplate evalTemplate =
  sheet->CreateFormulaEvaluationTemplate(1, 1,
    WideString(L"=ROW()+COLUMN()"), Lxcalc::xlfrsA1);

Lxcalc::TXLSFormulaEvaluationResult result =
  evalTemplate->EvaluateAt(7, 8);

A API de backend de expressões regulares direta documenta correspondência por instância, substituição, status e orçamentos do chamador

As fórmulas REGEX compartilham os controles de trabalho, memória e cancelamento do contexto de avaliação atual, incluindo alocações de workspace e de saída do PCRE2; cancelamento ou um limite de recursos produz um status explícito sem um resultado parcial de extração ou substituição

GROUPBY e PIVOTBY resumem arrays destacados ou snapshots de intervalos de planilha no contexto atual, incluindo ambientes Lambda capturados, índices de agrupamento, vetores de callback e armazenamento de saída; limites de recursos e cancelamento retornam status explícitos sem alterar dados da planilha, caches ou layout

Veja também

Método TXLSWorksheet.Calculate
Método IXLSWorkbook.Calculate
Mecanismo de cálculo do Excel