TXFADataStructure Class

TXFADataStructure, declarada em HPDFXFADataStructure, mantém edições estruturais delimitadas a uma árvore nativa existente de nós XFA e é dona de quaisquer árvores de elementos destacadas criadas, clonadas ou removidas através do grafo

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

O construtor toma Root emprestada e valida a árvore existente contra TXFADataStructureLimits antes de devolver; o grafo tem de ser destruído antes do proprietário da raiz emprestada

Todos os nomes públicos AnsiString, URIs de namespaces 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;

Âmbito de operações

BeginOperation(OnTick) inicia um âmbito e rejeita um âmbito aninhado; EndOperation liberta o callback guardado e é seguro durante a limpeza

O construtor corre o âmbito próprio de preflight dele e liberta o callback do construtor antes de devolver; métodos subsequentes exigem um novo âmbito ativo

OnTick é uma anonymous procedure Delphi ou uma nested procedure FPC do tipo TXFADataStructureTick; pode lançar uma exceção para cancelar trabalho ou impor um prazo de quem chama ou um contador de operações

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

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

Criação e clonagem

CreateDataNode(ClassName, Name, NamespaceURI = '') aceita dataGroup ou dataValue, cria um elemento destacado fresco e regista metadados explícitos de classes de nós de dados

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

CreateElement valida sintaxe XML, valores escalares, URIs reservados de namespaces e capacidade do grafo; a fábrica de formulários de nível superior 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 URI de namespace não vazio fornecido; bindings reservados xml e xmlns são validados

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

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

Declarações herdadas de namespaces são materializadas antes de um clone ou movimento, para que atributos com prefixo mantenham o namespace original deles fora do âmbito ancestral anterior deles

Edições de propriedade

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 equivalente a append

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

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

Edições de valores e de nomes

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

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

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

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

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

Quem chama diretamente ao grafo coordena atributos com prefixo com as declarações de namespaces deles e mantém edições compostas dentro da transação própria de rollback deles

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

Preflight de importação XML

ValidateImport(Node, Incoming, Overwrite, OnTick) verifica o grafo agregado projetado antes de quem chama 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 âmbito temporário de operações apenas quando nenhum âmbito já está ativo

Snapshots destacados

CaptureDetached devolve um snapshot de valores de todas as raízes e descendentes destacadas, incluindo texto, CDATA, comentários, processing instructions, atributos e declarações de namespaces

RestoreDetached(Snapshot) valida e prepara uma floresta destacada de substituição antes de trocar a propriedade; o array de nós devolvido por ela segue a ordem do snapshot e contém identidades nativas frescas para remapeamento de quem chama

Veja TXFADataStructureSnapshot para campos de registos e regras de identidades

Inspeção

Root expõe a raiz emprestada e DetachedRoots expõe as raízes próprias do grafo para inspeção; use métodos do grafo para alterações, para que a propriedade e os orçamentos permaneçam coerentes

Scripting transacional do Data DOM · Scripting transacional de árvores de formulários · TXFANode