XFA-Choice-Item-Scripting

Unit: HPDFXFARuntime

Ein Feld mit ui.choiceList exponiert Choice-Item-Methoden während der nativen JavaScript- und FormCalc-Ereignisausführung, einschließlich wiederholter Feldinstanzen und von Script-Objekten zurückgehaltener Aliasse

Methoden und Properties

Member	Verhalten
`length`	Schreibgeschützte Anzahl aktueller Export-Items
`selectedIndex`	Erster ausgewählter nullbasierter Index oder -1, wenn nichts ausgewählt ist; jede negative Ganzzahl zuweisen leert die Auswahl, während ein außerhalb liegender nichtnegativer Wert oder eine Nicht-Ganzzahl wirft, bevor sie geändert wird
`getDisplayItem(index)`	Anzeigetext am Index oder null, wenn der Index ungültig ist
`getSaveItem(index)`	Export-Text am Index oder null, wenn der Index ungültig ist
`boundItem(display)`	Export-Text für den ersten exakt passenden Anzeigetext oder null, wenn kein Anzeigetext passt
`getItemState(index)`	Ob das Item ausgewählt ist; ein ungültiger Index wirft
`setItemState(index, selected)`	Die Auswahl des Items aktualisieren; ein Item auswählen ersetzt die vorherige Auswahl bei einem Single-Select-Feld und behält andere ausgewählte Indizes bei einem Multi-Select-Feld
`addItem(display, bound)`	Ein Item anhängen, ohne die bestehenden ausgewählten Items zu ändern; das Weglassen des zweiten Arguments nutzt einen leeren Export-String
`deleteItem(index)`	Ein Item löschen und spätere Indizes verschieben, während die Identität überlebender Item-Aliasse erhalten bleibt; False für einen ungültigen Index
`clearItems()`	Aktuelle Items entfernen und Auswahl leeren; eine explizit leere Runtime-Liste bleibt nach Speichern und Neuladen leer
`setItems(text, columns)`	Aktuelle Items aus kommagetrennten Spalten ersetzen und Auswahl leeren; columns defaultet auf 1, eine Ein-Spalten-Zeile liefert Anzeige- und Export-Text, und eine längere Zeile nutzt ihre erste Spalte als Anzeigetext und letzte Spalte als Export-Text; False, wenn die Spaltenanzahl ungültig ist oder die Anzahl der Eingabefelder nicht teilt

Indizes sind Ganzzahlen und werden nie aus Strings erzwungen; Item-Methoden verlangen ihre dokumentierten Argumentanzahlen, wobei das optionale zweite Argument von addItem und setItems akzeptiert wird

Item-Werte bewahren Unicode, führende und nachfolgende Leerzeichen, explizite leere Exports und Zeilenumbrüche; ungültige XML-Steuerzeichen und ungepaarte UTF-16-Surrogate werden vor der Listenmutation abgelehnt

Sofortiger Zustand und Aliasse

Neue Items sind sofort über Item-Methoden und die Property-DOM sichtbar, und ein gelöschtes Item-Alias kann nicht auf ein überlebendes Item umleiten, das in den gelöschten Index rückt

Das Ersetzen oder Leeren der Liste erzeugt distincte Ersatzidentitäten; zurückbehaltene Script-Objekt-Aliasse zu entfernten Items schlagen bei späteren Lese- und Schreibzugriffen fehl, während überlebende Aliasse weiterhin dasselbe Item über Ereignisausführungen hinweg adressieren

Eine direkte rawValue-Zuweisung, ein gebundener Data-DOM-Schreibzugriff, ein öffentlicher Widget-Wert-Commit oder eine Export-Item-Skalar-Mutation invalidiert zwischengespeicherte explizite Indizes, einschließlich Zuweisungen, die denselben Raw-String bewahren

Persistenz und exakte Auswahl

SaveToBytes schreibt die tatsächlichen Form-Items pro Instanz und die synchronisierten Werte; das Ändern einer wiederholten Instanz bewahrt andere Instanzen und ihre Data-Scopes

Doppelte und leere Exports können über die Item-API nach exakten Indizes ausgewählt werden; das gespeicherte Formfeld hält die kanonischen Indizes und den passenden Raw-Wert in optionalen Attributen im Namespace urn:hotpdf:xfa:runtime fest

Standard-XFA-Items und Wert-Knoten bleiben unabhängig von diesen optionalen Attributen vorhanden; spätere Wert-Schreibzugriffe invalidieren die Attribute, sodass veraltete Indizes nicht den falschen doppelten Export auswählen können

Der native PDF-Consumer schreibt passende /Opt-Export-/Anzeige-Paare, exakte /I-Indizes und /V-Strings oder -Arrays und baut Appearances aus den ausgewählten Display-Labels

Transaktionen und Limits

Item-Änderungen partizipieren an der bestehenden Ereignistransaktion und am Script-Journal; ein nativer Wertlimit-Fehler, eine Aufrufer-Abbruch oder eine unbehandelte Event-Exception stellt gespeichertes XDP, den lexikalischen Script-State und die Bindings vor einer späteren Wiederholung wieder her

Node-Allokationen, Eingabespalten, UTF-8-Werte, XML-Operations-Payloads, native Property-Traversierung und Klonen behalten die konfigurierten Script- und Runtime-Budgets sowie Abbruchprüfungen bei

Beispiel

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");

Für FormCalc-Variablen, die ein Feld statt seines Skalarwerts zurückhalten, var list = Ref($.parent.choice) verwenden, bevor Item-Methoden aufgerufen werden

Der Methoden-Vokabular und die Spaltenargumente folgen der Adobe Designer Scripting Reference; die Runtime nutzt Ersetzungssemantik für setItems, wie in Adobes HTML5-Forms-Scripting-Support beschrieben