Artykuł techniczny

Dynamiczne XFA w PDFium Component: liczba stron to delta

Gdy dynamiczny formularz XFA w viewerze Delphi dodaje albo usuwa strony, PDFium Component zgłasza nową sumę przez TPdf.PageCount i TPdf.OnXfaPageCountChanged, czytając ją z ukończonego layoutu, bo natywne zdarzenie strony niesie deltę dodano/usunięto, a nie sumę. Biblioteki Windows V8 przeprowadzają też obszary trafień wejścia razem z przeprowadzonymi polami, a TPdfView wczytuje uchwyty stron ponownie po powrocie callbacka layoutu. Wyobraź sobie formularz wniosku o zwrot wydatków: kliknij Dodaj wiersz dwa razy i formularz urośnie do dwóch stron. Viewer, który ufa argumentowi zdarzenia, dumnie czyta 1 z 1, a taki, który trzyma geometrię widgetów sprzed layoutu, wysyła klawisze dla pola, które przeprowadziło się na stronę 2, gdzieś niewidocznie. Nic z tego nie wychodzi na przykładowych formularzach o stałej długości, od których każdy zaczyna testy, a powody warto znać, gdy osadzasz viewer formularzy

Co się dzieje, gdy dynamiczny formularz XFA się repaginuje?

Dynamiczny formularz XFA nie ma sztywnej listy stron, więc jego liczba stron jest wynikiem layoutu i może się zmieniać przy każdej edycji danych przez użytkownika. XFA 3.3 opisuje formularz jako drzewo subformów; powtarzalnym subformem steruje instanceManager, a skrypt typu _Row.addInstance() klonuje kolejny wiersz. Procesor layoutu przelewa potem treść do obszarów stron od nowa, co może dodać stronę, zabrać stronę albo wepchnąć istniejące pola na inną stronę. ISO 32000-1 §12.7.8 definiuje wyłącznie to, jak pakiety XFA jadą wewnątrz PDF; wszystko, co dzieje się potem, należy do silnika XFA, którym w PDFium Component jest własny layout XFA PDFiuma działający w procesie gospodarza. Viewer w Delphi ma więc do czynienia z dokumentem, którego liczba stron, rozmiary stron i pozycje widgetów to żywy stan. Trzy rzeczy idą źle, gdy gospodarz zakłada inaczej:

  • liczba stron cache'owana przez gospodarza do nawigacji, zakresów przewijania i spinerów stron robi się nieaktualna albo, gorzej, zostaje zaktualizowana złą liczbą
  • pola, które się przeprowadzają, pokazują obramowanie na nowym miejscu, podczas gdy edytor i obszar trafień myszy siedzą na starych współrzędnych
  • viewer trzyma uchwyt strony, który layout podmienił, więc kliki i rysowanie idą do strony, która w tym formularzu już nie istnieje

Utrwalanie edycji wierszy przez zapis i ponowne otwarcie to osobny problem z własnymi regułami; ten artykuł zostaje przy tym, co dzieje się w trakcie działania wewnątrz viewera

Jakiego runtime'u PDFium potrzebuje dynamiczne XFA?

Dynamiczne XFA w PDFium Component wymaga builda V8/XFA biblioteki natywnej, wybieranego globalną zmienną EnableV8Engine z modułu PDFium przed wczytaniem pierwszego dokumentu. Proces wiąże się z jedną biblioteką DLL przy pierwszym wczytaniu biblioteki przez dowolny TPdf, a zwykły build PDFium nie uruchomi silnika XFA w ogóle. Przy otwarciu dokumentu TPdf zajrzyje do pliku pod kątem znaczników XFA i przełączy się na build V8 automatycznie, ale tylko jeśli żaden zwykły nie został jeszcze wczytany w tym procesie. Gdy związanie poszło już złą stroną, TPdf.OnXfaRuntimeMissing odpala się raz, żeby gospodarz mógł kazać użytkownikowi zrestartować aplikację. Jawne ustawienie flagi na starcie usuwa zgadywanie. Struktura callbacków FPDF_FORMFILLINFO niosąca zdarzenia XFA też musi pasować do biblioteki DLL; tło opisuje FPDF_FORMFILLINFO wersja 2 i ABI callbacków XFA, a wykrywanie formularzy XFA i czytanie ich pakietów pokazuje, jak odróżnić typy formularzy, zanim otworzysz viewer

uses
  PDFium;

procedure TClaimForm.FormCreate(Sender: TObject);
begin
  // Zdecyduj, zanim pierwszy TPdf wczyta bibliotekę natywną:
  // proces nie może później przejść z pdfium.dll na pdfium.v8.dll
  EnableV8Engine := True;

  FPdf := TPdf.Create(nil);
  FPdf.OnXfaRuntimeMissing := PdfXfaRuntimeMissing;
  FPdf.OnXfaPageCountChanged := PdfXfaPageCountChanged;
  FPdf.FileName := 'C:\Forms\expense-claim.pdf';
  FPdf.Active := True;

  PdfView1.Pdf := FPdf;
  PdfView1.OnPageChange := PdfViewPageChange;
  PdfView1.Active := True;

  UpdatePageRange(FPdf.PageCount);
end;

procedure TClaimForm.PdfXfaRuntimeMissing(Sender: TObject);
begin
  StatusBar1.SimpleText :=
    'This XFA form needs the V8 runtime; restart the application to enable it';
end;

Dlaczego PageCount raportuje 1 dla formularza o dwóch stronach?

Wrapper, który zapisuje argument page_count natywnego zdarzenia strony jako sumę dokumentu, myli się, bo ten argument to w rzeczywistości bezwzględna różnica między nową a starą liczbą stron. PDFium podnosi FFI_PageEvent po zakończeniu przebiegu layoutu z typem zdarzenia strona dodana albo strona usunięta; wewnętrznie najpierw aktualizuje swoją zapamiętaną liczbę stron, a potem przekazuje abs(new - old). Przy początkowym layoutcie stara liczba to zero, więc delta równa się sumie, i trójstronicowy statyczny przykład zgłasza trzy strony, jak trzeba. Dokładnie dlatego formularze testowe o stałej długości nigdy nie obnażają tego błędu. Gdy dynamiczny formularz pierwszy raz urośnie z jednej strony do dwóch, delta wynosi 1, i taki wrapper raportuje liczbę stron 1. Usunięcie wiersza z trójstronicowego formularza produkuje ten sam rodzaj bezsensu w drugą stronę

Sumowanie delty na poprzednią wartość to też nie jest bezpieczna łata. Kolejność callbacków inicjalizacji i layoutu oznacza, że wrapper nie zawsze może ufać swojej wcześniejszej liczbie jako bazy, więc biegnąca suma może dryfować. Callback PDFium Component dlatego ignoruje argument jako liczbę i woła FPDF_GetPageCount na dokumencie, który czyta sumę z layoutu, właśnie co ukończonego. Potem czyści cache'owane sceny stron, zapisuje tę sumę jako nadpisanie liczby stron XFA za TPdf.PageCount i dopiero po tym podnosi OnXfaPageCountChanged. Kiedy twój handler się wykonuje, NewCount i FPdf.PageCount się zgadzają

Diagram dynamicznego XFA w PDFium Component, gdzie dodanie wiersza repaginuje formularz z jednej strony na dwie, a FFI_PageEvent przekazuje abs(nowo minus staro) jako deltę, więc traktowanie jej jako sumy raportowałoby liczbę stron 1, podczas gdy PDFium Component czyta FPDF_GetPageCount i zgłasza poprawną sumę
Natywne zdarzenie strony raportuje deltę dodano/usunięto, a nie sumę, więc PDFium Component ignoruje argument i czyta ukończony layout, zanim podniesie OnXfaPageCountChanged
procedure TClaimForm.PdfXfaPageCountChanged(Sender: TObject; NewCount: Integer);
begin
  // NewCount to suma ukończonego layoutu, nigdy delta.
  // To wykonuje się wewnątrz callbacka layoutu PDFium: aktualizuj tylko stan UI gospodarza,
  // nie zamykaj dokumentu ani nie wczytuj stron stąd
  UpdatePageRange(NewCount);
end;

procedure TClaimForm.PdfViewPageChange(Sender: TObject);
begin
  // Odpala się po każdym ponownym wczytaniu strony, łącznie z odroczonym odświeżeniem XFA
  PageSpin.Value := PdfView1.PageNumber;
end;

procedure TClaimForm.UpdatePageRange(Count: Integer);
begin
  PageSpin.MinValue := 1;
  PageSpin.MaxValue := Count;
  PageLabel.Caption := Format('of %d', [Count]);
end;

Zdarzenie odpala się wyłącznie dla formularzy Full XFA, których layout zmienia się w trakcie działania. Statyczne XFA i dokumenty AcroForm nigdy go nie podnoszą, więc viewer obsługujący oba może zostawić ten sam handler podpięty. Pozostawienie go niepodpiętym też jest bezpieczne; nadpisanie za TPdf.PageCount działa tak czy inaczej, a zdarzenie istnieje po to, żeby gospodarz odświeżył to, co cache'ował

Dlaczego pole wprowadzania zostaje na starej stronie, gdy pole się przeprowadza?

Obramowanie się przeprowadza, a edytor nie, gdy natywny notyfikator XFA porównuje prostokąt z nim samym. Gdy layout zmienia geometrię widgeta już wczytanego, PDFium powinien zauważyć nowy prostokąt i zawołać PerformLayout na widgetcie, co przestawia edytor tekstu i jego obszar trafień. Sprawdzenie porównujące GetWidgetRect() z RecacheWidgetRect() nie może nigdy odpalić: obie funkcje zwracają const referencję do tego samego pola, a recache nadpisuje to pole w miejscu, więc porównanie zawsze widzi dwie identyczne wartości i wczytane widgety pomijają swój relayout

Objaw wychodzi na jaw, gdy zmiana wysokości subformu sprawia, że istniejące pola przeskakują na następną stronę: obramowanie pola jest rysowane na nowym miejscu, podczas gdy wpisany tekst i obszar trafień myszy siedzą na poprzedniej współrzędnej Y. Jawne wymuszenie relayoutu nie pomaga, i ponowne wczytanie strony też nie, bo widget nadal wierzy, że jego geometria jest aktualna. Biblioteki Windows V8 rozprowadzane z PDFium Component kopiują stary prostokąt przez wartość przed recachowaniem i porównują tę kopię, więc przeprowadzone widgety robią relayout, a edytowana wartość pojawia się dokładnie tam, gdzie jest obramowanie. Sprawdzenie mieszka w kodzie natywnym i podróżuje z bibliotekami DLL, więc rozprowadzaj pdfium.v8.dll razem z modułami Pascala. Żeby przetestować samodzielnie, najpierw ustaw w przeżywającym wierszu wartość inną niż domyślna, a potem szukaj tej wartości w nowym położeniu pola, bo wiersz przebudowany z wartościami domyślnymi wyglądałby inaczej na zaliczony

Diagram relayoutu widgetów w PDFium Component zestawiający porównanie samego siebie, gdzie GetWidgetRect i RecacheWidgetRect zwracają jedno wspólne pole, więc przeprowadzone widgety pomijają PerformLayout, z kontrolą kopiowania przez wartość w bibliotekach Windows V8, która przestawia edytor i obszar trafień myszy na przerysowane obramowanie
Porównanie prostokąta z nim samym nigdy nie wykryje zmiany, więc obramowanie się przeprowadza, a wpisany tekst i kliki zostają, dopóki sprawdzenie najpierw nie zachowa kopii przez wartość

Jak TPdfView wczytuje strony ponownie, nie wyrywając uchwytu sprzed PDFium?

TPdfView odracza ponowne wczytanie strony następujące po zmianie layoutu XFA, aż natywny stos wywołań się rozwinie. Zdarzenie strony zwykle odpala się, gdy PDFium wciąż przetwarza wejście: użytkownik kliknął przycisk Dodaj wiersz, klik wykonał skrypt, skrypt zmienił liczbę instancji, a layout skończył się wewnątrz tego samego natywnego wywołania. Zamknięcie i ponowne otwarcie uchwytu strony w tym momencie uwolniłoby obiekt, którego wołający wciąż używa. Viewer, który w tym punkcie tylko unieważnia siebie, trzyma uchwyt strony wskazujący na stan sprzed layoutu, a jeśli użytkownik był na ostatniej stronie, gdy ta zniknęła, wybrany numer strony jest poza zakresem

Odroczone odświeżanie działa w kilku małych krokach, które tłumaczą zachowanie widziane od strony gospodarza:

  1. callback zdarzenia strony oznacza widok jako mający oczekujące odświeżenie layoutu XFA i wysyła prywatny komunikat okienkowy; powtórzone zdarzenia przed dotarciem komunikatu scaliłyby się w jedno odświeżenie
  2. widok bez uchwytu okna trzyma na razie flagę oczekującą i wysyła komunikat z CreateWnd, a zmiana dokumentu, deaktywacja widoku albo jego zniszczenie czyszczą flagę
  3. gdy komunikat dociera, widok czyści zaznaczenie tekstu, podświetlenie wyszukiwania i indeks pola z fokusem, bo wszystkie trzy odnosiły się do starego layoutu
  4. wybrana strona jest przycinana do nowego PageCount; zmieniony numer strony idzie przez normalne przełączenie strony, w przeciwnym razie bieżąca strona jest wczytywana ponownie, a tryb dopasowania stosuje się jeszcze raz
  5. jeśli layout nie zostawia żadnych stron, widok wyładowuje stary uchwyt strony, zamiast rysować stronę, która już nie istnieje
Diagram odroczonego odświeżenia XFA w TPdfView w PDFium Component, gdzie zdarzenie strony wewnątrz natywnego stosu wywołań layoutu tylko oznacza oczekujące odświeżenie i wysyła komunikat okienkowy, który później czyści nieaktualny stan zaznaczenia, przycina stronę do nowego PageCount i wczytuje ponownie albo wyładowuje uchwyt strony
ponowne wczytanie czeka, aż natywny stos wywołań się rozwije: wysłany komunikat scala powtórzone zdarzenia, potem widok przycina stronę, wczytuje ją ponownie i podnosi OnPageChange

To samo ograniczenie dotyczy twojego własnego kodu. OnXfaPageCountChanged wykonuje się wewnątrz natywnego callbacka layoutu, więc traktuj go jak powiadomienie: aktualizuj tam etykiety, zakresy spinerów i stan paska narzędzi, a wszystko cięższe, jak zamknięcie dokumentu albo otwarcie innego, kolejkuj wysłanym komunikatem, żeby wykonało się po powrocie callbacka. TPdfView.OnPageChange mówi ci potem, kiedy widok faktycznie wczytał stronę ponownie, a odczyt PdfView1.PageNumber w tym momencie daje wartość przyciętą. Nawigowanie Tabem i sprawdzenia FormType, które viewer formularzy robi przy otwarciu, opisuje nawigacja po polach formularzy PDF z PDFium Component

Jak viewer traktuje strony Full XFA, które nie mają warstwy tekstu?

Strony Full XFA nie mają tekstowej strony PDF, więc cokolwiek, co o taką stronę prosi, zawodzi z błędem Cannot open text page. Domyślne zaznaczanie tekstu i wykrywanie linków w viewerze oba sięgają do tej warstwy: przy TPdfView.AllowUserTextSelection na domyślnym True najechanie proszi warstwę tekstu o znak pod myszą, a kliknięcie puszczenia myszy uruchamia automatyczną sondę URL po tekście strony. W TPdfView obie wewnętrzne ścieżki zwracają brak wyniku, gdy TPdf.FormType to ftXfaFull, a runtime XFA jest dostępny, więc ustawienia domyślne działają, a wprowadzanie w pola zostaje dostępne

Wyłączenie AllowUserTextSelection dla dokumentów Full XFA to rozsądny wybór w UI, bo nie ma tekstu strony do zaznaczenia, a gesty przeciągania nie powinny startować trybu zaznaczania

procedure TClaimForm.ConfigureViewerForForm;
begin
  // FormType czyta otwarty dokument, więc wołaj to po FPdf.Active := True
  if FPdf.XFA and (FPdf.FormType = ftXfaFull) and FPdf.XfaRuntimeAvailable then
  begin
    // Na stronach Full XFA nie ma warstwy tekstu PDF; pola zostają edytowalne
    PdfView1.AllowUserTextSelection := False;
    StatusBar1.SimpleText := Format('Dynamic XFA form, %d page(s)',
      [FPdf.PageCount]);
  end
  else
    PdfView1.AllowUserTextSelection := True;
end;

Pisanie po zaznaczeniu potrzebuje własnej obsługi. Natywny edytor tekstu XFA nie zastępuje zaznaczenia, gdy dostaje znak: FORM_OnChar wstawia przy kursorze, a Backspace kasuje pojedynczy znak, więc przepuszczenie klawiszy wprost postawiłoby stary i nowy tekst obok siebie. PDFium Component pamięta, że klik wylądował na polu tekstowym XFA, i kieruje wpisane znaki, Backspace oraz Delete przez FORM_ReplaceSelection zawsze, gdy zaznaczenie istnieje, a dokument daje prawo wypełniania formularzy albo modyfikacji. O tym, czy pole XFA tylko do odczytu może się zmienić, decyduje edytor natywny, więc pole oznaczone w formularzu jako read-only trzyma swoją wartość nawet w dokumencie, który poza tym pozwala wypełniać. Ustawienie TPdfView.AllowFormEvents na False też zatrzymuje to kierowanie klawiatury, co sprawia, że viewer przeznaczony tylko do odczytu taki pozostaje

Ściąga: dynamiczne XFA w viewerze Delphi

ObjawPrzyczynaObsługiwane przez
Liczba stron pokazuje 1, gdy formularz urośnie do dwóch stronNatywne zdarzenie strony przekazuje deltę dodano/usunięto, nie sumęTPdf.PageCount czyta ukończony layout
Obramowanie pola się przeprowadza, wpisany tekst i obszar trafień zostająWczytany widget pomija relayout po porównaniu samego siebieKontrola z kopią przez wartość w bibliotekach Windows V8
Viewer rysuje albo kieruje wejście do stanu strony sprzed layoutuUchwyt strony niewczytany ponownie po repaginacjiOdroczone odświeżanie w TPdfView
Klik w pole prosi o tekstową stronę, która nie istniejeZaznaczanie tekstu i sonda URL na stronach bez warstwy tekstuŚcieżki tekstu zwracają brak wyniku na stronach ftXfaFull
Pisanie po zaznaczonej wartości dokleja zamiast zastępowaćNatywny edytor XFA wstawia przy kursorzeKlawisze kierowane przez FORM_ReplaceSelection
  • Ustaw EnableV8Engine na True, zanim jakikolwiek dokument się wczyta, i obsłuż OnXfaRuntimeMissing na wypadek, gdy najpierw wczytano bibliotekę zwykłą
  • Czytaj sumę z TPdf.PageCount albo z parametru NewCount OnXfaPageCountChanged; nigdy nie dodawaj ani nie odejmuj liczb stron samodzielnie
  • Trzymaj handler OnXfaPageCountChanged lekki, bo wykonuje się wewnątrz natywnego callbacka layoutu
  • Synchronizuj wskaźnik bieżącej strony w TPdfView.OnPageChange, które odpala się po tym, jak odroczone ponowne wczytanie przycina numer strony
  • Rozprowadzaj biblioteki DLL Windows V8 razem z modułami; kontrola relayoutu widgetów mieszka w kodzie natywnym
  • Testuj na formularzu, który faktycznie zmienia liczbę stron i przenosi edytowane pole przez łamanie strony, bo próbki o stałej długości ukrywają każdy problem z tej listy

Dynamiczne XFA zamienia liczbę stron i geometrię pól w wartości żywe, a viewer pozostaje poprawny tylko wtedy, gdy bierze je z ukończonego layoutu i wczytuje strony ponownie w bezpiecznym momencie. PDFium Component załatwia jedno i drugie wewnątrz TPdf i TPdfView, więc gospodarz musi tylko słuchać. Szczegóły i pobieranie są na stronie produktu PDFium Component for Delphi