XFA 選択項目のスクリプティング

Unit: HPDFXFARuntime

ui.choiceList を持つフィールドは、ネイティブ JavaScript と FormCalc のイベント実行中に選択項目メソッドを公開します。繰り返されたフィールドインスタンスと、スクリプトオブジェクトが保持するエイリアスも含みます

メソッドとプロパティ

メンバー	動作
`length`	現在のエクスポート項目数（読み取り専用）
`selectedIndex`	選択されている最初のゼロベースインデックス、未選択なら -1。負の整数を代入すると選択がクリアされ、範囲外の非負値や非整数は変更前に例外を投げます
`getDisplayItem(index)`	そのインデックスの表示テキスト、無効なインデックスなら null
`getSaveItem(index)`	そのインデックスのエクスポートテキスト、無効なインデックスなら null
`boundItem(display)`	完全一致する最初の表示テキストのエクスポートテキスト、一致なしなら null
`getItemState(index)`	その項目が選択されているかどうか。無効なインデックスは例外を投げます
`setItemState(index, selected)`	項目の選択を更新します。単一選択フィールドでは以前の選択を置き換え、複数選択フィールドでは他の選択済みインデックスを保持します
`addItem(display, bound)`	既存の選択済み項目を変更せずに項目を追加します。第 2 引数を省略すると空のエクスポート文字列を使います
`deleteItem(index)`	項目を削除し、生き残る項目エイリアスの ID を保持したまま後続のインデックスをずらします。無効なインデックスでは false を返します
`clearItems()`	現在の項目を削除し選択をクリアします。明示的に空になった実行時リストは、保存・再ロード後も空のままです
`setItems(text, columns)`	カンマ区切りの列から現在の項目を置き換え、選択をクリアします。columns のデフォルトは 1 で、1 列の行は表示とエクスポートの両テキストを供給し、より長い行は最初の列を表示テキスト、最後の列をエクスポートテキストにします。列数が無効か入力フィールド数を割り切れない場合は false を返します

インデックスは整数で、文字列から型強制されません。項目メソッドは文書化された引数の数を要求し、オプションの第 2 引数は addItem と setItems が受け付けます

項目値は、Unicode、先頭・末尾のスペース、明示的な空エクスポート、改行を保持します。無効な XML 制御文字とペアでない UTF-16 サロゲートは、リスト変更の前に拒否されます

即時状態とエイリアス

新しい項目は、項目メソッドとプロパティ DOM を通じて即座に見えます。削除された項目のエイリアスは、削除されたインデックスへ移動した生き残り項目にリダイレクトできません

リストの置き換えやクリアは、別個の置換 ID を作ります。削除された項目への、保持されたスクリプトオブジェクトのエイリアスは後の読み書きで失敗し、生き残ったエイリアスはイベント実行をまたいで同じ項目を指し続けます

直接的な rawValue 代入、バインドされた Data DOM 書き込み、公開ウィジェット値コミット、エクスポート項目のスカラー変更は、キャッシュされた明示的インデックスを無効化します。同じ raw 文字列を保持する代入も含みます

永続化と正確な選択

SaveToBytes は、インスタンスごとの実際のフォーム項目と同期された値を書き込みます。繰り返しインスタンスの変更は、他のインスタンスとそのデータスコープを保持します

重複および空のエクスポートは、項目 API を通じて正確なインデックスで選択できます。保存されたフォームフィールドは、urn:hotpdf:xfa:runtime 名前空間のオプション属性に、正準インデックスと一致する raw 値を記録します

標準 XFA の項目と値ノードは、これらのオプション属性とは独立して存在し続けます。後の値書き込みは属性を無効化するため、陳腐化したインデックスが間違った重複エクスポートを選択できません

ネイティブ PDF コンシューマは、一致する /Opt のエクスポート・表示ペア、正確な /I インデックス、/V の文字列または配列を書き込み、選択された表示ラベルから外観を構築します

トランザクションと上限

項目の変更は、既存のイベントトランザクションとスクリプトジャーナルに参加します。ネイティブの値上限失敗、呼び出し側のキャンセル、未処理のイベント例外は、後の再試行の前に、保存された 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 に従います。ランタイムは、Adobe の HTML5 forms scripting support が記述するように、setItems に置換セマンティクスを使います