Класс TXFADataStructure

TXFADataStructure, объявленный в HPDFXFADataStructure, ведёт ограниченные структурные правки существующего нативного XFA Data DOM и владеет всеми отсоединёнными деревьями элементов, созданными, клонированными или удалёнными через граф

CreateDataNode обслуживает элементы Data DOM, тогда как CreateElement также поддерживает построение элементов модели, используемое TXFAFormStructure

Конструктор заимствует Root и проверяет существующее дерево против TXFADataStructureLimits перед возвратом; граф должен быть уничтожен раньше владельца заимствованного корня

Все публичные имена AnsiString, URI пространств имён и текстовые значения содержат байты 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;

Область операции

BeginOperation(OnTick) открывает scope и отвергает вложенный scope; EndOperation освобождает сохранённый колбэк и безопасен при очистке

Конструктор выполняет собственный preflight scope и освобождает колбэк конструктора перед возвратом; последующим методам нужен новый активный scope

OnTick — анонимная процедура Delphi или вложенная процедура FPC типа TXFADataStructureTick; она может выбрасывать исключение, чтобы отменить работу или соблюсти дедлайн вызывающего кода либо счётчик операций

Методы готовят выделения, ёмкость владения и требуемые объявления пространств имён до финальной проверки отмены и структурной мутации; отвергнутая одиночная правка сохраняет существующий граф документа

Серия успешных прямых вызовов графа не откатывается автоматически, если последующий вызов падает; скриптовый runtime даёт полную транзакцию события и вместе восстанавливает свой документ, отсоединённый граф, скриптовые идентификаторы, лексическое состояние и журнал

Создание и клонирование

CreateDataNode(ClassName, Name, NamespaceURI = '') принимает dataGroup или dataValue, создаёт свежий отсоединённый элемент и записывает метаданные класса data-узла явно

CreateElement(ClassName, Name, NamespaceURI) создаёт отсоединённый элемент модели, чьим локальным XML-именем является ClassName, с опциональным атрибутом name XFA и явным объявлением пространства имён по умолчанию

CreateElement проверяет XML-синтаксис, скалярные значения, зарезервированные URI пространств имён и ёмкость графа; фабрика форм верхнего уровня проверяет поддерживаемую схему классов XFA

Name может быть локальным XML-именем или квалифицированным именем, чей непустой префикс относится к переданному непустому URI пространства имён; зарезервированные привязки xml и xmlns проверяются

Пустое имя допустимо для отсоединённого шага построения; перед присоединением задайте валидное имя через Rename

Clone(Node, Recursive = True) создаёт отсоединённую копию со свежими нативными идентификаторами; мелкая копия сохраняет собственное значение элемента, атрибуты и объявления пространств имён, исключая дочерние узлы

Унаследованные объявления пространств имён материализуются до клона или перемещения, чтобы квалифицированные префиксом атрибуты сохраняли исходное пространство имён вне прежней области видимости предка

Правки владения

Append(Parent, Node) перемещает тот же узел в конец упорядоченных детей родителя; InsertBefore(Parent, Node, Before) перемещает его перед существующим прямым ребёнком, при этом Before = nil эквивалентно append

Remove(Parent, Node) отсоединяет существующего прямого ребёнка и передаёт владение им графу; объект, потомки и нативные идентификаторы остаются валидными до уничтожения графа или восстановления отсоединённого снапшота

Чужие графы, циклы, перемещение заимствованного корня, присоединение без имени, невалидные ссылки на соседей и переполнение узлов/глубины/байтов поднимают EHPDFXFAError

Правки значения и имени

Rename(Node, Name) меняет локальное XML-имя элемента, сохраняя его префикс, URI пространства имён, позицию, потомков и нативный идентификатор; присоединённому элементу требуется непустое валидное XML-имя

SetValue(Node, Value) проверяет UTF-8 и скалярные XML-значения, заменяет обычные текстовые дети и сохраняет комментарии и инструкции обработки; пустой текст удаляет обычные текстовые дети

SetAttribute(Node, Name, Value) добавляет или замещает атрибут после проверки синтаксиса квалифицированного имени, значения UTF-8 и прогнозируемого байтового бюджета; пустое значение остаётся явным пустым атрибутом

SetNamespace(Node, NamespaceURI) меняет расширенный namespace элемента и обновляет объявление его текущего префикса, проверяя зарезервированные привязки

DeclareNamespace(Node, Prefix, NamespaceURI) добавляет или замещает объявление namespace, не меняя расширенное имя элемента; она отклоняет конфликтующее объявление для собственного префикса элемента

Прямые вызывающие графа координируют атрибуты с префиксами и их объявления namespace и держат составные правки внутри собственной транзакции отката

Бюджеты байтов и узлов включают агрегированное значение элемента и его фактический собственный текстовый узел, а не начисляют только одно представление текста

XML-предполёт импорта

ValidateImport(Node, Incoming, Overwrite, OnTick) проверяет проектируемый агрегированный граф до того, как вызывающий код импортирует собственный список входящих XML-детей

Когда Overwrite истинно, проектируемый размер исключает замещаемых детей цели и агрегированное значение; иначе существующие дети остаются в бюджете

Метод оставляет входящий список и документ неизменными и создаёт временный scope операции, только если активного scope ещё нет

Отсоединённые снапшоты

CaptureDetached возвращает значимый снапшот каждого отсоединённого корня и потомка, включая текст, CDATA, комментарии, инструкции обработки, атрибуты и объявления пространств имён

RestoreDetached(Snapshot) проверяет и готовит замещающий отсоединённый лес перед обменом владением; возвращённый массив узлов следует порядку снапшота и содержит свежие нативные идентификаторы для перемаппинга вызывающим кодом

Поля записи и правила идентификаторов см. в TXFADataStructureSnapshot

Инспекция

Root открывает заимствованный корень, а DetachedRoots — корни во владении графа для инспекции; изменения выполняйте методами графа, чтобы владение и бюджеты оставались согласованными

Транзакционный скриптинг Data DOM · Транзакционный скриптинг дерева форм · TXFANode