Tokens de fórmula e funções de usuário

O HotXLS expõe fluxos de tokens de fórmula de propriedade do chamador para inspeção sem perdas e regravação protegida em ambos os mecanismos de pasta de trabalho, além de registros hierárquicos de funções de usuário para cálculo personalizado

Modelo de token

TXLSFormulaTokenClass, TXLSFormulaTokenKinde TXLSFormulaTokenSource classificam cada TXLSFormulaToken e registram se ele veio de texto analisado, bytes BIFF clássicos ou outra origem suportada

Cada mecanismo de pasta de trabalho compila e traduz fórmulas por meio de uma única instância compartilhada de TXLSFormula: GetCompiled analisa texto no estilo A1 em uma árvore de sintaxe, GetCompiledR1C1 resolve referências R1C1 com base nas coordenadas da célula onde a fórmula vive, GetTranslated reconstrói uma árvore a partir de bytes BIFF clássicos, e a família GetStoreData grava os bytes dos tokens de volta para armazenamento. MaxRow e MaxCol delimitam a grade de referências que o compilador aceita — o mecanismo XLSX os eleva dos padrões do BIFF8 para a grade do XLSX, e referências que não cabem no BIFF8 não têm forma ptg, então os gravadores BIFF8 as reportam como não codificáveis

ArrayFormulaMode é definido enquanto o rgce de um record ARRAY (uma fórmula de matriz) é gravado: referências de classe de valor e constantes de matriz então se serializam como classe de matriz (tAreaA / tArrayA), do jeito que o próprio Excel as grava. Com operandos de classe de valor, o Excel avalia a fórmula de matriz com interseção implícita em vez de tratá-la como uma fórmula de matriz de verdade, e é por isso que os mecanismos definem a flag para o rgce do próprio record ARRAY

Inspeção limitada de uma folha armazenada simples

TXLSCompiledFormula.ReadSimpleLeafInfo(ExpectedOwner, MaxBytes, MaxTextCharacters, AllowUnboundBiff) inspeciona a árvore de sintaxe principal e qualquer fluxo de tokens retido in place, sem clonar, descompilar, avaliar ou materializar tokens ou arrays; o padrão de AllowUnboundBiff é False

As formas suportadas são uma única folha absoluta REF3D ou RANGE3D e um literal de string, com exatamente um token coerente quando um fluxo é retido; expressões, referências relativas ou com deslocamento, arrays, dados de array externos, tokens desconhecidos, folhas principal e retida divergentes e proprietários vinculados estranhos retornam fslkUnsupported sem alterar valores em cache ou o estado de cálculo

ExpectedOwner deve ser o calculador exato anexado à origem consumidora, e deve permanecer vivo e estável durante toda a inspeção e a extração de literais; um proprietário ausente gera EArgumentException, quotas negativas geram EArgumentOutOfRangeException, e entradas de origem retidas grandes demais geram EInvalidOperation antes de comparações de conteúdo ou de cópia de saída

Uma folha simples sem fluxo retido não estabelece seu proprietário original; um fluxo importado não vinculado também não carrega identidade de pasta de trabalho, de modo que AllowUnboundBiff=True explícito é apropriado apenas quando o chamador já fixou o calculador de origem e validará a identidade local da planilha antes de ler células; a inspeção de referências importadas atualmente aceita referências BIFF8 e rejeita a representação externa diferente do BIFF5

Os campos de sintaxe legados nomeados FFirstRowRel, FFirstColRel, FLastRowRele FLastColRel são verdadeiros para coordenadas absolutas; o helper também verifica as flags independentes de token relativo e a representação de deslocamento, de modo que os consumidores não precisem inferir coordenadas absolutas a partir desses nomes históricos

Árvore de sintaxe

CloneSyntaxTree retorna uma árvore analisada de propriedade do chamador com nós TXLSSyntaxItem para inspeção estrutural: cada nó informa seu ItemType, payload literal (Value, IntValue, DecValue), Spacesiniciais, vínculos de árvore (Parent, Child, ChildCount), a folha de referência como um TXLSRangeItem por meio de Rangee dados de constante de matriz (ArrayRows, ArrayCols, ArrayValueCounte as entradas TXLSArraySerVal em ArrayValues). A árvore é uma cópia destacada, então percorrê-la nunca toca as fórmulas compiladas da pasta de trabalho, e os membros de mutação (AddChild, PushChild, CopyObject, OffsetCopyReferences, AdjustForShifte TXLSRangeItem.CopyObject / AdjustForShift) existem para ferramentas que reescrevem uma árvore clonada antes da recompilação

Pontos de entrada da pasta de trabalho

Tokens := Worksheet.ParseFormulaTokens('SUM(A1:A4)', 1, 1);
try
  if Tokens.ReplaceReference(OldRef, NewRef) then
    Worksheet.SetFormulaTokens(1, 1, Tokens);
finally
  Tokens.Free;
end;

ParseFormulaTokens, GetFormulaTokens, FormulaTokensToTexte SetFormulaTokens mantêm a propriedade explícita e validam o contexto, a versão BIFF, o suporte a tokens, a propriedade de matrizes e os limites de referência antes de uma célula ser alterada

Registros de funções de usuário

TXLSUserFunctionResolver e TXLSUserFunctionRegistry fornecem consulta por nome por meio de RegisterHandler, UnregisterHandler, Clear, Contains, TryGetHandlere Count

Workbook.RegisterUserFunction('NETMARGIN', CalculateNetMargin);
Workbook.RegisterGlobalUserFunction('FISCALYEAR', CalculateFiscalYear);
try
  Workbook.Calculate;
finally
  Workbook.UnregisterUserFunction('NETMARGIN');
  Workbook.UnregisterGlobalUserFunction('FISCALYEAR');
end;

IXLSWorkbook, TXLSWorkbooke TXLSXWorkbook expõem RegisterUserFunction, UnregisterUserFunction, ClearUserFunctions, RegisteredUserFunctionCount, RegisterGlobalUserFunction, UnregisterGlobalUserFunction, ClearGlobalUserFunctionse RegisteredGlobalUserFunctionCount

Os pontos de entrada equivalentes no nível da unidade são XLSRegisterGlobalUserFunction, XLSUnregisterGlobalUserFunction, XLSClearGlobalUserFunctions, XLSRegisteredGlobalUserFunctionCounte XLSGlobalUserFunctionRegistered

TXLSCalculator.OnUserFunctionResolve participa antes do fallback de evento legado, e os manipuladores do registro são invocados fora do bloqueio do registro para que um manipulador possa se desregistrar com segurança

Nomes de funções externas e de estilo macro perigosos são bloqueados antes da avaliação dos argumentos e da busca pelo handler, a menos que AllowUnsafeFormulaCallbacks esteja explicitamente habilitado para a pasta de trabalho ou para a avaliação contextual individual; nomes comuns de user functions permanecem disponíveis por padrão

Diagnósticos de fórmula

TXLSXFormulaIssueKind, TXLSXFormulaLocatione TXLSXFormulaIssue são retornados por TXLSXWorkbook.AnalyzeFormulaIssues para funções ausentes, referências externas e componentes de dependência circular

Inspeção de planilha de macro

TXLSSheetKind distingue registros de planilha, planilha de macro, planilha de gráfico, módulo VBA e planilha desconhecida por meio de TXLSWorksheet.SheetKind; TXLSMacroRisk, TXLSMacroCommandInfoe TXLSMacroCommandArray descrevem os resultados tipados de TXLSWorksheet.ScanMacroCommands

Tipos de AutoAjuste mesclado e de classificação

TXLSMergedAutoFitStrategy e TXLSXMergedAutoFitStrategy escolhem crescimento primeiro, último ou balanceado para intervalos mesclados, enquanto TXLSSortOrientation, TXLSSortFormulaModee TXLSSortCompareEvent controlam a classificação estável vertical ou horizontal e o movimento de fórmulas

Veja também

• Mecanismo de cálculo do Excel
• Rastreamento e auditoria de fórmulas
• Fluxos de trabalho avançados de pasta de trabalho