Apresentação dinâmica de instâncias XFA

Unit: HPDFXFAPresentation

TXFAInstancePresentation é dona de um TXFAWidgetRuntime independente e adiciona um perfil delimitado de apresentação de instâncias para documentos de packets XDP com um record de datasets

Use SetPresence('row[1]', 'hidden') para remover uma ocorrência do fluxo, invisible para reter o espaço dela enquanto oculta os widgets dela, e visible para restaurá-la; índices são posições com base zero entre ocorrências de dados, incluindo ocorrências ocultas

O resolver de layout mede cada ocorrência separadamente, compacta os offsets verticais sobreviventes e reserva a extensão repetida completa antes de posicionar o conteúdo seguinte; linhas de altura fixa, altura derivada de conteúdo e de tabelas participam do reflow

Identidade estável e persistência

IDs de widgets combinam identidades opacas de template e datasets e permanecem estáveis quando linhas anteriores são ocultadas ou removidas, após save e reload, e enquanto campos sobreviventes retêm focus ou edições pendentes

O helper armazena atributos de identidades qualificados por namespace e overrides de instâncias numa extensão de namespace estrangeiro dentro do packet de formulários, usando urn:hotpdf:xfa:instance-presentation:1; linhas recém-adicionadas recebem identidades frescas e defaults de template, e linhas removidas não podem transferir edições pendentes a linhas de substituição

SaveToBytes retorna o XDP completo, incluindo datasets atualizados, identidades e estados de apresentação; use THotPDF.SetXFADocument para persisti-lo num PDF e defina XFANeedsRendering := True ao gravar um formulário dinâmico

Após o reload do PDF, obtenha o XDP completo com THotPDF.CreateLoadedXFAWidgetRuntime.SaveToBytes, e depois construa TXFAInstancePresentation a partir desses bytes para restaurar este perfil

A extensão de namespace é interpretada por este helper; o HPDFXFAFlatten nativo, a factory default de runtimes carregados e viewers XFA externos não aplicam automaticamente os overrides por instância dele, então armazenar o perfil persistentemente não afirma rendering idêntico em outros readers

Binding explícito e operações de instâncias

Subforms repetidos podem se vincular a um grupo de datasets com nome diferente através de <bind match="dataRef" ref="$record.lines.entry[*]"/>; raízes absolutas $record e $data e paths relativos suportam grupos pais sem índice e um grupo final repetido

Campos dentro de cada ocorrência usam o resolver nativo de valores vinculados, incluindo bindings explícitos relativos de campos como ref="label"

AddInstance e RemoveInstance atualizam o grupo de dados selecionado, aplicam o mínimo e máximo de occur, aplicam limites de criação e fazem reflow antes da publicação; a linha nova recebe valores de campos do template em vez de copiar valores digitados da linha anterior

Selectors usam um nome único de template com um índice opcional de ocorrências, como row[1]; nomes de template duplicados, grupos ausentes, índices inválidos e mutações sob um pai repetido ambíguo rejeitam a transação

SetAccess suporta open, readOnly, protected e nonInteractive; restrições de instâncias são herdadas pelos descendentes e impedem a edição pelo runtime próprio

Eventos condicionais

DispatchConditionalEvent localiza um evento de campo correspondente com content type JavaScript e parseia o perfil delimitado diretamente; Execute roda um script explícito contra um ID existente de widget

if(this.rawValue=="hide"){
  row[1].presence="hidden";
}else{
  row[1].presence="visible";
}
row.instanceManager.addInstance();
row.instanceManager.removeInstance(0);

Condições aceitam igualdade ou desigualdade entre this.rawValue e um literal entre aspas não escapado; blocos aninhados de if entre chaves e o else opcional são delimitados por MaxDepth

Atribuições suportam presence e access; todos os ramos são checados sintaticamente, incluindo ramos não tomados, e operações não suportadas rejeitam o lote inteiro

this.rawValue lê o valor commitado do widget; commite edições pendentes através de Runtime.CommitEdit antes de despachar um evento que deva observá-las

O Runtime.DispatchEvent original retém seu comportamento restrito de operações literais e rejeita sintaxe condicional e de instâncias indexadas; este helper não fornece um interpretador geral de JavaScript ou FormCalc, APIs de browser, acesso à rede nem despacho automático de lifecycle XFA

Transações e orçamentos

Mutações executam através de TXFAWidgetRuntime.UpdateDocument, junto de cálculos nativos e reflow estável delimitado; falha restaura o XDP serializado, focus, edições pendentes, estado de validação, contadores de cálculo e reflow e contagem de warnings

Callbacks de focus, layout e invalidação de widgets publicam somente após o sucesso; a resolução de rollback suprime o trabalho esgotado do helper e as checagens de cancelamento enquanto retém o layout nativo e os bounds de widgets, para que o cancelamento não possa impedir a restauração

Inicialize TXFAPresentationOptions com Default; os defaults são 200.000 operações, 4.096 estados de apresentação, 10.000 instâncias criadas por grupo, 32 MiB de envelope de entrada e documento, 65.536 bytes de scripts, 32 levels de aninhamento condicional e 5.000 milissegundos

MaxInputBytes também delimita um envelope XML conservador escapado antes de cada passada de layout e publicação, incluindo atributos de identidades, declarações de namespaces, texto e mudanças de datasets; XML válido pode chegar a esse limite conservador antes de a contagem de bytes serializada dele chegar ao mesmo valor

Cancelled é um callback opcional de método de objeto checado durante o trabalho delimitado; as opções do Runtime embutido continuam delimitando widgets, valores, cálculos, layout, reflow e trabalho nativo de scripts

Pintura do host e acessibilidade

Accessibility retorna records visíveis de widgets com ID estável, role, caption ou nome de campo, descrição de tooltip, valor commitado, página e bounds, focus, validade, estados read-only e required, e rótulos de choices; valores de password são omitidos

PaintPage entrega um snapshot de widgets visíveis e os records correspondentes de acessibilidade a um TXFAHostWidgetPainter; hosts customizados podem implementar os próprios controles ou superfície de rendering deles

TXFACanvasWidgetPainter fornece pintura real de canvases VCL e LCL para bordas de widgets, texto, mascaramento de password, marcas de checkboxes e radios, indicadores de choices, botões e focus, com escala positiva e offsets opcionais; ele clipa cada widget e restaura os estilos da canvas

O adapter de canvas pinta widgets e não pinta a tree estática completa de gráficos do XFA; o host fornece o próprio fundo de páginas, gráficos estáticos, roteamento de eventos, apresentação de seleções e ponte de acessibilidade dele para a plataforma dele

O runtime e o helper são objetos single-thread; callbacks precisam seguir a posse de threads do host e evitar mutações recursivas durante uma transação ativa

Chamadores C++Builder precisam fornecer todos os arguments do construtor do canvas painter, como new TXFACanvasWidgetPainter(canvas, 1, 0, 0); os headers gerados não retêm esses arguments default de ponto flutuante

Verificação

A aceitação cobre 106 casos Delphi por arquitetura, compilação FPC fresca nas duas arquiteturas Windows, compilação de headers públicos C++Builder em Win32 e Win64x, e validação independente da saída real PDF/XDP

Tests/Fixtures/XFAInstancePresentation/explicit-invoice.xdp contém nomes independentes de dados, três linhas de faturas repetidas, um evento condicional, metadados de acessibilidade e um footer seguinte

Run-XFAInstancePresentationTests.ps1 executa as checagens do helper e os fixtures existentes de regressão de eventos, runtime, scripting, SOM, DOM e resolução do XFA, sem GUI nem readers PDF externos

O verify_saved_invoice.py independente lê o PDF gerado com pypdf e checa linhas reais de dados XDP, identidades persistentes únicas, estado de ocorrências ocultas, defaults inicializados e identidades de reload

powershell -File Tests/Delphi/Run-XFAInstancePresentationTests.ps1 -Platform Win32 -CheckCppHeaders
powershell -File Tests/Delphi/Run-XFAInstancePresentationTests.ps1 -Platform Win64 -CheckCppHeaders
python Tests/Fixtures/XFAInstancePresentation/verify_saved_invoice.py

Veja o Runtime interativo de widgets XFA para o runtime base compatível e o contrato nativo de edição