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

Unidade: HPDFXFAPresentation

TXFAInstancePresentation é dona de um TXFAWidgetRuntime independente e acrescenta um perfil delimitado de apresentação de instâncias para documentos de pacotes XDP com um registo de datasets

Use SetPresence('row[1]', 'hidden') para remover uma ocorrência do fluxo, invisible para manter o espaço dela enquanto oculta os widgets dela, e visible para restaurá-la; os í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 offsets verticais sobreviventes e reserva a extensão repetida completa antes de posicionar o conteúdo seguinte; linhas de altura fixa, de altura derivada do conteúdo e de tabelas participam no reflow

Identidade estável e persistência

Os IDs de widgets combinam identidades opacas de templates e de datasets e permanecem estáveis quando linhas anteriores são ocultadas ou removidas, após gravação e recarregamento, e enquanto campos sobreviventes mantêm foco ou edições pendentes

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

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

Após recarregamento 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 fábrica por defeito de runtimes carregados e leitores XFA externos não aplicam automaticamente os overrides por instância dele, pelo que guardar persistentemente o perfil não afirma renderização idêntica noutros leitores

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

Subforms repetidos podem vincular-se 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 caminhos relativos suportam grupos pais não indexados e um grupo final repetido

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

AddInstance e RemoveInstance atualizam o grupo de dados selecionado, impõem o mínimo e o 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 introduzidos da linha anterior

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

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

Eventos condicionais

DispatchConditionalEvent localiza um evento de campo correspondente com tipo de conteúdo JavaScript e analisa diretamente o perfil delimitado; Execute corre um script explícito contra um ID de widget existente

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

As condições aceitam igualdade ou desigualdade entre this.rawValue e um literal entre aspas sem escape; blocos aninhados if entre chavetas e blocos else opcionais são delimitados por MaxDepth

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

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

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

Transações e orçamentos

As mutações executam através de TXFAWidgetRuntime.UpdateDocument, juntamente com cálculos nativos e reflow estável delimitado; a falha restaura o XDP serializado, o foco, as edições pendentes, o estado de validação, os contadores de cálculo e de reflow e a contagem de avisos

Callbacks de foco, layout e invalidação de widgets só são publicados após sucesso; a resolução de rollback suprime o trabalho esgotado do helper e as verificações de cancelamento mantendo 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 de documentos, 65,536 bytes de scripts, 32 níveis de aninhamento condicional e 5,000 milissegundos

MaxInputBytes também delimita um envelope XML conservador com escape antes de cada passagem de layout e de publicação, incluindo atributos de identidade, declarações de namespaces, texto e alterações de datasets; XML válido pode atingir este limite conservador antes de a contagem de bytes serializada dele atingir o mesmo valor

Cancelled é um callback opcional de métodos de objeto verificado durante o trabalho delimitado; as opções do Runtime incorporado continuam a delimitar widgets, valores, cálculos, layout, reflow e trabalho nativo de scripts

Pintura pelo host e acessibilidade

Accessibility devolve registos visíveis de widgets com ID estável, role, caption ou nome do campo, descrição de tooltip, valor confirmado, página e bounds, foco, validade, estados só de leitura e obrigatórios e etiquetas de escolhas; valores de palavras-passe são omitidos

PaintPage entrega um snapshot de widgets visíveis e registos de acessibilidade correspondentes a um TXFAHostWidgetPainter; hosts personalizados podem implementar os controlos ou a superfície de renderização próprios deles

TXFACanvasWidgetPainter fornece pintura real de canvas VCL e LCL para contornos de widgets, texto, máscaras de palavras-passe, marcas de checkboxes e radios, indicadores de escolhas, botões e foco, com escala positiva e offsets opcionais; corta cada widget e restaura os estilos do canvas

O adaptador de canvas pinta widgets e não pinta a árvore estática completa de gráficos XFA; o host fornece o próprio fundo de páginas, gráficos estáticos, encaminhamento 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; os callbacks têm de seguir a propriedade de threads do host e evitar mutações recursivas durante uma transação ativa

Quem chama a partir de C++Builder tem de fornecer todos os argumentos do construtor de pintores de canvas, como new TXFACanvasWidgetPainter(canvas, 1, 0, 0); os cabeçalhos gerados não retêm estes argumentos por defeito de vírgula flutuante

Verificação

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

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

Run-XFAInstancePresentationTests.ps1 corre as verificações do helper e os fixtures existentes de regressão de eventos XFA, runtime, scripting, SOM, DOM e resolução sem GUI nem leitores PDF externos

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

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