Classe TXFADataStructure

TXFADataStructure, declarada em HPDFXFADataStructure, mantém edições estruturais delimitadas a uma tree nativa existente de nós XFA e é dona de quaisquer trees de elementos desanexadas criadas, clonadas ou removidas pelo grafo

CreateDataNode atende elementos do Data DOM, enquanto CreateElement também suporta a construção de elementos de modelo usada pela TXFAFormStructure

O construtor empresta Root e valida a tree existente contra TXFADataStructureLimits antes de retornar; o grafo precisa ser destruído antes do dono da raiz emprestada

Todos os nomes AnsiString públicos, namespace URIs e valores de texto contêm bytes UTF-8

Graph := TXFADataStructure.Create(DatasetsRoot, Limits, OnTick);
try
  Graph.BeginOperation(OnTick);
  try
    Node := Graph.CreateDataNode('dataValue', 'amount');
    Graph.SetValue(Node, '42');
    Graph.Append(RecordNode, Node);
  finally
    Graph.EndOperation;
  end;
finally
  Graph.Free;
end;

Escopo de operações

BeginOperation(OnTick) inicia um escopo e rejeita um escopo aninhado; EndOperation libera o callback armazenado e é seguro durante a limpeza

O construtor executa o próprio escopo de preflight dele e libera o callback do construtor antes de retornar; os métodos subsequentes exigem um novo escopo ativo

OnTick é uma anonymous procedure Delphi ou uma nested procedure FPC do tipo TXFADataStructureTick; ela pode disparar erro para cancelar trabalho ou aplicar um deadline do chamador ou contador de operações

Os métodos preparam alocações, capacidade de posse e declarações exigidas de namespaces antes da checagem final de cancelamento e da mutação estrutural; uma edição individual rejeitada preserva o grafo existente do documento

Uma série de chamadas diretas bem-sucedidas ao grafo não é revertida automaticamente quando uma chamada posterior falha; o runtime de scripting fornece a transação completa de eventos e restaura juntos o documento, o grafo desanexado, identidades de scripts, estado lexical e journal

Criação e clonagem

CreateDataNode(ClassName, Name, NamespaceURI = '') aceita dataGroup ou dataValue, cria um elemento desanexado fresco e registra metadados explícitos de classes de data nodes

CreateElement(ClassName, Name, NamespaceURI) cria um elemento de modelo desanexado cujo nome local XML é ClassName, com um atributo XFA name opcional e uma declaração explícita de namespace default

CreateElement valida sintaxe XML, valores escalares, namespace URIs reservados e capacidade do grafo; a factory de formulários de nível mais alto valida o schema suportado de classes XFA

Name pode ser um nome local XML ou um nome qualificado cujo prefixo não vazio tem o namespace URI não vazio fornecido; os bindings reservados xml e xmlns são validados

Um nome vazio é permitido para uma etapa de construção desanexada; defina um nome válido com Rename antes da anexação

Clone(Node, Recursive = True) cria uma cópia desanexada com identidades nativas frescas; uma cópia rasa mantém o valor, os atributos e as declarações de namespaces do próprio elemento, enquanto exclui os nós filhos

Declarações herdadas de namespaces são materializadas antes de um clone ou move, para que atributos com prefixo retêm o namespace original deles fora do escopo de ancestral anterior deles

Edições de posse

Append(Parent, Node) move o mesmo nó para o fim dos filhos ordenados do pai; InsertBefore(Parent, Node, Before) move-o antes de um filho direto existente, com Before = nil equivalendo a append

Remove(Parent, Node) desanexa o filho direto existente e transfere a posse dele ao grafo; o objeto, os descendentes e as identidades nativas permanecem válidos até a destruição do grafo ou a restauração de snapshots desanexados

Grafos estrangeiros, ciclos, mover a raiz emprestada, anexação sem nome, referências inválidas de irmãos e overflow de nós/profundidade/bytes disparam EHPDFXFAError

Edições de valores e nomes

Rename(Node, Name) muda o nome local XML do elemento, retendo o prefixo, o namespace URI, a posição, os descendentes e a identidade nativa dele; um elemento anexado exige um nome XML válido não vazio

SetValue(Node, Value) valida valores escalares UTF-8 e XML, substitui filhos comuns de texto e preserva comentários e processing instructions; texto vazio remove os filhos comuns de texto

SetAttribute(Node, Name, Value) adiciona ou substitui um atributo depois de validar a sintaxe do nome qualificado dele, o valor UTF-8 e o orçamento projetado de bytes; um valor vazio permanece um atributo explicitamente vazio

SetNamespace(Node, NamespaceURI) muda o namespace expandido do elemento e atualiza a declaração para o prefixo atual dele, validando os bindings reservados

DeclareNamespace(Node, Prefix, NamespaceURI) adiciona ou substitui uma declaração de namespace sem mudar o nome expandido do elemento; ela rejeita uma declaração conflitante para o prefixo do próprio elemento

Chamadores diretos do grafo coordenam atributos com prefixo com as declarações de namespaces deles e mantêm edições compostas dentro da própria transação de rollback deles

Os orçamentos de bytes e nós incluem o valor agregado do elemento e o nó de texto real próprio dele, em vez de cobrar apenas uma representação do texto

Preflight de import XML

ValidateImport(Node, Incoming, Overwrite, OnTick) checa o grafo agregado projetado antes de o chamador importar uma lista própria de filhos XML de entrada

Quando Overwrite é true, o tamanho projetado exclui os filhos substituídos do alvo e o valor agregado dele; caso contrário, os filhos existentes permanecem no orçamento

O método deixa a lista de entrada e o documento inalterados e cria um escopo temporário de operações apenas quando nenhum escopo já está ativo

Snapshots desanexados

CaptureDetached retorna um snapshot de valores de toda raiz e descendente desanexados, incluindo texto, CDATA, comentários, processing instructions, atributos e declarações de namespaces

RestoreDetached(Snapshot) valida e prepara uma floresta desanexada de substituição antes de trocar a posse; o array de nós retornado por ela segue a ordem do snapshot e contém identidades nativas frescas para remapeamento pelo chamador

Veja TXFADataStructureSnapshot para os campos dos records e as regras de identidades

Inspeção

Root expõe a raiz emprestada e DetachedRoots expõe as raízes de posse do grafo para inspeção; use os métodos do grafo para mudanças, de modo que posse e orçamentos permaneçam coerentes

Scripting transacional do Data DOM · Scripting transacional da tree de formulários · TXFANode