Scripting de items de choice XFA
Unit: HPDFXFARuntime
Un campo con ui.choiceList expone métodos de items de choice durante la ejecución nativa de eventos JavaScript y FormCalc, incluidas las instancias repetidas de campos y los alias retenidos por script objects
Métodos y propiedades
| Miembro | Comportamiento |
|---|---|
length | Número de solo lectura de export items actuales |
selectedIndex | Primer índice seleccionado de base cero, o -1 cuando no hay selección; 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 empareje exactamente, o null cuando ningún texto de display empareja |
getItemState(index) | Si el item está seleccionado; un índice inválido lanza |
setItemState(index, selected) | Actualiza la selección del item; seleccionar un item reemplaza la selección previa en un campo de selección única y preserva los demás índices seleccionados en un campo multi-select |
addItem(display, bound) | Añade un item sin cambiar los items seleccionados existentes; omitir el segundo argumento usa una cadena de export vacía |
deleteItem(index) | Elimina un item y desplaza los índices posteriores reteniendo la identidad de los alias de items supervivientes; devuelve false para un índice inválido |
clearItems() | Elimina los items 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 items actuales a partir de columnas separadas por comas y limpia la selección; columns por defecto es 1, una fila de una columna suministra tanto display como export text, y una fila más larga usa su primera columna como display text y la última como export text; devuelve false si el recuento de columnas es inválido o no divide el recuento de campos de la entrada |
Los índices son enteros y nunca se fuerzan desde strings; los métodos de items exigen sus recuentos de argumentos documentados, con el segundo argumento opcional aceptado por addItem y setItems
Los valores de items preservan Unicode, espacios iniciales y finales, exports vacíos explícitos y saltos de línea; los caracteres de control XML inválidos y los surrogates UTF-16 sin pareja se rechazan antes de mutar la lista
Estado inmediato y alias
Los items nuevos son inmediatamente visibles a través de los métodos de items y del property DOM, y un alias de item eliminado no puede redirigir a un item superviviente que se mueva al índice eliminado
Reemplazar o limpiar la lista crea identidades de reemplazo distintas; los alias de script objects retenidos hacia items eliminados fallan en lecturas y escrituras posteriores, mientras que los alias supervivientes siguen direccionando el mismo item a través de ejecuciones de eventos
Una asignación directa de rawValue, una escritura en el Data DOM enlazado, un commit público del valor del widget o una mutación escalar de 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 form items reales por instancia y los valores sincronizados; modificar una instancia repetida preserva las demás instancias y sus ámbitos de datos
Los exports duplicados y vacíos pueden seleccionarse por índices exactos a través de la API de items; 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 items y value nodes estándar XFA permanecen presentes independientemente de estos atributos opcionales; las escrituras posteriores de valores invalidan los atributos para que los índices obsoletos no puedan seleccionar el export duplicado equivocado
El consumidor PDF nativo escribe pares /Opt export/display coincidentes, índices /I exactos y strings o arrays /V, y construye las appearances a partir de las etiquetas de display seleccionadas
Transacciones y límites
Los cambios de items participan en la transacción de eventos y el journal de scripts existentes; un fallo nativo de límite de valores, una cancelación del llamador o una excepción de evento no manejada restaura el XDP guardado, el estado léxico de scripts y los enlaces antes de un reintento posterior
Las asignaciones de nodos, las columnas de entrada, los valores UTF-8, los payloads de operaciones XML, el recorrido y clonado nativo de propiedades retienen los presupuestos configurados de scripts y runtime y las comprobaciones 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 lugar de su valor escalar, use var list = Ref($.parent.choice) antes de llamar a los métodos de items
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, según se describe en el soporte de scripting de HTML5 forms de Adobe