기술 문서

PDFium XFA 저장: 줄바꿈, 이모지, restoreState

XFA 클레임 폼의 빈 Comments 상자가 줄바꿈 하나를 담은 채 다시 열립니다. 저장하고 다시 열면 두 개가 됩니다. U+1F642, 살짝 웃는 얼굴로 입력한 고객 이름은 U+F642, 대부분의 폰트가 빈 사각형으로 그리는 private use 코드 포인트로 돌아옵니다. 세 효과 모두 XFA 저장이 datasets 패킷에 쓰는 XML 안에 살고, 이것들을 올바르게 다루는 저장 경로는 레이아웃 공백이 필드 값으로 들어가지 않게 하고, 보충 평면 문자를 온전한 서로게이트 쌍으로 운반하며, 실패한 기록을 손상된 파일이 아니라 저장 결과로 보고해야 합니다

어떤 PDFium 런타임이 XFA 값을 저장하나

XFA 값을 저장하는 것은 pdfium.v8.dll뿐입니다. V8 JavaScript 엔진과 XFA 폼 런타임을 함께 실은 유일한 PDFium Component 빌드이기 때문입니다. 편집이 커밋되고 나면(필드가 포커스를 잃거나 ClearFormFieldFocus가 커밋을 강제했을 때) 그 런타임은 저장 시점에 살아 있는 XFA 데이터를 datasets 패킷으로 익스포트하고, 코드에서 패킷을 편집할 필요는 없습니다. 각 Windows 아키텍처에는 V8과 XFA 없이 빌드된 pdfium.dll도 함께 배포되는데, 이쪽은 저장해 둔 패킷을 읽은 그대로 되돌려 씁니다. 필드에 포커스가 남아 있는 동안 쓴 값의 행방은 XFA 필드 편집이 저장에서 사라지는 이유에 정리되어 있습니다

Delphi 래퍼는 올바른 라이브러리를 골라 주려고 합니다. EnableV8Engine이 아직 False이고 아무 PDFium 라이브러리도 로드되지 않았으면, TPdf는 열려는 파일을 살펴 보고 XFA 표식(AcroForm 딕셔너리의 /XFA 항목이나 카탈로그의 /NeedsRendering true)을 발겡하면 로드 전에 EnableV8Engine을 켭니다. 이 전환은 프로세스마다 한 번만 동작합니다. 세션의 첫 문서가 평범한 PDF라서 이미 pdfium.dll이 상주 중이라면 프로세스는 그것에 묶인 채이고, 나중에 XFA 문서가 도착하면 TPdf.OnXfaRuntimeMissing이 발화합니다

기본 탐색 순서가 문제의 다른 절반입니다. LibraryName에 디렉터리가 없으면 로더는 애플리케이션 폴더나 그 상위 폴더 중 하나의 DLLs\Win32 또는 DLLs\Win64 폴더부터 찾으므로, 오래된 pdfium.v8.dll이 먼저 발견될 수 있습니다. 디렉터리를 포함한 LibraryName은 정확히 그 파일을 고정하고, 파일이 없으면 로드가 실패합니다

uses
  System.SysUtils, PDFium;

procedure SelectXfaRuntime;
begin
  // LibraryName의 디렉터리는 정확히 이 파일을 고정하고
  // 파일이 없으면 다른 곳을 찾는 대신 LoadLibrary가 실패합니다
{$IFDEF WIN64}
  PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win64\pdfium.v8.dll';
{$ELSE}
  PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win32\pdfium.v8.dll';
{$ENDIF}
  PDFium.EnableV8Engine := True;
  PDFium.LoadLibrary;  // 첫 XFA 저장이 아니라 시작 시점에 실패합니다
end;

문서를 연 뒤에는 TPdf.XFA가 파일에 XFA가 들어 있다고 알려 주고, TPdf.XfaRuntimeAvailable이 로드된 라이브러리가 이 문서에 대해 실제로 XFA 엔진을 시작할 수 있는지 알려 줍니다. 정적 폼과 동적 폼은 TPdf.FormType으로 구분합니다. 동적 폼은 ftXfaFull, 정적 폼은 ftXfaForeground를 반환합니다. V8 런타임 없는 머신에서의 패킷 수준 탐지는 Delphi에서 XFA 폼 감지와 XFA 패킷 추출의 주제입니다

저장된 XFA 필드에 줄바꿈이 붙는 이유

작성기가 시작 태그마다 줄바꿈을 넣어 XML을 예쁘게 인쇄하면 저장된 XFA 필드에 줄바꿈이 붙습니다. XFA 저장에는 두 작성기가 관여합니다. 범용 XML 요소 작성기와 폼 패킷 직렬화기이고, 둘 다 습관적으로 출력을 그렇게 형식화합니다. 대부분의 XML 문서에서 그 공백은 장식입니다. XFA 데이터에서는 그것이 값입니다. datasets 패킷을 다시 파싱하면 <Comments>와 </Comments> 사이의 모든 문자, 줄바꿈 포함이 필드에 속합니다

PDFium Component XFA 저장 사이클 다이어그램: 작성기가 시작 태그 뒤에 줄바꿈을 더하고, 다시 열린 파서는 Comments 태그 사이의 LF를 필드 값으로 읽으며, 작성기가 자신이 만들어 낸 공백만 제거하지 않는 한 추가 저장마다 줄바꿈이 하나씩 쌓입니다
첫 저장-재오픈 사이클이 첫 줄바꿈을 심고 이후 매 왕복이 하나씩 더합니다. 어긋남의 전체 모양이 두 번째 세대에서만 드러나는 이유입니다

때문에 빈 필드는 LF 하나를 담은 채 다시 열립니다. 이후의 저장마다 이미 있는 LF 주위로 형식화가 이루어지므로, 아무도 손대지 않은 필드는 검토 한 번당 줄이 하나씩 늘어납니다

로드 시점에 값을 잘라내는 것은 값싼 수리처럼 보이지만 실제 데이터를 망가뜨립니다. 사람들은 XFA 필드에 선행 공백, 후행 공백, 의도적인 줄바꿈을 입력하고, 주소 블록은 줄 구조를 유지해야 하며 고정폭 참조 코드는 바이트 그대로 살아남아야 합니다. 그래서 PDFium Component의 XFA 작성기는 직렬화기 자신이 태그 주위에 만들어 낸 공백만 제거합니다. 사용자 값, 파일에 이미 있던 텍스트 노드, CDATA 섹션은 그대로 통과하므로 " indented"는 계속 들여쓰기 되고 의도적으로 빈 필드는 빈 채로 남습니다

이모지, 서로게이트 쌍, 16비트 wchar_t

디코딩 경로가 온전한 유니코드 스칼라 값을 wchar_t 하나에 담으면 — Windows에서는 16비트입니다 — 이모지가 다른 문자로 돌아옵니다. XFA 로드에서 이 함정이 사는 곳은 두 곳입니다. UTF-8 스트림 디코더와 &#x1F642; 같은 숫자 문자 참조 파서입니다. U+1F642에는 17비트가 필요합니다. 16비트에 억지로 넣으면 최상위 비트가 떨어져 나가 Private Use Area의 U+F642가 남습니다

폼 직렬화기는 반대 방향으로 실패할 수 있습니다. 문자를 wchar_t 하나씩 걸러 내면 D83D와 DE42, 각자 따로는 무효인 서로게이트 코드 유닛 둘이 보이고 둘 다 버려집니다. 이모지는 대체 문자 하나 남기 없이 폼 패킷에서 사라집니다

PDFium Component 서로게이트 처리 다이어그램: U+1F642가 UTF-16 쌍 D83D DE42로 도착할 때 무심한 두 경로가 그것을 망가뜨립니다. 16비트 wchar_t 디코더는 스칼라를 private use area의 U+F642로 절단하고, 홀로 남은 서로게이트를 걸러 내는 직렬화기는 이모지를 통째로 버립니다
Windows의 wchar_t는 16비트이므로 서로게이트 쌍이 필요한 스칼라는 두 경로가 모두 쌍을 함께 유지하지 않으면 상위 절반을 잃거나 패킷에서 사라집니다

PDFium Component에서 디코더는 각 스칼라 값을 온전히 소비하고 올바른 서로게이트 쌍을 출력합니다. 출력 버퍼에 유닛 한 칸만 남았을 때도, 4바이트 UTF-8 시퀀스가 두 읽기 블록에 갈라져도 마찬가지입니다. 출력 방향에서는 폼 익스포터가 유효한 서로게이트 쌍을 함께 유지하고, 숫자 문자 참조도 올바른 쌍으로 디코딩됩니다

Latin-1 테스트 데이터는 이 경로 어디도 건드리지 않습니다. XFA 폼의 왕복 테스트에는 텍스트 필드에 U+FFFF 위의 문자가 최소 하나 필요하고, 저장된 바이트에서 4바이트 UTF-8 시퀀스 F0 9F 99 82를 확인하는 편이 렌더링된 필드를 보는 것보다 훨씬 많은 것을 알려 줍니다

단일 스트림 XFA와 저장 결과

단일 스트림 XFA 문서는 저장 경로가 하나의 XDP 스트림을 제자리에 다시 쓸 수 있을 때만 편집을 유지하고, 다시 쓸 수 없는 입력은 저장을 실패시켜야 합니다. ISO 32000-1 §12.7.8은 대화형 폼 딕셔너리의 /XFA 항목이 패킷 이름과 스트림이 번갈아 나오는 배열이거나 XDP 문서 전체를 담은 단일 스트림 가운데 하나임을 허용합니다. 배열 전용으로 작성된 저장 경로는 단일 스트림을 거부하고, 호출부가 그 결과를 무시하면 PDF는 폼 데이터를 옛 값으로 둔 채 작성됩니다

PDFium Component의 V8 런타임은 정의된 단일 스트림 부분집합을 세 단계로 처리합니다. 살아 있는 두 패킷, datasets와 form을 스테이징 영역으로 익스포트해 검증합니다. 그다음에야 원본 XDP 안의 해당 패킷을 교체하며, 다른 패킷과 루트 네임스페이스 선언은 유지합니다. 스테이징이 실패하면 영속 XFA 스트림은 건드리지 않고 문서는 수정 표시를 유지하므로, 이후의 저장이 다시 시도할 수 있습니다

PDFium Component 단일 스트림 XFA 저장 파이프라인: 라이브 datasets와 form 패킷을 스테이징으로 내보내 검증한 뒤 원본 XDP 안에서 교체하며 주석은 마커로 보존한다. 스테이징 실패와 DTD나 XMLDSig 같은 입력은 저장을 명시적으로 거부한다
스테이징된 내보내기는 무언가를 교체하기 전에 검증됩니다. 실패한 저장은 영속 XFA 스트림을 건드리지 않고 문서는 수정 표시를 유지합니다

재작성에 쓰는 파서가 버리기 때문에 XML 주석과 처리 명령은 특별한 주의가 필요합니다. 각각은 파싱 전에 고유한 마커로 바꿔 두었다가 나중에 되돌리고, 모든 마커가 정확히 한 번씩 나타날 때만 스트림을 씁니다. 그래서 라이브 패킷 밖의 주석도 텍스트와 순서를 유지합니다

일부 입력은 아예 거부되며, 각 거부는 실패한 저장으로 전달됩니다

  • 라이브 datasets나 form 패킷 안의 주석 또는 처리 명령. 원래 위치를 새로 익스포트한 콘텐츠에 대응시킬 방법이 없습니다
  • DTD 선언과 XMLDSig 서명. XDP를 재작성하면서 XML 서명의 유효성을 유지할 수 없습니다
  • 잘못된 UTF-8이나 UTF-16, 불완전한 태그, 잘못된 문자 참조, 알 수 없는 엔티티, 기형적인 처리 명령. 즉석에서 수리하는 대신 거부합니다

여기서는 거부가 더 나은 절충입니다. False를 반환하는 저장은 재시도하거나 기록하거나 사람에게 넘길 수 있습니다. 반면 조용히 정규화된 XDP는 몇 주 뒤, 그것을 바꾼 코드와는 먼 곳에서 서명이나 다운스트림 임포터를 깨뜨릴 수 있습니다. 단일 스트림 경로가 보존하는 것은 XML 콘텐츠 모델이며 UTF-8로 씁니다. 소스 스트림의 원본 바이트 레이아웃과 인코딩 선언은 옮겨지지 않습니다

마지막 버퍼 블록

마지막 함정은 XFA 아래, 범용 PDF 작성기에 있습니다. 출력을 고정 크기 블록으로 버퍼링하는 파일 작성기는 마지막 부분 블록을 끝에 밀어 내야 합니다. 그것이 문서 작성기가 이미 성공을 보고한 뒤의 정리 코드에서 일어나면, 마지막 블록의 디스크 풀 또는 I/O 오류는 호출부에 도달하지 않고 디스크의 파일은 짧아집니다. 두 PDFium Component 런타임 모두에서 마지막 플러시는 저장 결과의 일부이고, XFA 수정 표시는 기록이 실제로 성공한 뒤에만 지워집니다

Delphi 쪽은 한 층 더 얹습니다. TPdf.SaveAs는 대상 옆의 임시 파일에 쓰고, 스트림 저장이 True를 반환할 때만 그것을 대상 위로 이동합니다. False 결과는 이전 파일을 그 자리 그대로 두고, 최종 교체의 실패는 조용히 돌아오는 대신 OS 오류를 raise 합니다

동적 XFA 폼이 더 적은 페이지로 다시 열리는 이유

동적 XFA 폼은 루트 서브폼이 restoreState="auto"를 선언하지 않으면 더 적은 페이지로 다시 열리는데, 이 결정은 폼 제작자의 몫입니다. XFA 3.3에서 루트 서브폼의 restoreState 기본값은 manual입니다. manual 아래에서 XFA 프로세서는 저장된 폼 패킷에서 제한된 상태만 복원하고 나머지는 폼 자신의 스크립트에 맡깁니다. 필드 값과 반복 서브폼의 인스턴스 개수는 돌아오지만, 실행 시점에 설정된 기하 속성은 돌아오지 않습니다

사용자가 채워 넣는 동안 스크립트가 서브폼을 h="450pt"로 키우는 세 페이지 폼을 생각해 봅시다. 저장된 폼 패킷에는 새 높이와 필드 값, 인스턴스 개수가 들어 있습니다. 다시 열면 레이아웃이 템플릿 높이로 재구성되고 서브폼은 줄어들며, 콘텐츠는 두 페이지로 재유동합니다. 템플릿이 자동 복원을 요청하지 않았을 때 XFA 사양이 요구하는 동작이 그것입니다. 루트 서브폼에 선언하면 재오픈이 달라집니다

<template xmlns="http://www.xfa.org/schema/xfa-template/3.3/">
  <subform name="form1" layout="tb" restoreState="auto">
    <pageSet>
      <pageArea name="Page1">
        <contentArea x="0.25in" y="0.25in" w="8in" h="10.5in"/>
        <medium stock="letter"/>
      </pageArea>
    </pageSet>
    <subform name="Details" layout="tb" w="7.5in">
      <!-- 필드; 스크립트가 실행 시점에 h를 바꾸거나 인스턴스를 추가할 수 있음 -->
    </subform>
  </subform>
</template>

템플릿을 소유하지 않았다면 그대로 두세요. manual 모드를 위해 만들어진 폼은 자기 초기화 스크립트가 상태를 재구축하리라 기대하며, 그 밑바닥을 바꾸면 스크립트들이 전제하던 것이 달라집니다. 사용자가 입력하는 동안의 실시간 재페이지네이션은 다른 메커니즘으로, PDFium Component가 동적 XFA 페이지 수와 이동한 필드를 추적하는 방법에 설명되어 있습니다

Delphi에서 XFA 왕복 검사하기

XFA 저장은 저장된 파일을 새 TPdf 인스턴스로 다시 열어 저장된 데이터를 읽어 봄으로써 검증합니다. SaveAs의 True는 파일이 쓰였다는 말일 뿐입니다. TPdf.GetXfaDatasets는 라이브 데이터 모델이 아니라 문서에 저장된 그대로의 datasets 패킷을 반환하므로, 저장 전에 읽으면 마지막 로드의 값이 보입니다. 다시 연 뒤에는 쓰인 것을 정확히 보여 줍니다. 단일 스트림 문서에는 이름 붙은 별개 패킷이 없습니다. PDFium은 XDP 전체를 빈 이름의 패킷 하나로 보고하므로 GetXfaPacketByName('datasets')과 GetXfaDatasets는 모두 빈 배열을 반환하고, 아래 코드는 GetXfaFormPackets의 전체 스트림으로 폴백합니다

uses
  System.SysUtils, PDFium, FPdfXfa;

function ReadSavedXfaData(const FileName: string): string;
var
  Pdf: TPdf;
  Packets: TXfaPacketList;
  Bytes: TBytes;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.Active := True;
    Bytes := Pdf.GetXfaDatasets;          // 패킷 배열 레이아웃
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   // 단일 스트림: 이름 없는 패킷 하나
      if Length(Packets) = 1 then
      begin
        SetLength(Bytes, Length(Packets[0].Content));
        if Length(Bytes) > 0 then
          Move(Packets[0].Content[0], Bytes[0], Length(Bytes));
      end;
    end;
    Result := TEncoding.UTF8.GetString(Bytes);  // 저장된 XDP 출력은 UTF-8
  finally
    Pdf.Free;
  end;
end;

저장 루틴은 대기 중인 편집을 커밋하고 SaveAs 결과를 확인하며 다시 열린 값을 비교합니다. TPdf.ClearFormFieldFocus는 폼 포커스를 해제하는데, PDFium이 포커스된 필드의 편집 버퍼를 커밋하는 시점이 바로 이것입니다. TPdf.SetFocusedFormFieldText는 코드에서 포커스된 필드를 채울 수 있지만, 위젯 어노테이션을 통해 추적되는 포커스에 의존합니다. 동적 XFA 페이지에는 보통 그런 어노테이션이 없으므로 그곳에서는 False를 반환하고, 텍스트는 보통 TPdfView의 키보드 입력으로 들어옵니다

// XmlText는 직접 추가하는 헬퍼입니다. PDFium Component의 일부가 아닙니다
function XmlText(const S: string): string;
begin
  Result := StringReplace(S, '&', '&amp;', [rfReplaceAll]);
  Result := StringReplace(Result, '<', '&lt;', [rfReplaceAll]);
end;

procedure SaveXfaAndVerify(Pdf: TPdf; const FileName, FieldTag,
  Expected: string);
var
  Saved: string;
begin
  // 선택적 스크립트 채움. False는 포커스를 가진 추적 필드가 없다는 뜻입니다
  if (Pdf.FocusedFormFieldIndex >= 0) and
     not Pdf.SetFocusedFormFieldText(Expected) then
    raise EPdfError.Create('Could not write the focused field');

  Pdf.ClearFormFieldFocus;              // 편집 버퍼를 커밋합니다
  if not Pdf.SaveAs(FileName) then      // False이면 이전 파일이 그 자리에 남습니다
    raise EPdfError.CreateFmt('Saving %s failed', [FileName]);

  // 새 TPdf로 다시 열고 정확한 요소 텍스트를 찾습니다
  Saved := ReadSavedXfaData(FileName);
  if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
    Saved) = 0 then
    raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;

부분 문자열 검사는 스모크 테스트에 불과합니다. 빈 요소는 <Tag/>로 쓰일 수 있고, 데이터 요소는 속성을 가질 수 있으며, &와 <를 넘어서는 이스케이프는 직렬화기의 선택입니다. 실전 검사는 제대로 된 XML 파서에 맡기세요. 그리고 같은 입력으로 루틴을 연달아 두 번 돌리세요. 줄바꿈 어긋남은 두 번째 세대에서만 전체 모양을 보이기 때문입니다

XFA 런타임을 직접 구동하는 호스트 애플리케이션은 런타임이 기대하는 콜백 레이아웃도 맞춰 줘야 합니다. Delphi에서 FPDF_FORMFILLINFO 버전 2와 XFA ABI가 그 주제입니다. Win32와 Win64용 두 Windows 런타임, Delphi와 C++Builder 래퍼, TPdfView 뷰어 컨트롤은 PDFium Component for Delphi and C++Builder에 함께 들어 있습니다