XFA choice 項目腳本

單元：HPDFXFARuntime

帶 ui.choiceList 的欄位在原生 JavaScript 與 FormCalc 事件執行期間暴露 choice 項目方法，包含重複欄位 instance 與腳本物件保留的別名

方法與屬性

成員	行為
`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 寫出真實的按 instance 表單項目與同步值；修改重複 instance 不影響其他 instance 及其資料作用域

重複與空匯出值可以透過項目 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