동적 XFA 인스턴스 프레젠테이션

유닛: HPDFXFAPresentation

TXFAInstancePresentation은 독립적인 TXFAWidgetRuntime을 소유하고, datasets 레코드 하나를 가진 XDP 패킷 문서용 bounded 인스턴스 프레젠테이션 프로필을 더합니다

SetPresence('row[1]', 'hidden')은 하나의 occurrence를 플로우에서 빼고, invisible은 위젯을 숨기면서 공간은 유지하며, visible은 되돌립니다. 인덱스는 숨겨진 occurrence를 포함해 데이터 occurrence 사이의 0부터 시작하는 위치입니다

레이아웃 리졸버는 각 occurrence를 따로 측정하고 살아남은 세로 오프셋을 압축한 뒤 다음 콘텐츠를 배치하기 전에 반복 전체 범위를 확보합니다. 고정 높이, 콘텐츠에서 유도한 높이, 테이블 행 모두 리플로우에 참여합니다

안정적인 식별자와 영속성

위젯 ID는 불투명한 템플릿과 datasets 식별자를 조합하며, 앞쪽 행이 숨겨지거나 제거되어도, 저장 후 다시 로드해도, 남은 필드가 포커스나 미확정 편집을 유지하는 동안에도 안정적입니다

이 헬퍼는 네임스페이스 한정 식별자 속성과 인스턴스 오버라이드를 urn:hotpdf:xfa:instance-presentation:1을 써서 폼 패킷 안의 외래 네임스페이스 확장에 저장합니다. 새로 추가된 행은 새 식별자와 템플릿 기본값을 받고, 제거된 행은 미확정 편집을 대체 행에 넘길 수 없습니다

SaveToBytes는 갱신된 datasets, 식별자, 프레젠테이션 상태를 포함한 XDP 전체를 반환합니다. PDF에 저장하려면 THotPDF.SetXFADocument를 쓰고, 동적 폼을 쓸 때는 XFANeedsRendering := True로 설정하세요

PDF를 다시 로드한 뒤에는 THotPDF.CreateLoadedXFAWidgetRuntime.SaveToBytes로 XDP 전체를 얻고, 그 바이트로 TXFAInstancePresentation을 구성하면 이 프로필이 복원됩니다

이 네임스페이스 확장은 이 헬퍼만 해석합니다. 네이티브 HPDFXFAFlatten, 기본 로드 런타임 팩토리, 외부 XFA 뷰어는 인스턴스별 오버라이드를 자동으로 적용하지 않으므로, 프로필을 영속 저장한다고 다른 리더에서 동일하게 렌더링된다는 보장은 아닙니다

명시적 바인딩과 인스턴스 연산

반복 서브폼은 <bind match="dataRef" ref="$record.lines.entry[*]"/>로 이름이 다른 dataset 그룹에 바인딩할 수 있습니다. 절대 $record와 $data 루트와 상대 경로는 인덱스 없는 부모 그룹과 마지막 반복 그룹을 지원합니다

각 occurrence 안의 필드는 ref="label" 같은 명시적 상대 필드 바인딩을 포함해 네이티브 바운드 값 리졸버를 씁니다

AddInstance와 RemoveInstance는 선택한 데이터 그룹을 갱신하고 occur 최소·최대를 강제하며 생성 한도를 적용한 뒤 발행 전에 리플로우합니다. 새 행은 이전 행에 입력한 값을 복사하는 게 아니라 템플릿의 필드 값을 받습니다

셀렉터는 row[1]처럼 고유한 템플릿 이름에 선택적 occurrence 인덱스를 붙인 형태입니다. 중복 템플릿 이름, 없는 그룹, 잘못된 인덱스, 모호한 반복 부모 아래의 변경은 트랜잭션을 거절합니다

SetAccess는 open, readOnly, protected, nonInteractive를 지원합니다. 인스턴스 제한은 자손에 상속되고 owned 런타임을 통한 편집을 막습니다

조건부 이벤트

DispatchConditionalEvent는 JavaScript 콘텐츠 타입인 일치하는 필드 이벤트를 찾아 bounded 프로필을 바로 파싱하고, Execute는 기존 위젯 ID에 명시적 스크립트를 실행합니다

if(this.rawValue=="hide"){
  row[1].presence="hidden";
}else{
  row[1].presence="visible";
}
row.instanceManager.addInstance();
row.instanceManager.removeInstance(0);

조건은 this.rawValue와 이스케이프하지 않은 따옴표 리터럴 사이의 동등·부등 비교를 받고, 중괄호로 감싼 중첩 if와 선택적 else 블록은 MaxDepth로 제한됩니다

대입은 presence와 access를 지원하고, 실행되지 않는 분기를 포함해 모든 분기의 문법을 검사합니다. 지원하지 않는 연산은 배치 전체를 거절시킵니다

this.rawValue는 커밋된 위젯 값을 읽습니다. 그 값을 봐야 하는 이벤트를 디스패치하기 전에 Runtime.CommitEdit로 미확정 편집을 커밋하세요

기존 Runtime.DispatchEvent는 제한된 리터럴 연산 동작을 유지하며 조건문과 인덱스 인스턴스 문법은 거절합니다. 이 헬퍼는 범용 JavaScript나 FormCalc 인터프리터, 브라우저 API, 네트워크 접근, 자동 XFA 라이프사이클 디스패치를 제공하지 않습니다

트랜잭션과 예산

변경은 TXFAWidgetRuntime.UpdateDocument를 통해 네이티브 계산과 bounded 안정 리플로우와 함께 실행됩니다. 실패하면 직렬화된 XDP, 포커스, 미확정 편집, 검증 상태, 계산·리플로우 카운터, 경고 개수를 복원합니다

포커스, 레이아웃, 위젯 무효화 콜백은 성공 후에만 발행됩니다. 롤백 해석은 네이티브 레이아웃과 위젯 경계를 유지한 채 소진된 헬퍼 작업과 취소 검사를 억제해, 취소가 복원을 가로막지 못하게 합니다

TXFAPresentationOptions는 Default로 초기화하세요. 기본값은 연산 200,000회, 프레젠테이션 상태 4,096개, 그룹당 생성 인스턴스 10,000개, 입력·문서 엔벨로프 32 MiB, 스크립트 65,536바이트, 조건 중첩 32단계, 5,000밀리초입니다

MaxInputBytes는 각 레이아웃·발행 패스 전에 식별자 속성, 네임스페이스 선언, 텍스트, datasets 변경을 포함한 보수적인 이스케이프 XML 엔벨로프에도 상한을 둡니다. 직렬화된 바이트 수가 같은 값에 도달하기 전에 유효한 XML이 이 보수적 한도에 닿을 수 있습니다

Cancelled는 bounded 작업 도중 검사되는 선택적 객체 메서드 콜백입니다. 내장된 Runtime 옵션은 위젯, 값, 계산, 레이아웃, 리플로우, 네이티브 스크립트 작업에 계속 상한을 둡니다

호스트 페인팅과 접근성

Accessibility는 안정적인 ID, 역할, 캡션 또는 필드 이름, 툴팁 설명, 커밋된 값, 페이지와 경계, 포커스, 유효성, 읽기 전용·필수 상태, 선택 레이블을 담은 보이는 위젯 레코드를 반환합니다. 비밀번호 값은 생략됩니다

PaintPage는 보이는 위젯 스냅샷과 대응하는 접근성 레코드를 TXFAHostWidgetPainter에 전달합니다. 커스텀 호스트는 자체 컨트롤이나 렌더링 표면을 구현할 수 있습니다

TXFACanvasWidgetPainter는 위젯 테두리, 텍스트, 비밀번호 마스킹, 체크박스·라디오 표시, 선택 인디케이터, 버튼, 포커스를 실제 VCL과 LCL 캔버스로 그리고, 양수 스케일과 선택적 오프셋을 받습니다. 각 위젯을 클립하고 캔버스 스타일을 복원합니다

캔버스 어댑터는 위젯만 그리고 정적 XFA 그래픽 트리 전체는 그리지 않습니다. 페이지 배경, 정적 그래픽, 이벤트 라우팅, 선택 표현, 플랫폼 접근성 브리지는 호스트가 자체적으로 공급합니다

런타임과 헬퍼는 단일 스레드 객체입니다. 콜백은 호스트의 스레드 소유권을 따라야 하고 활성 트랜잭션 중 재귀적인 변경을 피해야 합니다

C++Builder 호출자는 new TXFACanvasWidgetPainter(canvas, 1, 0, 0)처럼 캔버스 페인터 생성자 인자를 모두 제공해야 합니다. 생성된 헤더는 이런 부동소수점 기본 인자를 유지하지 않습니다

검증

인수 검증은 아키텍처당 Delphi 케이스 106개, 두 Windows 아키텍처에서의 새 FPC 컴파일, Win32와 Win64x에서의 C++Builder 공개 헤더 컴파일, 실제 PDF/XDP 출력의 독립 검증을 다룹니다

Tests/Fixtures/XFAInstancePresentation/explicit-invoice.xdp는 독립적인 데이터 이름, 반복되는 인보이스 행 세 개, 조건부 이벤트, 접근성 메타데이터, 뒤따르는 푸터를 담고 있습니다

Run-XFAInstancePresentationTests.ps1은 헬퍼 검사와 기존 XFA 이벤트, 런타임, 스크립팅, SOM, DOM, 해석 회귀 픽스처를 GUI나 외부 PDF 리더 없이 실행합니다

독립 검증기 verify_saved_invoice.py는 pypdf로 생성된 PDF를 읽고 실제 XDP 데이터 행, 고유한 영속 식별자, 숨겨진 occurrence 상태, 초기화된 기본값, 재로드 식별자를 검사합니다

powershell -File Tests/Delphi/Run-XFAInstancePresentationTests.ps1 -Platform Win32 -CheckCppHeaders
powershell -File Tests/Delphi/Run-XFAInstancePresentationTests.ps1 -Platform Win64 -CheckCppHeaders
python Tests/Fixtures/XFAInstancePresentation/verify_saved_invoice.py

호환되는 기본 런타임과 네이티브 편집 계약은 대화형 XFA 위젯 런타임을 참고하세요