Scripting de choice items en XFA
Unit: HPDFXFARuntime
Un campo con ui.choiceList expone métodos de choice item durante la ejecución nativa de eventos JavaScript y FormCalc, incluidas instancias repetidas de campo y aliases retenidos por script objects
Métodos y propiedades
| Member | Behavior |
|---|---|
length | Número de solo lectura de los export items actuales |
selectedIndex | Primer índice seleccionado en base cero, o -1 cuando no hay ninguno; asignar cualquier entero negativo limpia la selección, mientras que un valor no negativo fuera de rango o no entero lanza antes de cambiarla |
getDisplayItem(index) | Texto de display en el índice, o null cuando el índice es inválido |
getSaveItem(index) | Texto de export en el índice, o null cuando el índice es inválido |
boundItem(display) | Texto de export del primer texto de display que coincida exactamente, o null cuando ninguno coincide |
getItemState(index) | Si el ítem está seleccionado; un índice inválido lanza |
setItemState(index, selected) | Actualiza la selección del ítem; seleccionar un ítem reemplaza la selección previa en un campo de selección única y preserva los demás índices seleccionados en uno multiselección |
addItem(display, bound) | Agrega un ítem sin cambiar los ítems seleccionados existentes; omitir el segundo argumento usa una cadena de export vacía |
deleteItem(index) | Borra un ítem y desplaza los índices posteriores reteniendo la identidad de los aliases de ítem que sobreviven; devuelve false para un índice inválido |
clearItems() | Quita los ítems actuales y limpia la selección; una lista runtime explícitamente vacía permanece vacía tras guardar y recargar |
setItems(text, columns) | Reemplaza los ítems actuales a partir de columnas separadas por comas y limpia la selección; columns es 1 por defecto, una fila de una columna provee tanto el texto de display como el de export, y una fila más larga usa su primera columna como display y su última como export; devuelve false si el conteo de columnas es inválido o no divide el conteo de campos de entrada |
Los índices son enteros y jamás se coercionan desde cadenas; los métodos de ítem exigen sus conteos de argumentos documentados, con el segundo argumento opcional aceptado por addItem y setItems
Los valores de ítem preservan Unicode, espacios al inicio y al final, exports vacíos explícitos y saltos de línea; los caracteres de control XML inválidos y los suplentes UTF-16 huérfanos se rechazan antes de mutar la lista
Estado inmediato y aliases
Los ítems nuevos son visibles de inmediato a través de los métodos de ítem y del property DOM, y un alias de ítem borrado no puede redirigir a un ítem superviviente que se mueva al índice borrado
Reemplazar o limpiar la lista crea identidades de reemplazo distintas; los aliases de script object retenidos hacia ítems quitados fallan en lecturas y escrituras posteriores, mientras que los aliases supervivientes siguen apuntando al mismo ítem a través de las ejecuciones de eventos
Una asignación directa de rawValue, una escritura al Data DOM, un commit público del valor del widget o una mutación escalar de un export item invalida los índices explícitos cacheados, incluidas las asignaciones que preservan la misma cadena raw
Persistencia y selección exacta
SaveToBytes escribe los ítems de formulario reales por instancia y los valores sincronizados; modificar una instancia repetida preserva las demás instancias y sus data scopes
Los exports duplicados y vacíos se pueden seleccionar por índices exactos a través de la API de ítems; el campo de formulario guardado registra los índices canónicos y el raw value coincidente en atributos opcionales del namespace urn:hotpdf:xfa:runtime
Los ítems y nodos de valor XFA estándar siguen presentes independientemente de esos atributos opcionales; las escrituras de valor posteriores invalidan los atributos para que índices vencidos no puedan seleccionar el export duplicado equivocado
El consumidor nativo de PDF escribe pares /Opt de export/display que coinciden, índices /I exactos y cadenas o arrays /V, y construye las apariencias a partir de las etiquetas de display seleccionadas
Transacciones y límites
Los cambios de ítem participan de la transacción de eventos y del script journal existentes; una falla de límite de valor nativa, una cancelación del llamador o una excepción de evento no manejada restauran el XDP guardado, el estado léxico del script y los bindings antes de un reintento posterior
Las asignaciones de nodos, las columnas de entrada, los valores UTF-8, los payloads de operaciones XML, el recorrido de propiedades nativo y el cloning retienen los presupuestos configurados de script y runtime y los checks de cancelación
Ejemplo
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");Para variables FormCalc que retienen un campo en vez de su valor escalar, usa var list = Ref($.parent.choice) antes de llamar a los métodos de ítem
El vocabulario de métodos y los argumentos de columnas siguen la Adobe Designer Scripting Reference; el runtime usa semántica de reemplazo para setItems, como describe el soporte de scripting de formularios HTML5 de Adobe