Scripting des éléments de choix XFA
Unité : HPDFXFARuntime
Un champ avec ui.choiceList expose les méthodes d'éléments de choix pendant l'exécution native d'événements JavaScript et FormCalc, instances de champs répétées et alias conservés par des objets script compris
Méthodes et propriétés
| Membre | Comportement |
|---|---|
length | Nombre en lecture seule des éléments d'export courants |
selectedIndex | Premier index sélectionné à base zéro, ou -1 quand rien n'est sélectionné ; affecter n'importe quel entier négatif efface la sélection, tandis qu'une valeur non négative hors plage ou non entière lève une exception avant de la modifier |
getDisplayItem(index) | Texte d'affichage à l'index, ou null quand l'index est invalide |
getSaveItem(index) | Texte d'export à l'index, ou null quand l'index est invalide |
boundItem(display) | Texte d'export du premier texte d'affichage correspondant exactement, ou null quand aucun texte d'affichage ne correspond |
getItemState(index) | Si l'élément est sélectionné ; un index invalide lève une exception |
setItemState(index, selected) | Met à jour la sélection de l'élément ; sélectionner un élément remplace la sélection précédente pour un champ mono-sélection et préserve les autres index sélectionnés pour un champ multi-sélection |
addItem(display, bound) | Ajoute un élément sans changer les éléments sélectionnés existants ; omettre le second argument utilise une chaîne d'export vide |
deleteItem(index) | Supprime un élément et décale les index suivants tout en conservant l'identité des alias d'éléments survivants ; retourne false pour un index invalide |
clearItems() | Retire les éléments courants et efface la sélection ; une liste runtime explicitement vide reste vide après enregistrement et rechargement |
setItems(text, columns) | Remplace les éléments courants depuis des colonnes séparées par des virgules et efface la sélection ; columns vaut 1 par défaut, une ligne à une colonne fournit le texte d'affichage et d'export, et une ligne plus longue utilise sa première colonne comme texte d'affichage et sa dernière colonne comme texte d'export ; retourne false si le nombre de colonnes est invalide ou ne divise pas le nombre de champs de l'entrée |
Les index sont des entiers et ne sont jamais coercés depuis des chaînes ; les méthodes d'éléments exigent leurs nombres d'arguments documentés, le second argument optionnel étant accepté par addItem et setItems
Les valeurs d'éléments préservent l'Unicode, les espaces initiaux et finaux, les exports vides explicites et les sauts de ligne ; les caractères de contrôle XML invalides et les substituts UTF-16 non appariés sont rejetés avant la mutation de la liste
État immédiat et alias
Les nouveaux éléments sont immédiatement visibles via les méthodes d'éléments et le DOM de propriétés, et un alias d'élément supprimé ne peut pas rediriger vers un élément survivant qui se déplace vers l'index supprimé
Remplacer ou vider la liste crée des identités de remplacement distinctes ; les alias d'objets script conservés vers des éléments retirés échouent aux lectures et écritures ultérieures, tandis que les alias survivants continuent d'adresser le même élément à travers les exécutions d'événements
Une affectation directe de rawValue, une écriture liée au Data DOM, une validation publique de valeur de widget ou une mutation scalaire d'élément d'export invalide les index explicites en cache, affectations préservant la même chaîne brute comprises
Persistence et sélection exacte
SaveToBytes écrit les éléments de formulaire réels par instance et les valeurs synchronisées ; modifier une instance répétée préserve les autres instances et leurs portées de données
Les exports dupliqués et vides peuvent être sélectionnés par index exacts via l'API d'éléments ; le champ de formulaire enregistré consigne les index canoniques et la valeur brute correspondante dans des attributs optionnels de l'espace de noms urn:hotpdf:xfa:runtime
Les éléments XFA standard et les nœuds de valeurs restent présents indépendamment de ces attributs optionnels ; des écritures de valeurs ultérieures invalident les attributs pour que des index périmés ne puissent pas sélectionner le mauvais export dupliqué
Le consommateur PDF natif écrit des paires /Opt export/affichage correspondantes, des index /I exacts et des chaînes ou tableaux /V, et construit les apparences depuis les étiquettes d'affichage sélectionnées
Transactions et limites
Les changements d'éléments participent à la transaction d'événement et au journal de script existants ; un échec natif de limite de valeur, une annulation par l'appelant ou une exception d'événement non gérée restaure le XDP enregistré, l'état lexical du script et les liaisons avant une nouvelle tentative
Les allocations de nœuds, les colonnes d'entrée, les valeurs UTF-8, les charges utiles d'opérations XML, la traversée native de propriétés et le clonage gardent les budgets de script et de runtime configurés ainsi que les contrôles d'annulation
Exemple
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");Pour les variables FormCalc qui conservent un champ plutôt que sa valeur scalaire, utilisez var list = Ref($.parent.choice) avant d'appeler les méthodes d'éléments
Le vocabulaire de méthodes et les arguments de colonnes suivent l'Adobe Designer Scripting Reference ; la runtime utilise une sémantique de remplacement pour setItems, comme décrit dans le support de scripting des formulaires HTML5 d'Adobe