XFA choice item scripting
Unit: HPDFXFARuntime
Een veld met ui.choiceList legt choice-item-methodes bloot tijdens native JavaScript- en FormCalc-event-executie, inclusief herhaalde veld-instances en door script-objecten vastgehouden aliassen
Methodes en properties
| Lid | Gedrag |
|---|---|
length | Read-only aantal huidige export-items |
selectedIndex | Eerste geselecteerde zero-based index, of -1 wanneer niets is geselecteerd; een negatieve integer toewijzen wist de selectie, terwijl een out-of-range niet-negatieve waarde of niet-integer gooit voordat hij wordt gewijzigd |
getDisplayItem(index) | Display-tekst op de index, of null wanneer de index ongeldig is |
getSaveItem(index) | Export-tekst op de index, of null wanneer de index ongeldig is |
boundItem(display) | Export-tekst voor de eerst exact matchende display-tekst, of null wanneer geen display-tekst matcht |
getItemState(index) | Of het item is geselecteerd; een ongeldige index gooit |
setItemState(index, selected) | Werk de selectie van het item bij; een item selecteren vervangt de vorige selectie voor een single-select-veld en behoudt andere geselecteerde indices voor een multi-select-veld |
addItem(display, bound) | Voeg een item toe zonder de bestaande geselecteerde items te wijzigen; het tweede argument weglaten gebruikt een lege export-string |
deleteItem(index) | Verwijder een item en schuif latere indices op met behoud van de identiteit van overlevende item-aliassen; geef false terug voor een ongeldige index |
clearItems() | Verwijder huidige items en wis de selectie; een expliciet lege runtime-lijst blijft leeg na save en reload |
setItems(text, columns) | Vervang huidige items vanuit kommagescheiden kolommen en wis de selectie; columns defaultt naar 1, een één-koloms-rij levert zowel display- als export-tekst, en een langere rij gebruikt diens eerste kolom als display-tekst en laatste kolom als export-tekst; geef false terug wanneer het kolomaantal ongeldig is of het invoerveld-aantal niet deelt |
Indices zijn integers en worden nooit uit strings gecoerced; item-methodes vragen diens gedocumenteerde argumentaantallen, waarbij het optionele tweede argument door addItem en setItems wordt geaccepteerd
Item-waarden behouden Unicode, leading en trailing spaties, expliciet lege exports en regeleindes; ongeldige XMLcontroletekens en ongepaarde UTF-16-surrogaten worden geweigerd vóór lijstmutatie
Directe status en aliassen
Nieuwe items zijn direct zichtbaar via item-methodes en de property DOM, en een verwijderd item-alias kan niet omleiden naar een overlevend item dat naar de verwijderde index schuift
De lijst vervangen of wissen creëert distincte vervangings-identiteiten; vastgehouden script-object-aliassen naar verwijderde items falen bij latere reads en writes, terwijl overlevende aliassen hetzelfde item blijven aanspreken over event-executies heen
Een directe rawValue-toewijzing, gebonden Data DOM-write, publieke widget-waarde-commit of export-item-scalar-mutatie invalideert gecachte expliciete indices, inclusief toewijzingen die dezelfde raw string behouden
Persistentie en exacte selectie
SaveToBytes schrijft de echte per-instance formulieritems en gesynchroniseerde waarden; een herhaalde instance wijzigen behoudt andere instances en diens data-scopes
Dubbele en lege exports kunnen via exacte indices worden geselecteerd door de item-API; het opgeslagen formulierveld registreert de canonieke indices en matchende raw waarde in optionele attributes in de urn:hotpdf:xfa:runtime-namespace
Standaard XFA-items en -waardenodes blijven onafhankelijk van deze optionele attributes aanwezig; latere waarde-writes invalideren de attributes zodat verouderde indices niet de verkeerde dubbele export kunnen selecteren
De native PDF-consumer schrijft matchende /Opt export/display-paren, exacte /I-indices en /V-strings of -arrays, en bouwt appearances vanuit de geselecteerde display-labels
Transacties en limieten
Itemwijzigingen doen mee aan de bestaande event-transactie en het script-journal; een native waardelimiet-falen, annulering door de aanroeper of onafgehandelde event-exception herstelt opgeslagen XDP, script-lexicale status en bindings vóór een latere retry
Node-allocaties, invoerkolommen, UTF-8-waarden, XML-operatie-payloads, native property-traversal en klonen behouden de geconfigureerde script- en runtime-budgetten en annuleringschecks
Voorbeeld
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");Voor FormCalc-variabelen die een veld vasthouden in plaats van diens scalar-waarde, gebruik var list = Ref($.parent.choice) vóór het aanroepen van item-methodes
De methode-vocabulaire en kolomargumenten volgen de Adobe Designer Scripting Reference; de runtime gebruikt vervanging-semantics voor setItems, zoals beschreven in Adobe's HTML5 forms scripting support