TXFADataStructure Class

TXFADataStructure, declarado en HPDFXFADataStructure, mantiene ediciones estructurales acotadas sobre un árbol de nodos XFA nativo existente y es dueño de los árboles de elementos separados creados, clonados o eliminados a través del grafo

CreateDataNode sirve para 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 de la raíz prestada

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;

Ámbito de operación

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

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

OnTick es un procedimiento anónimo Delphi o un procedimiento anidado FPC de tipo TXFADataStructureTick; puede lanzar una excepción para cancelar el trabajo o imponer un plazo del llamador o un contador de operaciones

Los métodos preparan asignaciones, capacidad de propiedad y las declaraciones de namespaces 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 de eventos 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 XFA opcional y una declaración explícita de namespace por defecto

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

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

Un nombre vacío está permitido 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 superficial conserva el valor, atributos y declaraciones de namespace del propio elemento excluyendo los nodos hijos

Las declaraciones de namespaces heredadas se materializan antes de un clone o move para que los atributos con prefijo retengan su namespace original fuera del ámbito de su 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) desprende 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 un snapshot separado

Grafos foráneos, ciclos, mover la raíz prestada, 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 ordinarios y preserva comentarios y processing instructions; el texto vacío elimina los hijos de texto ordinarios

SetAttribute(Node, Name, Value) añade o reemplaza un atributo tras validar su sintaxis de nombre cualificado, valor UTF-8 y presupuesto de bytes proyectado; un valor vacío permanece como atributo vacío explícito

SetNamespace(Node, NamespaceURI) cambia el namespace expandido del elemento y actualiza la declaración para su prefijo actual, validando los enlaces 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 conflictiva para el prefijo propio del elemento

Los llamadores directos del grafo coordinan los atributos con prefijo con sus declaraciones de namespaces 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; en caso contrario los hijos existentes permanecen en el presupuesto

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

Snapshots separados

CaptureDetached devuelve un snapshot de valor de cada raíz separada y descendiente, incluidos texto, CDATA, comentarios, processing instructions, atributos y declaraciones de namespaces

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 la raíz prestada y DetachedRoots expone las raíces 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