Documentação HotXLS

Referências a pastas de trabalho externas

Visão geral

Modelos de planilhas frequentemente obtêm dados de pastas de trabalho secundárias usando fórmulas de referência cruzada; o HotXLS oferece suporte à análise, gravação e preservação de referências a pastas de trabalho externas tanto em documentos BIFF8 (XLS clássico) quanto em OpenXML (XLSX)

Workspace de pastas de trabalho ativas

TXLSWorkbookWorkspace em lxWorkbookWorkspace é o núcleo compartilhado de identidade e registro para pastas de trabalho externas ativas; tanto TXLSWorkbook quanto TXLSXWorkbook expõem CreateWorkspaceWorkbook e possuem um ExternalWorkspace usado por seus avaliadores de fórmulas, enquanto uma pasta de trabalho ODS aberta por meio do TXLSXWorkbook informa o tipo de mecanismo OpenDocument pelo mesmo adaptador

var
  Host, Target: TXLSXWorkbook;
begin
  Host.ExternalWorkspace.Add(
    '..\Data\Target.xlsx',
    '..\Data\Target.xlsx',
    'C:\Models\Host.xlsx',
    Target.CreateWorkspaceWorkbook);

  // The compatibility facade maps an unambiguous name to the
  // relationship target already stored in Host.ExternalLinks
  Host.RegisterExternalWorkbook('Target.xlsx', Target);

  // The matching call revokes a facade-level registration
  Host.UnregisterExternalWorkbook('Target.xlsx');
end;

Pastas de trabalho clássicas usam os mesmos métodos de compatibilidade com destinos TXLSWorkbook; RegisterExternalWorkbook e UnregisterExternalWorkbook gerenciam apenas o mapeamento de nomes no nível da fachada, enquanto ExternalWorkspace.Remove e Clear revogam os registros do workspace em si. Chamadores de motores cruzados adicionam qualquer adaptador Classic, XLSX ou ODS diretamente ao ExternalWorkspace

  • A normalização de identidade é lexical e insensível a maiúsculas e minúsculas, preserva caminhos e extensões, resolve destinos relativos com base na identidade de origem do proprietário, colapsa segmentos de ponto e não realiza acesso a sistema de arquivos ou à rede
  • Identidades exatas e apelidos explícitos são resolvidos primeiro; a busca apenas pelo nome base só tem sucesso quando exatamente um registro conectado corresponde, caso contrário Resolve retorna xlswrsConflict
  • Add rejeita colisões de chave exata, de apelido e de pasta de trabalho duplicada; caminhos completos distintos e extensões distintas podem coexistir
  • Remove e Clear revogam os registros, enquanto a destruição direta de um destino Classic ou XLSX desconecta seu adaptador e aguarda os leitores ativos antes de liberar o modelo
  • Planilhas externas são resolvidas pelo nome declarado antes do fallback posicional baseado em um, de modo que a ordem de planilhas da pasta de trabalho de destino não precisa corresponder ao diretório de vínculos da origem
  • O avaliador de fórmulas lê primeiro uma pasta de trabalho ativa resolvida e então recorre ao cache tipado do arquivo hospedeiro; hospedeiros Classic XLS decodificam valores XCT e CRN esparsos, enquanto hospedeiros XLSX usam o cache de vínculos externos já mantido pelo modelo de pacote
  • OnLoadWorkbook é uma solicitação de recurso controlada e opcional; seu valor padrão é nil, então o recálculo ainda não realiza acesso a sistema de arquivos ou à rede, a menos que o código da aplicação forneça explicitamente essa política
  • Cada identidade normalizada invoca o loader no máximo uma vez até ResetLoadAttempts; solicitações concorrentes de nível superior compartilham o resultado em andamento, incluindo desfechos tipados de não encontrado e de erro, em vez de abrir o mesmo recurso repetidamente
  • MaxLoadDepth tem padrão 16 e MaxWorkbookCount tem padrão 64; reentrada com a mesma identidade, dependências aninhadas a uma identidade já em andamento, esgotamento de profundidade e esgotamento da contagem de pastas de trabalho retornam diagnósticos tipados sem bloquear dentro de um ciclo de carga
  • IRIs de fonte externa ODF permanecem identidades lexicais completas, incluindo esquemas URI e caracteres entre aspas, mas nunca autorizam acesso implícito a arquivos ou à rede
  • Um conflito de identidade permanece #REF! para que dados em cache desatualizados não possam esconder um roteamento ambíguo; uma célula ausente no cache é um valor vazio apenas quando o arquivo declara um cache válido para aquela planilha

Resolve realiza a busca nos registros e depois a carga controlada opcional; seu desfecho é um TXLSWorkspaceResolveStatus (xlswrsResolved, xlswrsNotFound, xlswrsConflict, xlswrsDisconnected, xlswrsLoadNotFound, xlswrsLoadLimit, xlswrsLoadLoop ou xlswrsLoadError), e ResolveWithLoader também retorna um TXLSWorkspaceLoadDiagnostic que combina um TXLSWorkspaceLoadDiagnosticCode com um TXLSWorkspaceLoadResponseStatus (xlswlrsNotFound, xlswlrsResolved, xlswlrsError) para distinguir desfechos de não encontrado, erro do loader, resultado desconectado, limite de profundidade ou de pastas de trabalho, reentrada de identidade, dependência concorrente e conflito de registro. O retorno de chamada do loader recebe um TXLSWorkspaceLoadRequest (identidade, profundidade, contagem de registros, limites) e responde com um TXLSWorkspaceLoadResponse

Recalculate informa um TXLSWorkspaceRecalcStatus, opcionalmente com um detalhamento TXLSWorkspaceRecalcResult, e o avaliador registra a procedência por célula como um TXLSWorkspaceRuntimeLookup (xlswrlInactive, xlswrlResolved, xlswrlFallbackCache ou xlswrlError) para que os diagnósticos saibam distinguir uma leitura ativa de um fallback em cache

O adaptador IXLSWorkspaceWorkbook expõe EngineKind (tipo TXLSWorkspaceEngineKind: xlsweClassic, xlsweOpenXml ou xlsweOpenDocument), SourceIdentity, InstanceIdentity e Generation, testa a atividade com IsConnected, lê uma célula por meio de TryGetCellValue (retornando um TXLSWorkspaceCellStatus tipado de valor, ausente, referência inválida, desconectado ou erro, mais um sinalizador de fora do intervalo usado), atualiza o modelo com Recalculate e se desvincula do modelo da pasta de trabalho com Disconnect

O registro acrescenta AddAlias para nomes extras vinculados a uma identidade registrada, TryResolve como a variante de busca sem exceções, e BaseNameMatchCount para pré-visualizar quantos registros conectados compartilham um nome base antes de escolher um destino inequívoco

Grafo de dependências entre pastas de trabalho

BuildDependencyGraph tira um instantâneo de todos os adaptadores de pasta de trabalho registrados e extrai nós de fórmulas dos modelos Classic XLS, XLSX e ODS para um único TXLSWorkspaceDepGraph; o método retorna False e nenhum grafo parcial quando qualquer adaptador registrado não consegue fornecer metadados de dependência

  • Cada nó de fórmula mantém sua identidade canônica de pasta de trabalho, nome da planilha e posição da planilha com base um, posição da célula com base zero, retângulo de saída da matriz, volatilidade e estado de referência não resolvida
  • Referências de células e de intervalos retangulares mantêm identidades canônicas de pasta de trabalho e planilha de destino; referências de coluna inteira, linha inteira e planilha inteira permanecem um único intervalo em vez de se expandir para milhões de células
  • Nomes definidos locais permanecem consultáveis como dependências simbólicas e também se expandem para suas dependências concretas de célula ou intervalo quando a definição pode ser resolvida estaticamente
  • Nomes definidos externos preservam o slot de vínculo externo, o nome declarado, o escopo opcional de planilha e a identidade canônica do destino, sem tratar metadados de DDE, OLE ou funções de usuário como nomes de pasta de trabalho
  • FindDependentsOfCell e a construção de arestas do grafo usam árvores de intervalos de linhas com poda de extremo máximo; LastRangeCandidateChecks e EdgeCandidateChecks expõem o número de verificações exatas de retângulos para verificação de desempenho
  • A extração de fórmulas executa sob leases de leitura da pasta de trabalho e examina apenas objetos de fórmula materializados, de modo que o armazenamento de valores compactado permanece compactado e a criação do grafo não modifica as gerações da pasta de trabalho

Recálculo agendado

Recalculate retém o grafo compartilhado e o reconstrói apenas quando o registro do workspace ou a geração de dependências de fórmulas de uma pasta de trabalho muda; gerações de valor iniciam uma nova passada de pendência, e a pendência se propaga pelas arestas dependentes entre pastas de trabalho

var
  RecalcInfo: TXLSWorkspaceRecalcResult;
  Status: TXLSWorkspaceRecalcStatus;
begin
  Status := Workspace.Recalculate(RecalcInfo);
  if Status <> xlswrcOk then
    HandleWorkspaceCalculation(Status, RecalcInfo);
end;
  • Componentes fortemente conectados são computados sobre células de fórmulas, de modo que pastas de trabalho podem se vincular nos dois sentidos e permanecer acíclicas quando seus caminhos de dependência no nível de células não formam um ciclo
  • Membros reais de ciclos e descendentes pendentes bloqueados por um ciclo são invalidados e excluídos da ordem topológica, impedindo que valores em cache desatualizados sejam apresentados como resultados bem-sucedidos
  • Referências voláteis ou não resolvidas estaticamente forçam o comportamento conservador de pendência exigido para a correção, enquanto grafos estáveis reutilizam o trabalho de dependência anterior
  • Leituras externas dentro de uma passada usam um cache exato de instância de pasta de trabalho, planilha, linha e coluna; uma fórmula agendada invalida seu intervalo de saída antes da avaliação para que dependentes posteriores observem o novo valor
  • O cache local da passada nunca concede autoridade de recurso; as pastas de trabalho registradas e o loader opcional controlado pelo chamador permanecem as únicas fontes de resolução ativa, seguidas pelos caches tipados de arquivo e por #REF!
  • TXLSWorkspaceRecalcResult expõe se o grafo foi reconstruído, além das contagens de pendentes, avaliadas, invalidadas, de ciclos, de bloqueadas, de acertos e de falhas de cache
  • O status distingue sucesso, adaptadores sem suporte, pastas de trabalho desconectadas, referências circulares, erros de cálculo e mutação do workspace durante a passada
  • Chamadas a Recalculate no mesmo workspace são serializadas, de modo que duas sessões de cálculo nunca modificam o grafo compartilhado ou os caches da pasta de trabalho simultaneamente
  • Remove ou Clear pode executar enquanto uma passada está ativa; a passada mantém instantâneos seguros dos adaptadores e retorna xlswrcWorkspaceChanged em vez de desreferenciar um registro removido
  • Destruir um workspace aguarda o término de sua passada ativa, enquanto destruir uma pasta de trabalho registrada desconecta seu adaptador e faz as resoluções posteriores falharem com segurança
  • Falhas do loader e resultados de não encontrado permanecem em cache uma vez por identidade normalizada até ResetLoadAttempts, e um cálculo com falha retém o estado local de pendência para uma nova tentativa explícita
  • O grafo retido torna uma passada subsequente sem mudanças proporcional às pastas de trabalho registradas em vez da contagem de fórmulas; a análise de componentes não recursiva e as arestas compactas de intervalo mantêm modelos profundos e largos limitados pelos metadados de fórmulas materializados

Desanexar nomes definidos externos

ConvertExternalDefinedNamesToRefErrors oferece a mesma operação pública em TXLSWorkbook e TXLSXWorkbook; ele retorna o número de definições no escopo da pasta de trabalho e no escopo da planilha substituídas por #REF! nativo

var
  Converted: Integer;
begin
  Converted := Workbook.ConvertExternalDefinedNamesToRefErrors;
  // External-link parts and ordinary cell formulas remain intact
end;
  • A seleção no XLS clássico usa tokens de referência BIFF compilados e a identidade XTI da pasta de trabalho de suporte, de modo que referências tridimensionais na mesma pasta de trabalho e fluxos de tokens incertos permanecem inalterados
  • A seleção no XLSX usa slots numéricos de pasta de trabalho com reconhecimento de sintaxe na ordem dos relacionamentos do documento e aceita apenas partes de vínculos externos da pasta de trabalho, excluindo DDE, OLE, slots não resolvidos, referências de tabela e texto entre colchetes dentro de cadeias de caracteres
  • Todas as substituições são preparadas antes da primeira mutação e confirmadas como uma única operação de gravação; uma segunda chamada é idempotente
  • Texto do nome, escopo de pasta de trabalho ou planilha, visibilidade, comentários, sinalizadores de macro e internos, atributos XLSX desconhecidos e o diretório de vínculos externos permanecem disponíveis após a conversão e o round-trip
  • Definições malformadas e sem suporte permanecem preservadas byte a byte ou no texto sempre que possível e acrescentam diagnósticos xlsDiagnosticDefinedNameConversionSkipped em vez de serem adivinhadas
  • Fórmulas dependentes recalculam para o valor de erro correspondente do Excel, enquanto um resultado em cache válido para uma fórmula externa direta comum permanece disponível se sua pasta de trabalho ativa se desconectar depois
  • A operação é específica do Excel e não reinterpreta a semântica de fórmulas de nomes do OpenDocument

Referências externas no XLS clássico

Em pastas de trabalho XLS clássicas, os vínculos externos são armazenados no bloco de diretório global usando registros EXTERNALBOOK e EXTERNNAME; o HotXLS mantém esses diretórios durante os ciclos de leitura e gravação do arquivo, garantindo que as referências a intervalos remotos sobrevivam aos loops de modificação

Relações externas do XLSX

Para pastas de trabalho OOXML, o mapeamento de vínculos externos é gerenciado por meio de partes de relacionamento; verifique os detalhes das interfaces de suporte abaixo

Copyright © 2010-2026 losLab Software