XFA choice item-scripting
Unit: HPDFXFARuntime
Et felt med ui.choiceList udstiller choice item-metoder under native JavaScript- og FormCalc-event-afvikling, inklusive gentagne felt-instances og aliasser tilbageholdt af script-objekter
Metoder og properties
| Member | Adfærd |
|---|---|
length | Skrivebeskyttet antal aktuelle export-items |
selectedIndex | Første valgte nul-baserede indeks eller -1, når intet er valgt; tildeling af et negativt heltal rydder markeringen, mens en værdi uden for intervallet eller ikke-heltal kaster, før den ændres |
getDisplayItem(index) | Display-tekst ved indekset eller null, når indekset er ugyldigt |
getSaveItem(index) | Export-tekst ved indekset eller null, når indekset er ugyldigt |
boundItem(display) | Export-tekst for den første eksakt matchende display-tekst eller null, når ingen display-tekst matcher |
getItemState(index) | Om itemet er valgt; et ugyldigt indeks kaster |
setItemState(index, selected) | Opdater itemets markering; at vælge et item erstatter den tidligere markering for et single-select-felt og beholder andre valgte indeks for et multi-select-felt |
addItem(display, bound) | Tilføj et item uden at ændre de eksisterende valgte items; udeladelse af det andet argument bruger en tom export-streng |
deleteItem(index) | Slet et item og flyt senere indeks, mens overlevende item-aliasers identitet beholder; returnér false for et ugyldigt indeks |
clearItems() | Fjern aktuelle items og ryd markering; en eksplicit tom runtime-liste forbliver tom efter gemning og genindlæsning |
setItems(text, columns) | Erstat aktuelle items fra kommaseparerede kolonner og ryd markering; columns er som standard 1, en ét-kolonne-række leverer både display- og export-tekst, og en længere række bruger sin første kolonne som display-tekst og sidste kolonne som export-tekst; returnér false, hvis kolonneantallet er ugyldigt eller ikke dividerer inputfelt-antallet |
Indeks er heltal og coerces aldrig fra strenge; item-metoder kræver deres dokumenterede argumentantal, med det valgfrie andet argument accepteret af addItem og setItems
Item-værdier bevarer Unicode, førende og afsluttende mellemrum, eksplicitte tomme exports og linjeskift; ugyldige XML kontroltegn og uparede UTF-16 surrogater afvises inden listemutation
Øjeblikkelig tilstand og aliasser
Nye items er straks synlige gennem item-metoder og property-DOM'en, og et slettet item-alias kan ikke omdirigere til et overlevende item, der flytter ind i det slettede indeks
At erstatte eller rydde listen skaber distinkte erstatnings-identiteter; tilbageholdte script-object-aliasser til fjernede items fejler ved senere læsninger og skrivninger, mens overlevende aliasser fortsætter med at adressere samme item på tværs af event-afviklinger
En direkte rawValue-tildeling, bundet Data DOM-skrivning, public widget værdi-commit eller export-item scalar-mutation invaliderer cachede eksplicitte indeks, inklusive tildelinger der bevarer samme rå streng
Persistens og eksakt markering
SaveToBytes skriver de faktiske per-instance formulare-items og synkroniserede værdier; at modificere en gentaget instance bevarer andre instances og deres data-scopes
Duplikerede og tomme exports kan vælges efter eksakte indeks gennem item-API'en; det gemte formularfelt registrerer de kanoniske indeks og matchende rå værdi i valgfrie attributter i urn:hotpdf:xfa:runtime-namespacet
Standard XFA items og value-noder forbliver til stede uafhængigt af disse valgfrie attributter; senere værdiskrivninger invaliderer attributterne, så forældede indeks ikke kan vælge den forkerte duplikerede export
Den native PDF-consumer skriver matchende /Opt export/display-par, eksakte /I-indeks og /V-strenge eller -arrays og bygger appearances ud fra de valgte display-labels
Transaktioner og grænser
Item-ændringer deltager i den eksisterende event-transaktion og script-journal; en native værdigrænse-fejl, kalder-cancellation eller ubehandlet event-exception gendanner gemt XDP, script leksikalsk tilstand og bindinger inden et senere retry
Node-allokeringer, inputkolonner, UTF-8-værdier, XML operations-payloads, native property-traversal og kloning beholder de konfigurerede script- og runtime-budgetter samt cancellation-tjek
Eksempel
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");Til FormCalc-variabler, der beholder et felt snarere end dets scalar-værdi, brug var list = Ref($.parent.choice) før item-metoderne kaldes
Metodeordforrådet og kolonneargumenterne følger Adobe Designer Scripting Reference; runtime'en bruger erstatningssemantik for setItems som beskrevet i Adobes HTML5 forms scripting support