XFA 선택 항목 스크립팅

Unit: HPDFXFARuntime

ui.choiceList를 가진 필드는 네이티브 JavaScript와 FormCalc 이벤트 실행 중에 선택 항목 메서드를 노출합니다. 반복 필드 인스턴스와 스크립트 객체가 유지하는 별칭도 포함입니다

메서드와 속성

멤버	동작
`length`	현재 export 항목 수의 읽기 전용 값
`selectedIndex`	선택된 첫 번째 0 기반 인덱스, 선택이 없으면 -1. 음수 정수를 할당하면 선택을 해제하고, 범위 밖의 양수나 비정수 값을 할당하면 변경 전에 throw합니다
`getDisplayItem(index)`	해당 인덱스의 표시 텍스트, 인덱스가 무효하면 null
`getSaveItem(index)`	해당 인덱스의 export 텍스트, 인덱스가 무효하면 null
`boundItem(display)`	정확히 매칭되는 첫 번째 표시 텍스트의 export 텍스트, 매칭이 없으면 null
`getItemState(index)`	항목의 선택 여부. 무효한 인덱스는 throw합니다
`setItemState(index, selected)`	항목의 선택을 갱신합니다. 단일 선택 필드에서 항목을 선택하면 이전 선택을 대체하고, 다중 선택 필드에서는 다른 선택 인덱스를 유지합니다
`addItem(display, bound)`	기존 선택된 항목을 바꾸지 않고 항목을 추가합니다. 두 번째 인수를 생략하면 빈 export 문자열을 씁니다
`deleteItem(index)`	항목을 삭제하고 이후 인덱스를 당기되 살아남은 항목 별칭의 신원은 유지합니다. 무효한 인덱스는 false를 반환합니다
`clearItems()`	현재 항목을 제거하고 선택을 해제합니다. 명시적으로 비운 런타임 리스트는 저장 후 다시 로드해도 비어 있습니다
`setItems(text, columns)`	쉼표로 구분된 컬럼에서 현재 항목을 교체하고 선택을 해제합니다. columns 기본값은 1이고, 한 컬럼 행은 표시·export 텍스트 모두에 쓰이며, 더 긴 행은 첫 컬럼을 표시 텍스트로, 마지막 컬럼을 export 텍스트로 씁니다. 컬럼 수가 무효하거나 입력 필드 수를 나누지 않으면 false를 반환합니다

인덱스는 정수이며 문자열에서 강제 변환되지 않습니다. 항목 메서드는 문서화된 인수 수를 요구하고, addItem과 setItems는 선택적 두 번째 인수를 받습니다

항목 값은 Unicode, 선행·후행 공백, 명시적 빈 export, 줄바꿈을 보존합니다. 무효한 XML 제어 문자와 짝 안 맞는 UTF-16 서러게이트는 리스트 변경 전에 거부됩니다

즉시 상태와 별칭

새 항목은 항목 메서드와 속성 DOM에서 즉시 보이며, 삭제된 항목의 별칭은 삭제된 인덱스로 이동한 살아남은 항목을 가리키도록 재설정될 수 없습니다

리스트를 교체하거나 비우면 서로 다른 교체 신원이 만들어집니다. 제거된 항목을 가리키던 스크립트 객체 별칭은 이후 읽기·쓰기에서 실패하고, 살아남은 별칭은 이벤트 실행을 가로지르며 같은 항목을 계속 참조합니다

직접 rawValue 할당, Data DOM 쓰기, 공개 위젯 값 커밋, export 항목 스칼라 변경은 캐시된 명시적 인덱스를 무효화합니다. 같은 원시 문자열을 유지하는 할당도 포함입니다

영속성과 정확한 선택

SaveToBytes는 인스턴스별 실제 폼 항목과 동기화된 값을 씁니다. 반복 인스턴스를 수정해도 다른 인스턴스와 그 데이터 스코프는 보존됩니다

중복 export와 빈 export는 항목 API로 정확한 인덱스로 선택할 수 있습니다. 저장된 폼 필드는 urn:hotpdf:xfa:runtime 네임스페이스의 선택 속성에 정규 인덱스와 매칭되는 원시 값을 기록합니다

표준 XFA 항목과 값 노드는 이 선택 속성과 무관하게 존재합니다. 이후 값 쓰기는 속성을 무효화하므로 오래된 인덱스가 잘못된 중복 export를 선택할 수 없습니다

네이티브 PDF 소비자는 매칭되는 /Opt export/표시 쌍, 정확한 /I 인덱스, /V 문자열이나 배열을 쓰고, 선택된 표시 라벨로 appearance를 만듭니다

트랜잭션과 한도

항목 변경은 기존 이벤트 트랜잭션과 스크립트 저널에 참여합니다. 네이티브 값 한도 실패, 호출자 취소, 처리되지 않은 이벤트 예외는 저장된 XDP, 스크립트 렉시컬 상태, 바인딩을 이후 재시도 전에 복원합니다

노드 할당, 입력 컬럼, UTF-8 값, XML 연산 페이로드, 네이티브 속성 순회와 복제는 설정된 스크립트·런타임 예산과 취소 검사를 유지합니다

예제

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");

스칼라 값이 아니라 필드를 유지하는 FormCalc 변수는 항목 메서드를 호출하기 전에 var list = Ref($.parent.choice)를 쓰세요

메서드 어휘와 컬럼 인수는 Adobe Designer Scripting Reference를 따릅니다. 런타임은 Adobe의 HTML5 forms scripting support에서 설명하는 대로 setItems에 교체 의미론을 씁니다