Scripting de choice items no XFA

Unit: HPDFXFARuntime

Um campo com ui.choiceList expõe os métodos de choice items durante a execução nativa de eventos JavaScript e FormCalc, incluindo instâncias repetidas de campos e aliases retidos por objetos de scripts

Métodos e propriedades

Membro	Comportamento
`length`	Contagem read-only de export items atuais
`selectedIndex`	Primeiro índice selecionado com base zero, ou -1 quando nenhum está selecionado; atribuir qualquer inteiro negativo limpa a seleção, enquanto um valor não negativo fora da faixa ou não inteiro lança erro antes de mudá-la
`getDisplayItem(index)`	Texto de display no índice, ou null quando o índice é inválido
`getSaveItem(index)`	Texto de export no índice, ou null quando o índice é inválido
`boundItem(display)`	Texto de export para o primeiro texto de display exatamente correspondente, ou null quando nenhum texto de display corresponde
`getItemState(index)`	Se o item está selecionado; um índice inválido lança erro
`setItemState(index, selected)`	Atualiza a seleção do item; selecionar um item substitui a seleção anterior num campo de seleção única e preserva os outros índices selecionados num campo multi-select
`addItem(display, bound)`	Anexa um item sem mudar os items selecionados existentes; omitir o segundo argument usa uma string de export vazia
`deleteItem(index)`	Exclui um item e desloca os índices posteriores, retendo a identidade dos aliases sobreviventes de items; retorna false para um índice inválido
`clearItems()`	Remove os items atuais e limpa a seleção; uma lista de runtime explicitamente vazia permanece vazia após save e reload
`setItems(text, columns)`	Substitui os items atuais a partir de colunas separadas por vírgulas e limpa a seleção; columns tem default 1, uma linha de uma coluna fornece tanto o texto de display quanto o de export, e uma linha mais longa usa a primeira coluna como display e a última como export; retorna false se a contagem de colunas é inválida ou não divide a contagem de campos da entrada

Índices são inteiros e nunca são coeridos de strings; os métodos de items exigem as contagens documentadas de arguments, com o segundo argument opcional aceito por addItem e setItems

Valores de items preservam Unicode, espaços no início e no fim, exports explicitamente vazios e quebras de linha; caracteres de controle XML inválidos e surrogates UTF-16 não pareados são rejeitados antes da mutação da lista

Estado imediato e aliases

Items novos são imediatamente visíveis pelos métodos de items e pelo DOM de propriedades, e um alias de item excluído não pode redirecionar para um item sobrevivente que se move para o índice excluído

Substituir ou limpar a lista cria identidades de substituição distintas; aliases retidos de objetos de scripts para items removidos falham em leituras e escritas posteriores, enquanto aliases sobreviventes continuam endereçando o mesmo item entre execuções de eventos

Uma atribuição direta de rawValue, escrita no Data DOM vinculado, commit público de valor de widget ou mutação escalar de item de export invalida os índices explícitos em cache, incluindo atribuições que preservam a mesma string raw

Persistência e seleção exata

SaveToBytes grava os items reais de formulários por instância e os valores sincronizados; modificar uma instância repetida preserva as outras instâncias e os escopos de dados delas

Exports duplicados e vazios podem ser selecionados por índices exatos através da API de items; o campo de formulário salvo registra os índices canônicos e o valor raw correspondente em atributos opcionais no namespace urn:hotpdf:xfa:runtime

Items e nós de valores padrão do XFA permanecem presentes independentemente desses atributos opcionais; escritas posteriores de valores invalidam os atributos para que índices velhos não selecionem o export duplicado errado

O consumer nativo PDF grava pares export/display correspondentes de /Opt, índices /I exatos e strings ou arrays /V, e constrói aparências a partir dos rótulos de display selecionados

Transações e limites

Mudanças de items participam da transação e do journal existentes de eventos; uma falha nativa de limite de valores, cancelamento do chamador ou exceção de evento não tratada restaura o XDP salvo, o estado lexical de scripts e os bindings antes de um retry posterior

Alocações de nós, colunas de entrada, valores UTF-8, payloads de operações XML, traversal e clonagem nativos de propriedades retêm os orçamentos configurados de scripts e runtime e as checagens de cancelamento

Exemplo

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 variáveis FormCalc que retêm um campo em vez do valor escalar dele, use var list = Ref($.parent.choice) antes de chamar os métodos de items

O vocabulário de métodos e os arguments de colunas seguem a Adobe Designer Scripting Reference; o runtime usa semântica de substituição para setItems, como descrito no suporte a scripting de HTML5 forms da Adobe