TXFADataStructure Class

TXFADataStructure 宣告於 HPDFXFADataStructure,對既有的原生 XFA 節點樹維護設限的結構性編輯,並擁有經該圖建立、複製或移除的一切分離元素樹

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) 開啟一個作用域並拒絕巢狀作用域;EndOperation 釋放保存的 callback,在清理期間呼叫是安全的

建構子執行自己的預檢作用域並在回傳前釋放建構子 callback;後續方法需要新的作用中作用域

OnTick 是 Delphi 匿名程序或 FPC 的 TXFADataStructureTick 型別巢狀程序;它可以拋出例外來取消工作,或強制呼叫端時限、操作計數

各方法在最終取消檢查與結構變更之前準備配置、所有權容量與所需的命名空間宣告;單一編輯被拒絕時保留既有文件圖

一連串成功的直接圖呼叫不會在後續呼叫失敗時自動 rollback;腳本執行期提供完整的事件交易,一併還原其文件、分離圖、腳本身分、詞法狀態與 journal

建立與複製

CreateDataNode(ClassName, Name, NamespaceURI = '') 接受 dataGroup 或 dataValue,建立全新的分離元素並記錄明確的 data node 類別詮釋資料

CreateElement(ClassName, Name, NamespaceURI) 建立分離的模型元素,其 XML 本地名稱為 ClassName,帶選用的 XFA name 屬性與明確預設命名空間宣告

CreateElement 驗證 XML 語法、純量值、保留命名空間 URI 與圖容量;更高層的 form 工廠驗證受支援的 XFA 類別 schema

Name 可以是 XML 本地名稱,也可以是非空前綴對應所給非空命名空間 URI 的限定名稱;保留的 xml 與 xmlns 綁定會被驗證

分離建構步驟允許空名稱;附著前請用 Rename 設定合法名稱

Clone(Node, Recursive = True) 建立帶全新原生身分的分離副本;淺層複製保留元素自身的值、屬性與命名空間宣告,排除子節點

繼承的命名空間宣告在複製或移動之前具現化,前綴屬性在其原祖先作用域之外仍保留原命名空間

所有權編輯

Append(Parent, Node) 把同一節點移到父節點有序子節點的結尾;InsertBefore(Parent, Node, Before) 把它移到某個既有直接子節點之前,Before = nil 等價於附加

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) 改變元素展開後的命名空間,並更新其目前前綴的宣告,同時驗證保留綁定

DeclareNamespace(Node, Prefix, NamespaceURI) 新增或替換命名空間宣告而不改變元素展開名稱;元素自身前綴的衝突宣告會被拒絕

直接圖呼叫端需要協調前綴屬性與其命名空間宣告,並把複合編輯放進自己的 rollback 交易

位元組與節點預算包含元素的彙總值及其真實擁有的文字節點,而不是只對文字的一種表示計費

XML 匯入預檢

ValidateImport(Node, Incoming, Overwrite, OnTick) 在呼叫端匯入擁有的傳入 XML 子節點清單之前,檢查預計的彙總圖

Overwrite 為 true 時,預計尺寸排除目標將被替換的子節點與彙總值;否則既有子節點保留在預算內

該方法不更動傳入清單與文件,並且只在目前沒有作用中作用域時建立暫時操作作用域

分離快照

CaptureDetached 回傳所有分離根及後代的值快照,包含文字、CDATA、註解、處理指令、屬性與命名空間宣告

RestoreDetached(Snapshot) 在交換所有權之前驗證並準備替換用的分離森林;回傳的節點陣列按快照順序排列,為呼叫端重映射提供全新原生身分

記錄欄位與身分規則見 TXFADataStructureSnapshot

檢視

Root 暴露借用的根,DetachedRoots 暴露圖擁有的根供檢視;變更請使用圖方法,所有權與預算才能保持一致

交易化 Data DOM 腳本 · 交易化 form tree 腳本 · TXFANode