Scripting degli item di choice XFA
Unità: HPDFXFARuntime
Un campo con ui.choiceList espone i metodi sugli item di choice durante l'esecuzione di eventi JavaScript e FormCalc nativi, incluse le istanze ripetute del campo e gli alias conservati dagli script object
Metodi e proprietà
| Membro | Comportamento |
|---|---|
length | Numero read-only degli item export correnti |
selectedIndex | Primo indice selezionato a base zero, oppure -1 quando nessuno è selezionato; assegnare qualsiasi intero negativo azzera la selezione, mentre un valore non negativo fuori range o non intero solleva un'eccezione prima di cambiarlo |
getDisplayItem(index) | Testo di display all'indice, oppure null quando l'indice non è valido |
getSaveItem(index) | Testo export all'indice, oppure null quando l'indice non è valido |
boundItem(display) | Testo export per il primo testo di display con corrispondenza esatta, oppure null quando nessun testo di display corrisponde |
getItemState(index) | Se l'item è selezionato; un indice non valido solleva un'eccezione |
setItemState(index, selected) | Aggiorna la selezione dell'item; selezionare un item sostituisce la selezione precedente in un campo single-select e preserva gli altri indici selezionati in un campo multi-select |
addItem(display, bound) | Aggiunge un item senza cambiare gli item selezionati esistenti; omettere il secondo argomento usa una stringa export vuota |
deleteItem(index) | Elimina un item e sposta gli indici successivi conservando l'identità degli alias sopravvissuti; restituisce false per un indice non valido |
clearItems() | Rimuove gli item correnti e azzera la selezione; una lista runtime esplicitamente vuota resta vuota dopo save e reload |
setItems(text, columns) | Sostituisce gli item correnti da colonne separate da virgole e azzera la selezione; columns fa default a 1, una riga a una colonna fornisce sia il testo di display sia quello export, e una riga più lunga usa la prima colonna come testo di display e l'ultima come testo export; restituisce false se il numero di colonne non è valido o non divide il numero di campi in input |
Gli indici sono interi e non vengono mai forzati da stringhe; i metodi sugli item richiedono il numero di argomenti documentato, con il secondo argomento opzionale accettato da addItem e setItems
I valori degli item preservano Unicode, spazi iniziali e finali, export vuoti espliciti e interruzioni di riga; i caratteri di controllo XML non validi e le surrogate UTF-16 non appaiate vengono rifiutati prima della mutazione della lista
Stato immediato e alias
I nuovi item sono immediatamente visibili attraverso i metodi sugli item e il property DOM, e un alias a un item eliminato non può reindirizzare a un item sopravvissuto che si sposta nell'indice eliminato
Sostituire o azzerare la lista crea identità di sostituzione distinte; gli alias conservati dagli script object verso item rimossi falliscono nelle letture e scritture successive, mentre gli alias sopravvissuti continuano a puntare allo stesso item attraverso le esecuzioni degli eventi
Un'assegnazione diretta a rawValue, una scrittura sul Data DOM in binding, un commit pubblico del valore del widget o una mutazione scalare di un item export invalida gli indici espliciti in cache, incluse le assegnazioni che preservano la stessa stringa raw
Persistenza e selezione esatta
SaveToBytes scrive gli item del form per istanza e i valori sincronizzati reali; modificare un'istanza ripetuta preserva le altre istanze e i loro scope dati
Export duplicati e vuoti possono essere selezionati per indici esatti tramite la API sugli item; il campo del form salvato registra gli indici canonici e il valore raw corrispondente in attributi opzionali nel namespace urn:hotpdf:xfa:runtime
Gli item XFA standard e i nodi valore restano presenti indipendentemente da questi attributi opzionali; le scritture di valore successive invalidano gli attributi così che indici stallo non possano selezionare l'export duplicato sbagliato
Il consumer PDF nativo scrive coppie /Opt export/display corrispondenti, indici /I esatti e stringhe o array /V, e costruisce le appearance a partire dalle etichette di display selezionate
Transazioni e limiti
Le modifiche agli item partecipano alla transazione di evento e allo journal degli script esistenti; un fallimento del limite di valori nativo, una cancellazione del chiamante o un'eccezione di evento non gestita ripristinano l'XDP salvato, lo stato lessicale degli script e i binding prima di un retry successivo
Le allocazioni dei nodi, le colonne in input, i valori UTF-8, i payload delle operazioni XML, l'attraversamento e il cloning delle proprietà native conservano i budget configurati di script e runtime e i controlli di cancellazione
Esempio
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");Per le variabili FormCalc che conservano un campo invece del suo valore scalare, usare var list = Ref($.parent.choice) prima di chiamare i metodi sugli item
Il vocabolario dei metodi e gli argomenti a colonne seguono l'Adobe Designer Scripting Reference; il runtime usa la semantica di sostituzione per setItems, come descritto nel supporto allo scripting dei form HTML5 di Adobe