XFA 宿主模型

啟用 TXFAWidgetRuntimeOptions.ScriptOptions.EnableJavaScript,即可透過隨附的 QuickJS 引擎使用有狀態的 xfa.host 模型

在建立執行環境前,先透過 TXFAWidgetRuntimeOptions.HostModel 設定應用程式中繼資料,並透過TXFAWidgetRuntime.HostModel 讀取目前狀態

屬性

屬性	行為
`name`、`version`、`appType`、`platform`、`variation`、`language`	由嵌入應用程式提供的唯讀應用程式中繼資料
`numPages`	唯讀的實際版面頁數,包括欄位 widget 之外的定位內容
`currentPage`	以零為基底的目前頁面,會對照 numPages 檢查;聚焦某欄位時會選取其所在頁面
`title`	Unicode 執行階段標題,受 MaxValueChars 限制,並隨交易一起發布
`calculationsEnabled`	控制自動計算腳本;預設為 true
`validationsEnabled`	控制已編輯值的驗證腳本;預設為 true

應用程式版本識別的是嵌入應用程式;程式庫不會以自己的版本號代替

宿主狀態屬於執行環境;標題與頁面變更不會修改原始 PDF 物件圖,也不會編碼進已儲存的 XDP 資料

導覽、焦點與資料重設

方法	行為
`pageUp()`、`pageDown()`	在頁面邊界內移動,並停在第一頁或最後一頁
`getFocus()`	回傳即時聚焦的欄位出現個體;焦點不存在、已被移除或被遮蔽時回傳 null
`setFocus(fieldOrSOM)`	對可見的即時欄位出現個體請求焦點;null 或空文字會清除焦點
`resetData(paths="")`	為逗號分隔 SOM 清單選出的欄位還原範本預設值,paths 為空時適用於所有欄位;重複執行個體數與無關的出現個體不受影響

被重設的欄位會離開編輯模式並回到有效互動狀態,避免殘留的編輯緩衝覆寫重設後的值

Reset 與 Data DOM loadXML 可以在同一個事件中執行；二者的變更共用該事件交易，腳本失敗或預算耗盡會在重試之前還原資料值、編輯緩衝、host 狀態與腳本物件詞彙狀態

當執行個體管理員重排重複子表單時,欄位識別會跟隨其資料出現個體,快照還原也會保留這些邏輯識別

焦點生命週期與交易

執行環境的焦點變更會提交並驗證待處理的來源編輯、執行來源 exit 腳本、選取新欄位,並在計算與版面塵埃落定前執行目標 enter 腳本

enter 或 exit 腳本發出的焦點請求可以改寫目標;每輪焦點處理最多允許 64 次轉移,並共用腳本操作與經過時間預算

腳本透過 xfa.event.name 看到活動;計算與驗證收到各自的 context 名稱

公開的 FocusWidget 與 enter/exit DispatchEvent 呼叫使用同一套交易式生命週期;ClearFocus 會在 exit 生命週期前取消其目前的編輯緩衝,保留既有的取消行為

OnFocusChanged 在提交後按順序發布 callback;中間的目標改寫留在交易內,而腳本、驗證或預算的失敗會一併還原宿主狀態、焦點、編輯緩衝、文件值與腳本語彙狀態

Options := TXFAWidgetRuntimeOptions.Default;
Options.ScriptOptions.EnableJavaScript := True;
Options.HostModel.Name := 'Application';
Options.HostModel.Version := '1.0';
Options.HostModel.Language := 'en-US';
Runtime := TXFAWidgetRuntime.Create(XDPBytes, 595, 842, Options);

xfa.host.title = "Order form";
xfa.host.setFocus("rows[1].quantity");
xfa.host.resetData("rows[1].quantity,rows[1].price");
xfa.host.calculationsEnabled = false;

應用程式效果與其餘涵蓋

對話框、列印、外部導覽、匯入/匯出與 HTTP 效果使用明確的應用程式宿主傳輸與已記錄回應;狀態模型本身不啟動任何 UI 或網路操作

更多宿主對話框 API、Acrobat 的每個宿主屬性、動態同步 reflow 查詢與完整的 SOM 運算子,仍是另外的整合目標