XFA choice 条目脚本

单元：HPDFXFARuntime

带 ui.choiceList 的字段在原生 JavaScript 与 FormCalc 事件执行期间暴露 choice 条目方法，包括重复字段实例和脚本对象保留的别名

方法与属性

成员	行为
`length`	当前导出条目数的只读值
`selectedIndex`	第一个选中的从零开始索引，无选中时为 -1；赋任何负整数都会清除选中，越界的非负值或非整数会在改动之前抛出
`getDisplayItem(index)`	索引处的显示文本，索引非法时为 null
`getSaveItem(index)`	索引处的导出文本，索引非法时为 null
`boundItem(display)`	第一个精确匹配显示文本的导出文本，无匹配时为 null
`getItemState(index)`	条目是否被选中；索引非法时抛出
`setItemState(index, selected)`	更新条目选中状态；单选字段选中某条目会替换先前选中，多选字段则保留其他选中索引
`addItem(display, bound)`	追加条目而不改动既有选中项；省略第二个参数时使用空导出字符串
`deleteItem(index)`	删除条目并前移后续索引，同时保留存活条目别名的身份；索引非法时返回 false
`clearItems()`	移除当前条目并清除选中；显式为空的运行时列表在保存并重新加载后仍为空
`setItems(text, columns)`	用逗号分隔的列替换当前条目并清除选中；columns 默认 1，单列行的显示与导出文本相同，更长一行用第一列作显示文本、最后一列作导出文本；列数非法或不整除输入字段数时返回 false

索引必须是整数，不会从字符串强制转换；条目方法要求文档规定的参数个数，addItem 与 setItems 可接受可选的第二个参数

条目值保留 Unicode、前后空格、显式空导出值和换行；非法 XML 控制字符和未配对 UTF-16 代理在列表变更之前被拒绝

即时状态与别名

新条目立即通过条目方法和属性 DOM 可见，被删除条目的别名不能重定向到移入被删索引的存活条目

替换或清空列表会创建不同的替换身份；指向被移除条目的脚本对象别名在后续读写时失败，而存活别名在多次事件执行间继续指向同一条目

直接的 rawValue 赋值、绑定的 Data DOM 写入、公开 widget 值提交或导出条目标量变更都会使缓存中的显式索引失效，保持相同原始字符串的赋值也不例外

持久化与精确选中

SaveToBytes 写出真实的按实例表单条目和同步值；修改重复实例不影响其他实例及其数据作用域

重复与空导出值可以通过条目 API 按精确索引选中；保存的表单字段在 urn:hotpdf:xfa:runtime 命名空间的可选属性中记录规范索引与匹配的原始值

标准 XFA 条目与值节点独立于这些可选属性存在；后续值写入会使属性失效，过期索引因此无法选中错误的重复导出值

原生 PDF 消费方写出匹配的 /Opt 导出/显示对、精确的 /I 索引和 /V 字符串或数组，并根据选中的显示标签构建外观

事务与限制

条目变更参与既有的事件事务与脚本 journal；原生值限制失败、调用方取消或未处理的事件异常会恢复已保存的 XDP、脚本词法状态和绑定，随后可重试

节点分配、输入列、UTF-8 值、XML 操作载荷、原生属性遍历和克隆保留配置的脚本与运行时预算及取消检查

示例

var list = this.parent.choice;
list.clearItems();
list.addItem("Display A", "same");
list.addItem("Display B", "same");
list.selectedIndex = 1;
if (list.getDisplayItem(list.selectedIndex) !== "Display B")
    throw new Error("Unexpected selected label");

FormCalc 变量保留字段而不是其标量值时，请先写 var list = Ref($.parent.choice) 再调用条目方法

方法词汇和列参数遵循 Adobe Designer Scripting Reference；运行时对 setItems 使用替换语义，见 Adobe 的 HTML5 forms scripting support