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()`	返回实时聚焦的字段 occurrence，焦点缺失、被移除或被隐藏时返回 null
`setFocus(fieldOrSOM)`	对可见的实时字段 occurrence 请求焦点；null 或空文本清除焦点
`resetData(paths="")`	为逗号分隔 SOM 列表选定的字段恢复模板默认值，paths 为空时作用于全部字段；重复实例计数与无关 occurrence 保持不变

被重置的字段退出编辑模式并恢复有效的交互状态，防止残留的编辑缓冲区覆盖重置值

实例管理器重排重复 subform 时，字段标识跟随其数据 occurrence；快照恢复保留这些逻辑标识

焦点生命周期与事务

运行时焦点变化会提交并验证待定的源编辑，执行源 exit 脚本，选中新字段，并在计算与布局稳定之前执行目标 enter 脚本

由 enter 或 exit 脚本发起的焦点请求可以改写目标；每次焦点派发允许 64 次转移，并共享脚本操作与耗时预算

脚本通过 xfa.event.name 看到活动；计算与验证收到各自的上下文名

公开的 FocusWidget 和 enter/exit DispatchEvent 调用使用同一事务生命周期；ClearFocus 在 exit 生命周期前取消其当前编辑缓冲区，保留其既有取消行为

OnFocusChanged 在提交后按序发布回调；中间改写保持在事务内，脚本、验证或预算失败会一并恢复宿主状态、焦点、编辑缓冲区、文档值和脚本词法状态

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 运算符仍是独立的集成目标