Classe TXFADataStructure

TXFADataStructure, déclarée dans HPDFXFADataStructure, gère des éditions structurelles bornées d'un arbre de nœuds XFA natif existant et possède les arbres d'éléments détachés créés, clonés ou retirés via le graphe

CreateDataNode sert aux éléments du Data DOM, tandis que CreateElement prend aussi en charge la construction d'éléments de modèle utilisée par TXFAFormStructure

Le constructeur emprunte Root et valide l'arbre existant face aux TXFADataStructureLimits avant de retourner ; le graphe doit être détruit avant le propriétaire de la racine empruntée

Tous les noms, URI d'espaces de noms et valeurs de texte AnsiString publics contiennent des octets 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;

Portée d'opération

BeginOperation(OnTick) démarre une portée et rejette une portée imbriquée ; EndOperation libère le callback stocké et reste sûr pendant le nettoyage

Le constructeur exécute sa propre portée de précontrôle et libère le callback du constructeur avant de retourner ; les méthodes suivantes exigent une nouvelle portée active

OnTick est une procédure anonyme Delphi ou une procédure imbriquée FPC de type TXFADataStructureTick ; elle peut lever une exception pour annuler le travail ou imposer une échéance d'appelant ou un compteur d'opérations

Les méthodes préparent les allocations, la capacité de possession et les déclarations d'espaces de noms requises avant leur contrôle d'annulation final et leur mutation structurelle ; une édition individuelle rejetée préserve le graphe de document existant

Une série d'appels directs réussis au graphe n'est pas automatiquement annulée quand un appel ultérieur échoue ; la runtime de scripting fournit la transaction d'événement complète et restaure ensemble son document, son graphe détaché, ses identités de script, son état lexical et son journal

Création et clonage

CreateDataNode(ClassName, Name, NamespaceURI = "") accepte dataGroup ou dataValue, crée un élément détaché neuf et consigne les métadonnées explicites de classe de nœud de données

CreateElement(ClassName, Name, NamespaceURI) crée un élément de modèle détaché dont le nom local XML est ClassName, avec un attribut name XFA optionnel et une déclaration d'espace de noms par défaut explicite

CreateElement valide la syntaxe XML, les valeurs scalaires, les URI d'espaces de noms réservés et la capacité du graphe ; la fabrique de formulaires de plus haut niveau valide le schéma de classes XFA pris en charge

Name peut être un nom local XML ou un nom qualifié dont le préfixe non vide porte l'URI d'espace de noms non vide fournie ; les liaisons réservées xml et xmlns sont validées

Un nom vide est permis pour une étape de construction détachée ; définissez un nom valide avec Rename avant l'attachement

Clone(Node, Recursive = True) crée une copie détachée avec des identités natives fraîches ; une copie superficielle garde la valeur, les attributs et les déclarations d'espaces de noms propres à l'élément tout en excluant les nœuds enfants

Les déclarations d'espaces de noms héritées sont matérialisées avant un clonage ou un déplacement pour que les attributs préfixés gardent leur espace de noms d'origine hors de la portée d'ancêtre précédente

Éditions de possession

Append(Parent, Node) déplace le même nœud à la fin des enfants ordonnés du parent ; InsertBefore(Parent, Node, Before) le déplace avant un enfant direct existant, Before = nil équivalant à un ajout en fin

Remove(Parent, Node) détache l'enfant direct existant et transfère sa possession au graphe ; l'objet, les descendants et les identités natives restent valides jusqu'à la destruction du graphe ou une restauration d'instantané détaché

Graphes étrangers, cycles, déplacement de la racine empruntée, attachement sans nom, références de frères invalides et débordements de nœuds/profondeur/octets lèvent EHPDFXFAError

Éditions de valeurs et de noms

Rename(Node, Name) change le nom XML local de l'élément en conservant son préfixe, son URI d'espace de noms, sa position, ses descendants et son identité native ; un élément attaché exige un nom XML valide non vide

SetValue(Node, Value) valide les valeurs scalaires UTF-8 et XML, remplace les enfants texte ordinaires et préserve commentaires et instructions de traitement ; un texte vide retire les enfants texte ordinaires

SetAttribute(Node, Name, Value) ajoute ou remplace un attribut après validation de sa syntaxe de nom qualifié, de sa valeur UTF-8 et de son budget d'octets projeté ; une valeur vide reste un attribut vide explicite

SetNamespace(Node, NamespaceURI) change l'espace de noms étendu de l'élément et met à jour la déclaration pour son préfixe courant, tout en validant les liaisons réservées

DeclareNamespace(Node, Prefix, NamespaceURI) ajoute ou remplace une déclaration d'espace de noms sans changer le nom étendu de l'élément ; elle rejette une déclaration conflictuelle pour le préfixe propre de l'élément

Les appelants directs du graphe coordonnent les attributs préfixés avec leurs déclarations d'espaces de noms et gardent les éditions composées dans leur propre transaction d'annulation

Les budgets d'octets et de nœuds incluent la valeur agrégée de l'élément et son nœud texte réellement possédé, au lieu de ne facturer qu'une seule représentation du texte

Précontrôle d'import XML

ValidateImport(Node, Incoming, Overwrite, OnTick) vérifie le graphe agrégé projeté avant qu'un appelant n'importe une liste possédée d'enfants XML entrants

Quand Overwrite vaut true, la taille projetée exclut les enfants remplacés de la cible et sa valeur agrégée ; sinon les enfants existants restent dans le budget

La méthode laisse la liste entrante et le document inchangés et ne crée une portée d'opération temporaire que si aucune portée n'est déjà active

Instantanés détachés

CaptureDetached retourne un instantané de valeurs de chaque racine détachée et de chaque descendant, texte, CDATA, commentaires, instructions de traitement, attributs et déclarations d'espaces de noms compris

RestoreDetached(Snapshot) valide et prépare une forêt détachée de remplacement avant d'échanger la possession ; son tableau de nœuds retourné suit l'ordre de l'instantané et contient des identités natives fraîches pour le remappage par l'appelant

Voir TXFADataStructureSnapshot pour les champs du record et les règles d'identité

Inspection

Root expose la racine empruntée et DetachedRoots expose les racines possédées par le graphe pour inspection ; utilisez les méthodes du graphe pour les changements afin que possession et budgets restent cohérents

Scripting transactionnel du Data DOM · Scripting transactionnel de l'arbre de formulaire · TXFANode