Teknik Makale

PDFium Component XFA kaydı: satır sonu, emoji, restoreState

Bir XFA talep formundaki boş bir Comments kutusu, içinde bir satır beslemesiyle yeniden açılır. Bir daha kaydedip açtığınızda kutuda ikisi vardır. U+1F642, hafifçe gülümseyen yüz, ile yazılmış bir müşteri adı U+F642 olarak geri gelir; çoğu fontun boş bir dikdörtgen olarak çizdiği özel kullanım alanı bir kod noktası. Üç etki de bir XFA kaydının datasets paketine yazdığı XML’de yaşar ve bunları doğru yapan bir kayıt yolu; layout boşluğunu field değerlerinin dışında tutmaya, tamamlayıcı düzlem karakterlerini eksiksiz surrogate çiftleri olarak taşımaya ve başarısız bir yazımı bozulmuş bir dosya yerine kayıt sonucuyla bildirmeye zorunludur

Hangi PDFium runtime’ı XFA değerlerini kaydeder?

Yalnızca pdfium.v8.dll XFA değerlerini kaydeder; çünkü hem V8 JavaScript motorunu hem de XFA form runtime’ını taşıyan tek PDFium Component derlemesi odur. Bir düzenleme işlendiğinde (field odağı yitirdiğinde ya da ClearFormFieldFocus işlemi zorladığında) o runtime, kaydetme sırasında canlı XFA verisini datasets paketine aktarır; sizin kodunuzda paket düzenlemesi olmadan. Her Windows mimarisi ayrıca V8 ve XFA olmadan derlenen bir pdfium.dll ile gelir; o ise saklanan paketleri okundukları biçimle harfi harfine geri yazar. Field hâlâ odaklıyken yazılan bir değere ne olduğunu XFA field düzenlemelerinin kayıtta neden kaybolduğu yazısı ele alır

Delphi sarmalayıcısı sizin için doğru kütüphaneyi seçmeye çalışır. EnableV8Engine hâlâ False iken ve henüz hiçbir PDFium kütüphanesi yüklenmemişken TPdf, açmak üzere olduğu dosyaya bakar ve XFA işaretleri bulursa (AcroForm sözlüğünde bir /XFA girdisi ya da katalogda /NeedsRendering true) yüklemeden önce EnableV8Engine’i açar. Bu değişim işlem başına yalnızca bir kez çalışır. Oturumun ilk belgesi sıradan bir PDF olduğu için sıradan bir pdfium.dll hâlihazırda yerleşikse işlem ona bağlı kalır ve sonradan bir XFA belgesi geldiğinde TPdf.OnXfaRuntimeMissing tetiklenir

Varsayılan arama sırası sorunun diğer yarısıdır. LibraryName’de bir dizin yoksa yükleyici, uygulama klasörünün ya da üstlerinden birinin altındaki DLLs\Win32 ya da DLLs\Win64 klasörüyle başlar; dolayısıyla daha eski bir pdfium.v8.dll önce bulunabilir. Bir dizin içeren bir LibraryName tam olarak o dosyayı sabitler ve dosya eksikse yükleme başarısız olur

uses
  System.SysUtils, PDFium;

procedure SelectXfaRuntime;
begin
  // LibraryName’deki bir dizin tam bu dosyayı sabitler;
  // eksik bir dosya başka yerde aramak yerine LoadLibrary’nin başarısız olmasına yol açar
{$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;  // ilk XFA kaydında değil başlangıçta başarısız ol
end;

Bir belge açıldıktan sonra TPdf.XFA dosyanın XFA içerdiğini, TPdf.XfaRuntimeAvailable ise yüklenen kütüphanenin bu belge için XFA motorunu gerçekten başlatabildiğini söyler. Statik ve dinamik formlar TPdf.FormType üzerinden ayırt edilir; dinamik form için ftXfaFull, statik için ftXfaForeground döndürür. V8 runtime’ı olmayan bir makinede paket düzeyinde yoklama, XFA formlarını saptama ve Delphi’de XFA paketlerini çıkarma yazısının konusudur

Kaydedilen XFA field’ları neden fazladan satır beslemeleri kazanabilir?

Kaydedilen XFA field’ları, yazıcı XML’ini her başlangıç etiketinden sonra bir satır sonuyla güzel biçimlendirdiğinde satır beslemeleri kazanır. Bir XFA kaydında iki yazıcı devrededir, genel XML element yazıcısı ile form paketi serileştiricisi ve ikisi de çıktıyı alışkanlıkla böyle biçimlendirir. Çoğu XML belgesinde o boşluk kozmetiktir. XFA verisinde ise değerin kendisidir: datasets paketi yeniden ayrıştırıldığında <Comments> ile </Comments> arasındaki her karakter, satır sonu dâhil, field’e aittir

Yazıcının başlangıç etiketlerinden sonra satır sonu eklediği, yeniden açılan parser’ın Comments etiketleri arasındaki LF’yi field değeri diye okuduğu ve yazıcı yalnızca kendisinin sentezlediği boşluğu kaldırmadıkça her sonraki kaydın bir satır beslemesi daha eklediği PDFium Component XFA kayıt döngüsü şeması
Bir kaydet-yeniden açma döngüsü ilk satır beslemesini ekler ve her sonraki tur bir tane daha ekler; kayma tam biçimini bu yüzden yalnızca ikinci nesilde gösterir

Boş bir field bu yüzden tek bir LF ile yeniden açılır. Her sonraki kaydetme, hâlihazırda duran LF’nin çevresini biçimlendirir; böylece kimsenin dokunmadığı bir field, her inceleme turunda bir satır büyür

Yüklemede değerleri kırpmak ucuz bir tamir gibi görünür ve gerçek veriyi bozardı. İnsanlar XFA field’larına baştaki boşlukları, sondaki boşlukları ve kasıtlı satır sonlarını yazar; bir adres bloğu satır yapısını korumalı, sabit genişlikli bir referans kodu bayt bayt hayatta kalmalıdır. PDFium Component’teki XFA yazıcıları bunun yerine yalnızca serileştiricinin etiketlerin çevresinde kendisinin sentezlediği boşluğu düşürür. Kullanıcı değerleri, dosyada hâlihazırda olan metin düğümleri ve CDATA bölümleri değişmeden geçer; böylece " indented" girintili kalır ve kasıtlı boş bırakılmış bir field boş kalır

Emoji, surrogate çiftleri ve 16 bitlik wchar_t

Bir emoji, bir çözümleme yolu eksiksiz bir Unicode skaler değerini tek bir wchar_t’e, Windows’ta 16 bit genişliğinde olan bu türe, sığdırdığında başka bir karakter olarak geri gelir. Bir XFA yüklemesinde bu tuzağa maruz iki yer vardır: UTF-8 akış çözücüsü ve &#x1F642; gibi sayısal karakter referanslarının çözümleyicisi. U+1F642 17 bit ister. 16 bit’e sıkıştırırsanız üstteki bit dökülür ve geriye Private Use Area’da U+F642 kalır

Bir form serileştiricisi ters yönde başarısız olabilir. Karakterleri birer wchar_t süzerek D83D ve DE42 olmak üzere iki surrogate kod birimi görür; her biri tek başına geçersizdir ve ikisini de atar. Emoji form paketinden, gerisinde hiçbir değiştirme karakteri bırakmadan kaybolur

U+1F642’nin UTF-16 çifti D83D DE42 olarak geldiği ve iki naif yolun onu bozabildiği PDFium Component surrogate işleme şeması: 16 bitlik wchar_t çözücüler skaler değeri özel kullanım alanındaki U+F642’ye kısaltırken tek başına duran surrogate’leri süzen bir serileştirici emoji’yi tümüyle düşürür
Windows’ta wchar_t 16 bit genişliğindedir; surrogate çifti gerektiren bir skaler değer, her iki yol da çiftleri birlikte tutmadıkça ya üst yarısını yitirir ya da paketten kaybolur

PDFium Component’te çözücü her skaler değeri eksiksiz tüketir ve düzgün bir surrogate çifti üretir; çıkış tamponunda yalnızca bir birimlik yer kaldığında da, dört baytlık bir UTF-8 dizisi iki okuma bloğuna bölündüğünde de. Çıkış yolunda form aktarıcı geçerli surrogate çiftlerini birlikte tutar ve sayısal karakter referansları da doğru çiftlere çözülür

Latin-1 test verisi bu yolların hiçbirine dokunmaz. Bir XFA formu için round-trip testi, bir metin field’ında U+FFFF üzerinde en az bir karakter ister ve kaydedilen baytlarda dört baytlık F0 9F 99 82 UTF-8 dizisini kontrol etmek, çizilen field’a bakmaktan daha çok şey söyler

Tek-stream XFA ve kayıt sonucu

Tek stream’li bir XFA belgesi düzenlemelerini yalnızca kayıt yolu bir XDP akışını yerinde yeniden yazabiliyorsa korur ve yeniden yazamadığı her girdi kaydı başarısız kılmalıdır. ISO 32000-1 §12.7.8, etkileşimli form sözlüğündeki /XFA girdisinin ya paket adlarıyla akışları dönüşümlü sayan bir dizi ya da bütün XDP belgesini tutan tek bir akış olmasına izin verir. Yalnızca diziler için yazılmış bir kayıt yolu tek akışları reddeder ve çağıran bu sonucu yok sayarsa PDF, form verisi eski değerleriyle yazılır

PDFium Component’teki V8 runtime, tanımlı bir tek-stream alt kümesini üç adımda işler. İki canlı paketi, datasets ile form’u, bir staging alanına aktarır ve doğrular. Ancak ondan sonra özgün XDP içindeki eşleşen paketleri, öteki paketleri ve kök namespace bildirimlerini koruyarak değiştirir. Staging başarısız olursa kalıcı XFA akışına hiç dokunulmaz ve belge değişiklik işaretini korur; böylece sonraki bir kayıt yeniden deneyebilir

Canlı datasets ile form paketlerinin staging’e aktarıldığı, doğrulandığı ve ardından işaretçilerle korunmuş yorumlarla özgün XDP içinde değiştirildiği, staging başarısızlıkları ile DTD ya da XMLDSig gibi girdilerin kaydı açıkça reddettiği PDFium Component tek-stream XFA kayıt hattı
Aşamalı aktarım, herhangi bir şey değiştirilmeden önce doğrulanır; böylece başarısız bir kayıt kalıcı XFA akışına dokunmaz ve belge değişiklik işaretini korur

XML yorumları ve işlem talimatları ek özen ister; çünkü yeniden yazım için kullanılan çözümleyici onları düşürür. Her biri ayrıştırmadan önce özgün bir işaretçiyle değiştirilir ve sonra geri konur; akış, her işaretçi tam bir kez göründüğünde yazılır. Böylece canlı paketlerin dışındaki yorumlar metinlerini ve sıralarını korur

Bazı girdiler için tartışma bile açılmaz, doğrudan reddedilirler ve her red size başarısız bir kayıt olarak ulaşır:

  • Canlı datasets ya da form paketlerinin içindeki yorumlar ya da işlem talimatları; çünkü özgün konumlarını taze aktarılmış içeriğe eşlemenin bir yolu yoktur
  • DTD bildirimleri ve XMLDSig imzaları; çünkü XDP’yi yeniden yazmak bir XML imzasını geçerli tutamaz
  • Geçersiz UTF-8 ya da UTF-16, eksik etiketler, geçersiz karakter referansları, bilinmeyen entity’ler ve hatalı kurgulu işlem talimatları; anında onarılmak yerine reddedilirler

Reddetmek buradaki daha iyi tercihtir. False döndüren bir kayıt yeniden denenebilir, günlüğe yazılabilir ya da birine devredilebilir; oysa sessizce normalize edilmiş bir XDP, onu değiştiren koddan çok uzakta, haftalar sonra bir imzayı ya da aşağı akıştaki bir aktarıcıyı bozabilir. Tek-stream yolunun koruduğu şey XML içerik modelidir, UTF-8 olarak yazılır; kaynak akışın özgün bayt düzeni ve kodlama bildirimi devredilmez

Son tamponlanmış blok

Son tuzak, XFA’nın altında, genel PDF yazıcısında durur. Çıktıyı sabit boyutlu bloklarla tamponlayan bir dosya yazıcısı, sonda eksik bloğu dışarı itmek zorundadır. Bu, belge yazıcısı başarıyı çoktan bildirdikten sonra temizlik kodunda gerçekleşirse, son bloktaki dolu disk ya da G/Ç hatası çağırana asla ulaşmaz ve diskteki dosya kısa kalır. PDFium Component’in her iki runtime’ında da son boşaltım kayıt sonucunun parçasıdır ve XFA değişiklik işareti yalnızca yazım gerçekten başarılı olduktan sonra temizlenir

Delphi tarafı bir katman daha ekler. TPdf.SaveAs, hedefin yanındaki geçici bir dosyaya yazar ve onu yalnızca akış kaydı True döndürdüğünde hedefin üzerine taşır. False bir sonuç önceki dosyayı olduğu gibi bırakır ve son değiş tokuşun başarısızlığı sessizce dönmek yerine bir işletim sistemi hatası fırlatır

Dinamik bir XFA formu neden daha az sayfayla yeniden açılır?

Dinamik bir XFA formu, kök subform’u restoreState="auto" bildirmediğinde daha az sayfayla yeniden açılır ve bu karar form yazarına aittir. XFA 3.3’te kök subform’daki restoreState varsayılan olarak manual’dır. manual altında XFA işlemcisi, kaydedilen form paketinden yalnızca sınırlı durumu geri yükler ve gerisini formun kendi script’lerine bırakır. Field değerleri ile yinelenen subform’ların instance sayıları geri gelir; çalışma zamanında ayarlanan geometrik property’ler gelmez

Kullanıcı doldururken script’i bir subform’u h="450pt"’ye büyüten üç sayfalık bir form düşünün. Kaydedilen form paketi yeni yüksekliği, field değerlerini ve instance sayılarını tutar. Yeniden açılışta layout, şablon yüksekliklerinden yeniden kurulur, subform eski boyuna döner ve içerik iki sayfaya yeniden akar. Şablon otomatik geri yüklemeyi hiç istememişte XFA belirtiminin istediği davranış budur. Bunu kök subform’da bildirmek yeniden açmayı değiştirir:

<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">
      <!-- field’lar; script’ler çalışma zamanında h’yi değiştirebilir ya da instance ekleyebilir -->
    </subform>
  </subform>
</template>

Şablonun sahibi değilseniz dokunmayın: manual modu için kurulmuş bir form, durumunu kendi başlatma script’lerinin kurmasını bekler ve modu altlarında değiştirmek, o script’lerin yazıldığı varsayımları değiştirir. Kullanıcı yazarken canlı yeniden sayfalama ayrı bir mekanizmadır; PDFium Component’in dinamik XFA sayfa sayılarını ve taşınan field’ları nasıl izlediği yazısında anlatılır

Delphi’den bir XFA round-trip’ini denetlemek

Bir XFA kaydı, kaydedilen dosyayı taze bir TPdf instance’ında yeniden açıp saklanan veriyi geri okuyarak doğrulanır; çünkü SaveAs’ten dönen True yalnızca dosyanın yazıldığını söyler. TPdf.GetXfaDatasets, datasets paketini belgede saklandığı hâliyle döndürür, canlı veri modelini değil; bu yüzden kaydetmeden önce okumak, son yüklemenin değerlerini gösterir. Yeniden açtıktan sonra ise yazılanı tam olarak gösterir. Tek-stream bir belgenin ayrıca adlandırılmış paketleri yoktur: PDFium bütün XDP’yi boş adlı tek bir paket olarak bildirir; dolayısıyla GetXfaPacketByName('datasets') ile GetXfaDatasets boş bir dizi döndürür ve aşağıdaki kod, eksiksiz akışa GetXfaFormPackets üzerinden düşer

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;          // paket-dizisi düzeni
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   // tek stream: adı olmayan tek paket
      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);  // kaydedilen XDP çıktısı UTF-8’dir
  finally
    Pdf.Free;
  end;
end;

Kayıt yordamı bekleyen düzenlemeyi işler, SaveAs sonucunu kontrol eder ve yeniden açılan değeri karşılaştırır. TPdf.ClearFormFieldFocus form odağını kaldırır; PDFium, odaklı field’ın düzenleme tamponunu tam da o an işler. TPdf.SetFocusedFormFieldText odaklı field’ı koddan doldurabilir ama odak izlemeyi widget annotation’ları üzerinden yapar; dinamik bir XFA sayfasında o genellikle yoktur. Orada False döndürür ve metin normalde TPdfView’deki klavye girişiyle gelir

// XmlText kendi eklediğiniz bir yardımcıdır; PDFium Component’in parçası değildir
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
  // İsteğe bağlı scriptli doldurma; False, izlenen hiçbir field’ın odaklı olmadığı anlamına gelir
  if (Pdf.FocusedFormFieldIndex >= 0) and
     not Pdf.SetFocusedFormFieldText(Expected) then
    raise EPdfError.Create('Could not write the focused field');

  Pdf.ClearFormFieldFocus;              // düzenleme tamponunu işle
  if not Pdf.SaveAs(FileName) then      // False: önceki dosya yerinde bırakılır
    raise EPdfError.CreateFmt('Saving %s failed', [FileName]);

  // Taze bir TPdf’te yeniden açıp tam element metnini ara
  Saved := ReadSavedXfaData(FileName);
  if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
    Saved) = 0 then
    raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;

Alt dizi testi yalnızca bir duman testidir. Boş bir element <Tag/> olarak yazılabilir, veri elementleri attribute taşıyabilir ve & ile < ötesindeki kaçış serileştiricinin takdirine kalmıştır; üretim kontrolleri gerçek bir XML çözümleyicine ait olur. Yordamı aynı girdiyle üst üste iki kez çalıştırın; çünkü satır sonu kayması tam biçimini yalnızca ikinci nesilde gösterir

XFA runtime’ını doğrudan süren ana uygulamalar, runtime’ın beklediği callback düzenini de bilmek zorundadır; konusu FPDF_FORMFILLINFO sürüm 2 ve Delphi’de XFA ABI’si yazısıdır. Win32 ile Win64 için her iki Windows runtime’ı, Delphi ve C++Builder sarmalayıcısı ve TPdfView görüntüleyici kontrolü, Delphi ve C++Builder için PDFium Component ile birlikte gelir