Clase TXFADataStructure

TXFADataStructure, declarado en HPDFXFADataStructure, mantiene ediciones estructuradas acotadas sobre un Data DOM nativo XFA existente y es propietario de los árboles de elementos separados creados, clonados o eliminados a través del grafo

CreateDataNode sirve a los elementos del Data DOM, mientras que CreateElement también soporta la construcción de elementos de modelo usada por TXFAFormStructure

El constructor toma prestado Root y valida el árbol existente contra TXFADataStructureLimits antes de devolver; el grafo debe destruirse antes que el propietario del root prestado

Todos los nombres, URIs de namespace y valores de texto AnsiString públicos contienen 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;

Alcance de la operación

BeginOperation(OnTick) inicia un scope y rechaza un scope anidado; EndOperation libera el callback almacenado y es seguro durante la limpieza

El constructor ejecuta su propio scope de preflight y libera el callback del constructor antes de devolver; los métodos posteriores exigen un nuevo scope activo

OnTick es una anonymous procedure de Delphi o una nested procedure de FPC del tipo TXFADataStructureTick; puede lanzar una excepción para cancelar el trabajo o aplicar un deadline del llamador o un contador de operaciones

Los métodos preparan asignaciones, capacidad de propiedad y las declaraciones de namespace requeridas antes de su comprobación final de cancelación y mutación estructural; una edición individual rechazada preserva el grafo existente del documento

Una serie de llamadas directas exitosas al grafo no se revierte automáticamente cuando una llamada posterior falla; el runtime de scripting suministra la transacción completa del evento y restaura juntos su documento, grafo separado, identidades de scripts, estado léxico y journal

Creación y clonado

CreateDataNode(ClassName, Name, NamespaceURI = '') acepta dataGroup o dataValue, crea un elemento separado fresco y registra metadatos explícitos de clase de data-node

CreateElement(ClassName, Name, NamespaceURI) crea un elemento de modelo separado cuyo nombre local XML es ClassName, con un atributo name de XFA opcional y una declaración de namespace predeterminado explícita

CreateElement valida la sintaxis XML, los valores escalares, los URIs de namespace reservados y la capacidad del grafo; la fábrica de formularios de nivel superior valida el esquema de clases XFA soportado

Name puede ser un nombre local XML o un nombre calificado cuyo prefijo no vacío tiene el URI de namespace no vacío suministrado; los bindings reservados xml y xmlns se validan

Se permite un nombre vacío para un paso de construcción separado; establezca un nombre válido con Rename antes de adjuntar

Clone(Node, Recursive = True) crea una copia separada con identidades nativas frescas; una copia shallow conserva el propio valor del elemento, sus atributos y declaraciones de namespace excluyendo los nodos hijos

Las declaraciones de namespace heredadas se materializan antes de un clone o move para que los atributos con prefijo retengan su namespace original fuera de su scope de ancestro previo

Ediciones de propiedad

Append(Parent, Node) mueve el mismo nodo al final de los hijos ordenados del padre; InsertBefore(Parent, Node, Before) lo mueve antes de un hijo directo existente, con Before = nil equivalente a append

Remove(Parent, Node) separa el hijo directo existente y transfiere su propiedad al grafo; el objeto, los descendientes y las identidades nativas permanecen válidos hasta la destrucción del grafo o la restauración de snapshots separados

Grafos ajenos, ciclos, mover el root prestado, adjuntar sin nombre, referencias de hermanos inválidas y overflow de nodo/profundidad/bytes lanzan EHPDFXFAError

Ediciones de valores y nombres

Rename(Node, Name) cambia el nombre local XML del elemento reteniendo su prefijo, URI de namespace, posición, descendientes e identidad nativa; un elemento adjunto exige un nombre XML válido no vacío

SetValue(Node, Value) valida valores escalares UTF-8 y XML, reemplaza los hijos de texto ordinario y preserva comentarios e instrucciones de procesamiento; el texto vacío elimina los hijos de texto ordinario

SetAttribute(Node, Name, Value) añade o reemplaza un atributo después de validar su sintaxis de nombre calificado, valor UTF-8 y presupuesto proyectado de bytes; un valor vacío sigue siendo un atributo vacío explícito

SetNamespace(Node, NamespaceURI) cambia el namespace expandido del elemento y actualiza la declaración de su prefijo actual, validando los bindings reservados

DeclareNamespace(Node, Prefix, NamespaceURI) añade o reemplaza una declaración de namespace sin cambiar el nombre expandido del elemento; rechaza una declaración en conflicto para el prefijo del propio elemento

Los callers directos del grafo coordinan los atributos con prefijo con sus declaraciones de namespace y mantienen las ediciones compuestas dentro de su propia transacción de rollback

Los presupuestos de bytes y nodos incluyen el valor agregado del elemento y su nodo de texto propio real, en lugar de cobrar solo una representación del texto

Preflight de importación XML

ValidateImport(Node, Incoming, Overwrite, OnTick) comprueba el grafo agregado proyectado antes de que el llamador importe una lista propia de hijos XML entrantes

Cuando Overwrite es true, el tamaño proyectado excluye los hijos reemplazados del objetivo y su valor agregado; de lo contrario los hijos existentes permanecen en el presupuesto

El método deja la lista entrante y el documento sin cambios y crea un scope de operación temporal solo cuando no hay ningún scope ya activo

Snapshots separados

CaptureDetached devuelve un snapshot de valor de cada root y descendiente separado, incluyendo texto, CDATA, comentarios, instrucciones de procesamiento, atributos y declaraciones de namespace

RestoreDetached(Snapshot) valida y prepara un bosque separado de reemplazo antes de intercambiar la propiedad; su array de nodos devuelto sigue el orden del snapshot y contiene identidades nativas frescas para el remapeo del llamador

Vea TXFADataStructureSnapshot para los campos del record y las reglas de identidad

Inspección

Root expone el root prestado y DetachedRoots expone los roots propiedad del grafo para inspección; use los métodos del grafo para los cambios de modo que la propiedad y los presupuestos permanezcan coherentes

Scripting transaccional del Data DOM · Scripting transaccional del árbol de formularios · TXFANode