XFA choice item scripting
Unit: HPDFXFARuntime
Pole s ui.choiceList vystavuje metody položek volby během nativního provedení JavaScript i FormCalc událostí, tedy i opakované instanční pole a aliasy držené skriptovými objekty
Metody a vlastnosti
| Člen | Chování |
|---|---|
length | Read-only počet aktuálních exportních položek |
selectedIndex | První vybraný zero-based index, či -1, když nic není vybrané; přiřazení jakéhokoli záporného celého čísla výběr vymaže, zatímco mimo rozsah ležící nezáporná hodnota či necelé číslo hodí výjimku, dřív než ho změní |
getDisplayItem(index) | Display text na indexu, či null při neplatném indexu |
getSaveItem(index) | Exportní text na indexu, či null při neplatném indexu |
boundItem(display) | Exportní text pro první přesně odpovídající display text, či null, když se žádný netrefí |
getItemState(index) | Zda je položka vybraná; neplatný index hodí výjimku |
setItemState(index, selected) | Aktualizuje výběr položky; vybrání položky nahradí předchozí výběr u pole s jedním výběrem a zachová ostatní vybrané indexy u pole s vícenásobným výběrem |
addItem(display, bound) | Připojí položku, aniž by změnila stávající vybrané položky; vynechání druhého argumentu použije prázdný exportní řetězec |
deleteItem(index) | Smaže položku a posune pozdější indexy, při zachování identity aliasů přeživších položek; pro neplatný index vrátí false |
clearItems() | Odstraní aktuální položky a vymaže výběr; explicitně prázdný runtime seznam zůstane po uložení i reloadu prázdný |
setItems(text, columns) | Nahradí aktuální položky z čárkou oddělených sloupců a vymaže výběr; columns defaultuje na 1, jedno sloupcový řádek dodá display i exportní text a delší řádek použije první sloupec jako display text a poslední jako exportní text; vrátí false, když je počet sloupců neplatný či nedělí počet vstupních polí |
Indexy jsou celá čísla a nikdy se nepřetypovávají z řetězců; metody položek vyžadují své zdokumentované počty argumentů, přičemž volitelný druhý argument přijímají addItem a setItems
Hodnoty položek zachovávají Unicode, úvodní i závěrečné mezery, explicitně prázdné exporty i konce řádků; neplatné XML řídicí znaky i nespárované UTF-16 surrogáty se odmítnou, dřív než mutace seznamu
Okamžitý stav a aliasy
Nové položky jsou hned viditelné přes metody položek i property DOM a alias smazané položky se nemůže přesměrovat na přeživší položku, která se přesune na smazaný index
Náhrada či vymazání seznamu vytvoří odlišné náhradní identity; držené aliasy skriptových objektů na odebrané položky selžou při pozdějších čteních i zápisech, zatímco přeživší aliasy dál adresují tutéž položku napříč provedeními událostí
Přímé přiřazení rawValue, navázaný zápis Data DOM, veřejný commit hodnoty widgetu či skalární mutace exportní položky zneplatní cacheované explicitní indexy, tedy i přiřazení zachovávající tutéž surovou hodnotu
Perzistence a přesný výběr
SaveToBytes zapíše skutečné per-instance formulářové položky i synchronizované hodnoty; úprava opakované instance zachová jiné instance i jejich datové scopy
Duplicitní i prázdné exporty se dají vybrat přesnými indexy přes API položek; uložené form pole zaznamená kanonické indexy i odpovídající surovou hodnotu ve volitelných atributech v namespace urn:hotpdf:xfa:runtime
Standardní XFA položky i value uzly zůstávají přítomné nezávisle na těch volitelných atributech; pozdější zápisy hodnot atributy zneplatní, takže zastaralé indexy nemohou vybrat špatný duplicitní export
Nativní PDF konzument zapíše odpovídající páry export/display /Opt, přesné indexy /I a řetězce či pole /V a postaví appearance z vybraných display popisků
Transakce a limity
Změny položek se účastní stávající transakce událostí i skriptového journalu; nativní selhání hodnotového limitu, zrušení volajícího či nezpracovaná výjimka události obnoví uložené XDP, skriptový lexický stav i bindingy, dřív než pozdější retry
Alokace uzlů, vstupní sloupce, UTF-8 hodnoty, XML payloady operací, nativní property traversal i klonování si uchovávají nakonfigurované rozpočty skriptů i runtime a kontroly zrušení
Příklad
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");U FormCalc proměnných držících pole, nikoli jeho skalární hodnotu, použijte var list = Ref($.parent.choice), dřív než zavoláte metody položek
Slovník metod i sloupcové argumenty řídí Adobe Designer Scripting Reference; runtime použije náhradní sémantiku u setItems, jak popisuje podpora skriptování HTML5 formulářů od Adobe