Artykuł techniczny

Zapis XFA: znaki nowej linii, emoji i restoreState

Puste pole Comments na formularzu roszczeniowym XFA otwiera się ponownie z jednym znakiem nowej linii w środku. Zapisz i otwórz jeszcze raz — pole ma ich dwa. Nazwisko klienta wpisane z U+1F642, lekko uśmiechniętą twarzą, wraca jako U+F642, punkt kodowy z obszaru prywatnego, który większość czcionek rysuje jako pusty prostokąt. Wszystkie trzy efekty mieszkają w XML, który zapis XFA wpisuje do pakietu datasets, a ścieżka zapisu, która chce je mieć z głowy, musi trzymać biel layoutu poza wartościami pól, nieść znaki z płaszczyzny uzupełniającej jako kompletne pary surrogate'ów i zgłaszać nieudany zapis przez wynik zapisu, a nie przez uszkodzony plik

Który runtime PDFium zapisuje wartości XFA?

Wartości XFA zapisuje wyłącznie pdfium.v8.dll, bo to jedyny build PDFium Component, który niesie i silnik JavaScript V8, i runtime formularzy XFA. Gdy edycja została skomitowana (pole straciło fokus albo ClearFormFieldFocus wymusił commit), ten runtime eksportuje przy zapisie żywe dane XFA do pakietu datasets, bez żadnej edycji pakietów w twoim kodzie. Każda architektura Windows dostaje też pdfium.dll, zbudowany bez V8 i XFA, który zapisuje przechowane pakiety dokładnie tak, jak je przeczytał. Co się dzieje z wartością wpisaną, gdy pole wciąż ma fokus, opisuje artykuł o tym, dlaczego edycje pól XFA znikają przy zapisie

Wrapper Delphi stara się sam wybrać właściwą bibliotekę. Gdy EnableV8Engine jest wciąż False i żadna biblioteka PDFium nie została jeszcze wczytana, TPdf ogląda plik, który zamierza otworzyć, i jeśli znajduje znaczniki XFA (wpis /XFA w słowniku AcroForm albo /NeedsRendering true w katalogu), włącza EnableV8Engine przed wczytaniem. Ten przełącznik działa raz na proces. Jeśli zwykły pdfium.dll jest już rezydentny, bo pierwszym dokumentem sesji był zwykły PDF, proces pozostaje mu wierny, a TPdf.OnXfaRuntimeMissing odpala, gdy później przychodzi dokument XFA

Domyślna kolejność szukania to druga połowa problemu. Bez katalogu w LibraryName loader zaczyna od folderu DLLs\Win32 albo DLLs\Win64 pod folderem aplikacji albo jednym z jego przodków, więc najpierw może wypaść starszy pdfium.v8.dll. LibraryName zawierające katalog przypina dokładnie ten plik, a gdy go brakuje, wczytywanie zawodzi

uses
  System.SysUtils, PDFium;

procedure SelectXfaRuntime;
begin
  // Katalog w LibraryName przypina ten dokładny plik;
  // gdy pliku brakuje, wczytywanie podnosi wyjątek zamiast schodzić niżej
{$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;  // zawieść na starcie, nie przy pierwszym zapisie
end;

Po otwarciu dokumentu TPdf.XFA mówi, że plik zawiera XFA, a TPdf.XfaRuntimeAvailable — że wczytana biblioteka potrafi dla tego dokumentu faktycznie uruchomić silnik XFA. Formularze statyczne i dynamiczne odróżnia TPdf.FormType, który zwraca ftXfaFull dla formularza dynamicznego i ftXfaForeground dla statycznego. Sondowanie na poziomie pakietów na maszynie bez runtime V8 to temat artykułu o wykrywaniu formularzy XFA i wyciąganiu pakietów XFA w Delphi

Dlaczego zapisane pola XFA mogą zyskać dodatkowe znaki nowej linii?

Zapisane pola XFA zyskują znaki nowej linii, gdy pisarz pretty-printuje swój XML z nową linią po każdym tagu otwierającym. W zapisie XFA uczestniczą dwa pisarze — generyczny pisarz elementów XML i serializator pakietu formularza — i obaj nawykowo formatują wyjście w ten sposób. W większości dokumentów XML ta biel jest kosmetyczna. W danych XFA jest wartością: gdy pakiet datasets jest parsowany ponownie, każdy znak między <Comments> a </Comments> należy do pola — nowa linia wliczona

Diagram cyklu zapisu XFA w PDFium Component, gdzie pisarz dokleja nową linię po tagach otwierających, ponownie otwarty parser czyta LF między tagami Comments jako wartość pola, a każdy dalszy zapis dokleja następny znak nowej linii, chyba że pisarz usuwa wyłącznie biel, którą sam syntetyzował
Jeden cykl zapisu i ponownego otwarcia sieje pierwszy znak nowej linii, a każda kolejna runda dokleja następny — dlatego dryf pokazuje pełny kształt dopiero na drugiej generacji

Puste pole otwiera się więc ponownie z jednym LF. Każdy dalszy zapis formatuje wokół LF, który już tam siedzi, więc pole, którego nikt nie tknął, rośnie o jedną linię na rundę przeglądu

Przycinanie wartości przy wczytywaniu wygląda na tanią naprawę i zepsułoby prawdziwe dane. Ludzie wpisują do pól XFA spacje z przodu, spacje na końcu i celowe łamanie linii; blok adresu musi utrzymać strukturę wierszy, a kod referencyjny o stałej szerokości musi przeżyć bajt po bajcie. Pisarze XFA w PDFium Component wyrzucają więc wyłącznie biel, którą sam serializator syntetyzuje wokół tagów. Wartości użytkownika, węzły tekstowe już obecne w pliku i sekcje CDATA przechodzą nietknięte, więc " indented" zostaje wcięte, a celowo puste pole pozostaje puste

Emoji, pary surrogate'ów i 16-bitowy wchar_t

Emoji wraca jako inny znak, gdy ścieżka dekodowania zapisuje pełną wartość skalarną Unicode w pojedynczym wchar_t, który na Windows ma 16 bitów. Dwa miejsca wczytywania XFA są na to wystawione: dekoder strumienia UTF-8 i parser numerycznych referencji znaków, takich jak &#x1F642;. U+1F642 potrzebuje 17 bitów. Wciśnij go w 16, a górny bit odpada i zostaje U+F642 w Private Use Area

Serializator formularza potrafi zawieść w przeciwnym kierunku. Filtrując znaki po jednym wchar_t, widzi dwie jednostki surrogate'owe, D83D i DE42, z których każda jest nieprawidłowa w izolacji, i wyrzuca obie. Emoji znika z pakietu formularza bez śladu, nawet znaku zastępczego nie zostawiając

Diagram obsługi surrogate'ów w PDFium Component, gdzie U+1F642 przychodzi jako para UTF-16 D83D DE42, a dwie naiwne ścieżki potrafią ją zepsuć: dekodery 16-bitowego wchar_t ucinają skalar do U+F642 w obszarze prywatnym, a serializator filtrujący samotne surrogaty wyrzuca emoji całkowicie
Windowsowe wchar_t ma 16 bitów, więc skalar wymagający pary surrogate'ów traci górną połowę albo znika z pakietu, dopóki obie ścieżki nie nauczą się trzymać par razem

W PDFium Component dekoder konsumuje każdą wartość skalarną w całości i emituje porządną parę surrogate'ów — także wtedy, gdy bufor wyjściowy ma miejsce tylko na jedną kolejną jednostkę i wtedy, gdy czterobajtowa sekwencja UTF-8 jest rozcięta między dwa bloki odczytu. Na wyjściu eksporter formularza trzyma ważne pary surrogate'ów razem, a numeryczne referencje znaków też dekodują do poprawnych par

Dane testowe Latin-1 nigdy nie dotykają żadnej z tych ścieżek. Test round-tripu formularza XFA potrzebuje w polu tekstowym przynajmniej jednego znaku powyżej U+FFFF, a sprawdzenie zapisanych bajtów pod kątem czterobajtowej sekwencji UTF-8 F0 9F 99 82 mówi więcej niż patrzenie na wyrenderowane pole

XFA w jednym strumieniu i wynik zapisu

Dokument XFA w jednym strumieniu broni swoich edycji tylko wtedy, gdy ścieżka zapisu potrafi przepisać jeden strumień XDP w miejscu, a każde wejście, którego przepisać nie potrafi, musi zawalić zapis. ISO 32000-1 §12.7.8 pozwala, żeby wpis /XFA słownika formularza interaktywnego był albo tablicą przeplatającą nazwy pakietów i strumienie, albo pojedynczym strumieniem niosącym cały dokument XDP. Ścieżka zapisu napisana tylko dla tablic odrzuca pojedyncze strumienie, a jeśli wołający zignoruje ten wynik, PDF zostaje zapisany z danymi formularza na starych wartościach

Runtime V8 w PDFium Component obsługuje zdefiniowany podzbiór pojedynczego strumienia w trzech krokach. Eksportuje oba żywe pakiety, datasets i form, do strefy przygotowawczej i waliduje je. Dopiero potem podmienia pasujące pakiety wewnątrz oryginalnego XDP, zachowując pozostałe pakiety i deklaracje przestrzeni nazw korzenia. Gdy przygotowanie zawiedzie, trwały strumień XFA nie jest nigdy ruszany, a dokument trzyma swoją pieczątkę modyfikacji, więc późniejszy zapis może spróbować ponownie

Potok zapisu XFA w jednym strumieniu w PDFium Component, gdzie żywe pakiety datasets i form są eksportowane do strefy przygotowawczej, walidowane, a potem podmieniane wewnątrz oryginalnego XDP z komentarzami zachowanymi przez znaczniki, podczas gdy porażki przygotowania i wejścia jak DTD albo XMLDSig odrzucają zapis jawnie
Eksport przygotowawczy jest walidowany, zanim cokolwiek zostanie podmienione, więc nieudany zapis zostawia trwały strumień XFA nietknięty, a dokument trzyma swoją pieczątkę modyfikacji

Komentarze XML i instrukcje przetwarzania potrzebują dodatkowej troski, bo parser używany do przepisywania je wyrzuca. Każdy jest przed parsowaniem podmieniany na unikalny znacznik i odkładany z powrotem po parsowaniu, a strumień jest zapisany tylko wtedy, gdy każdy znacznik pojawia się dokładnie raz — komentarze poza żywymi pakietami zachowują więc swój tekst i porządek

Niektóre wejścia są nadal odrzucane celowo, a każde odrzucenie to jawna porażka zapisu:

  • Komentarze albo instrukcje przetwarzania wewnątrz żywych pakietów datasets albo form, bo nie da się odwzorować ich oryginalnych pozycji w świeżo wyeksportowanej treści
  • Deklaracje DTD i podpisy XMLDSig, bo przepisanie XDP nie potrafi utrzymać ważności podpisu XML
  • Nieprawidłowe UTF-8 albo UTF-16, niedomknięte tagi, nieprawidłowe referencje znaków, nieznane encje i zepsute instrukcje przetwarzania — odrzucane zamiast naprawianych w locie

Odmowa to tu lepsza wymiana. Zapis, który zwraca False, można powtórzyć, zalogować albo oddać człowiekowi, podczas gdy XDP po cichu znormalizowany potrafi złamać podpis albo importera po stronie odbiorczej tygodnie później, daleko od kodu, który to zmienił. To, co ścieżka pojedynczego strumienia faktycznie zachowuje, to model treści XML, zapisany jako UTF-8; oryginalny układ bajtów i deklaracja kodowania strumienia źródłowego nie są przenoszone

Ostatni buforowany blok

Ostatnia pułapka siedzi poniżej XFA, w generycznym pisarzu PDF. Pisarz plików buforujący wyjście w blokach o stałym rozmiarze musi na końcu wypchnąć ostatni częściowy blok. Jeśli to się dzieje w kodzie sprzątającym, po tym jak pisarz dokumentów zdążył już zgłosić sukces, pełny dysk albo błąd I/O na ostatnim bloku nigdy nie dociera do wołającego, a plik na dysku jest za krótki. W obu runtime'ach PDFium Component końcowy spłuk wchodzi w skład wyniku zapisu, a pieczątka modyfikacji XFA jest zdejmowana dopiero po faktycznym sukcesie zapisu

Strona Delphi dokłada jeszcze jedną warstwę. TPdf.SaveAs zapisuje do pliku tymczasowego obok celu i przenosi go na miejsce celu tylko wtedy, gdy zapis strumienia zwróci True. Wynik False zostawia poprzedni plik dokładnie takim, jaki był, a niepowodzenie końcowego przeniesienia podnosi błąd systemowy zamiast cicho przejść dalej

Dlaczego dynamiczny formularz XFA otwiera się ponownie z mniejszą liczbą stron?

Dynamiczny formularz XFA otwiera się ponownie z mniejszą liczbą stron, gdy jego subform korzenia nie deklaruje restoreState="auto", a ta decyzja należy do autora formularza. W XFA 3.3 restoreState na subformie korzenia domyślnie jest manual. Przy manual procesor XFA przywraca ze zapisanego pakietu formularza tylko ograniczony stan, a resztę zostawia własnym skryptom formularza. Wartości pól i liczniki instancji powtarzalnych subformów wracają; właściwości geometryczne ustawione w trakcie działania — nie

Weź trójstronicowy formularz, którego skrypt rozrasta subform do h="450pt", gdy użytkownik go wypełnia. Zapisany pakiet formularza trzyma nową wysokość, wartości pól i liczniki instancji. Przy ponownym otwarciu layout jest budowany od wysokości z szablonu, subform się kurczy, a treść przelewa się na dwie strony. To zachowanie, o które prosi specyfikacja XFA, gdy szablon nigdy nie poprosił o automatyczne przywracanie. Zadeklarowanie tego na subformie korzenia zmienia ponowne otwarcie:

<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">
      <!-- pola; skrypty mogą zmieniać h albo dodawać instancje w trakcie działania -->
    </subform>
  </subform>
</template>

Jeśli szablon nie jest twój, zostaw go w spokoju: formularz zbudowany dla trybu manual oczekuje, że jego własne skrypty inicjalizacyjne odbudują stan, a przełączenie trybu pod nimi zmienia to, wokół czego te skrypty były pisane. Żywa repaginacja w trakcie pisania przez użytkownika to osobny mechanizm — opisuje go artykuł o tym, jak PDFium Component śledzi liczby stron dynamicznego XFA i przeprowadzone pola

Sprawdzenie round-tripu XFA z Delphi

Zapis XFA weryfikuje się przez ponowne otwarcie zapisanego pliku w świeżej instancji TPdf i odczytanie przechowanych danych z powrotem, bo True od SaveAs mówi tylko tyle, że plik został zapisany. TPdf.GetXfaDatasets zwraca pakiet datasets taki, jak jest przechowany w dokumencie, a nie żywy model danych, więc odczyt przed zapisem pokazuje wartości z ostatniego wczytania. Po ponownym otwarciu pokazuje dokładnie to, co zapisano. Dokument w jednym strumieniu nie ma osobno nazwanych pakietów: PDFium raportuje cały XDP jako jeden pakiet o pustej nazwie, więc GetXfaPacketByName('datasets') i GetXfaDatasets zwracają obie pustą tablicę, a kod poniżej schodzi do kompletnego strumienia z 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;          // układ tablicy pakietów
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   // jeden strumień: jeden nienazwany pakiet
      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);  // zapisane wyjście XDP jest UTF-8
  finally
    Pdf.Free;
  end;
end;

Procedura zapisu komituje oczekującą edycję, sprawdza wynik SaveAs i porównuje ponownie otwartą wartość. TPdf.ClearFormFieldFocus zabiera fokus formularzowi, i to właśnie wtedy PDFium komituje bufor edycji pola z fokusem. TPdf.SetFocusedFormFieldText potrafi wypełnić pole z fokusem z kodu, ale polega na fokusie śledzonym przez adnotacje widgetów, których dynamiczna strona XFA zwykle nie ma; tam zwraca False, a tekst normalnie przychodzi przez wejście z klawiatury w TPdfView

// XmlText to helper, który dopisujesz sam; nie jest częścią 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
  // Opcjonalne wypełnienie skryptowe; False znaczy, że żadne śledzone pole nie ma fokusu
  if (Pdf.FocusedFormFieldIndex >= 0) and
     not Pdf.SetFocusedFormFieldText(Expected) then
    raise EPdfError.Create('Could not write the focused field');

  Pdf.ClearFormFieldFocus;              // commit bufora edycji
  if not Pdf.SaveAs(FileName) then      // False: poprzedni plik zostaje na miejscu
    raise EPdfError.CreateFmt('Saving %s failed', [FileName]);

  // Ponowne otwarcie w świeżym TPdf i szukanie dokładnego tekstu elementu
  Saved := ReadSavedXfaData(FileName);
  if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
    Saved) = 0 then
    raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;

Test podtekstu to tylko smoke test. Pusty element może być zapisany jako <Tag/>, elementy danych mogą nieść atrybuty, a ucieczki poza & i < to wybór serializatora — sprawdzenia produkcyjne należą do prawdziwego parsera XML. Uruchom procedurę dwa razy pod rząd na tym samym wejściu, bo dryf nowej linii pokazuje pełny kształt dopiero na drugiej generacji

Aplikacje hostujące, które napędzają runtime XFA bezpośrednio, potrzebują też układu callbacków, jakiego on się spodziewa — to temat artykułu FPDF_FORMFILLINFO version 2 i ABI XFA w Delphi. Oba runtime'y Windows dla Win32 i Win64, wrapper Delphi i C++Buildera oraz kontrolka podglądu TPdfView są częścią PDFium Component for Delphi and C++Builder