Teknik Makale

Delphi'de PDF İçeriğini Duyarlı HTML'ye Yeniden Akıtma

Etiketli PDF kutusu işaretsiz bırakılarak bir kelime işlemciden dışa aktarılmış bir sözleşme, ekranda hâllâ yapılandırılmış görünür: 24 pointlik bold bir başlık, numaralı maddeler, çizgili bir ücret cetveli. Yeniden akışa uygun HTMLye çevirdiğinizde ücret cetveli düzgün bir <table> olarak döner ama başlık, dipnotla tamamen aynı konumda bir <p>dir. O çıktı doğrudur. ISO 32000-1 §14.8, bir PDFe "bu metin dizisi bir başlıktır" demek için tam olarak tek bir yer verir: structure tree; ve etiketsiz bir dosyada o yoktur. Font boyutu ve kalınlık dizgi tercihleridir ve her büyük kalın satırı bir <h1>e çeviren bir dönüştürücü, alıntı bloklarını, tablo toplamlarını ve antetlerdeki şirket adını da yükseltir

Her PDF-to-HTML hattına sorulmaya değer soru, çıktısındaki her başlığın, liste ögesinin ve tablonun nereden geldiği ve her birinin bir telefon düzeni, bir ekran okuyucu ya da bir arama indeksleyici tarafından ne kadarına güvenilebildiğidir. Başlıklar ile tablolar farklı cevaplar verir. Dışa aktarma adımı, satır kırılımı, karakter kodlaması ve bellek hakkında kendi tercihlerini ekler

PDFium Component reflow hattının Delphi şeması: GetStructuredText, ya etiketli structure treei ya da düzen okuma sırasını BuildReflowDocumenta besler ve kendi kendine yeten bir ToHtml dışa aktarma üretir
Yeniden akış modelindeki her düğüm aynı yapılandırılmış metin katmanına izlenir; rolü structure tree tarafından mı bildirildi ya da blok düz düzen sırasına mı düştü, fark etmez

Başlıklar ve listeler nereden gelir?

PDFium Component yeniden akış modelini TPdf.BuildReflowDocumentle kurar ve o metot her kelimeyi, bloğu ve anlamsal ipucunu yapılandırılmış metin blokları ve okuma sırası yazısında anlatılan GetStructuredTextten alır. Arkasında ikinci bir parser ya da ikinci bir metin çıkarıcı yoktur. İstenen aralıktaki her sayfa için blokları fiziksel düzen sırasında toplar. GetStructuredText, her bloğu sayfanın etiketli içeriğiyle çakışan alana göre zaten eşlemiştir ve BuildReflowDocument bulduğu rolü bloğa kopyalar: Hden H6ya başlık olur (seviyesiyle), LI, Lbl ve LBody liste ögesi olur, Figure metni alternatif açıklama olan bir şekil olur ve Caption altyazı olur

İki sonuç çıkar ve ikisi de kolayca gözlenir. Blok sırası daima sayfa düzenini izler; etiketli bir dosyada bile. Etiketler bir bloğun ne olduğunu belirler, geometri nereye gideceğini. Etiketsiz bir sayfada ise her blok bir paragraftır. Başlıklar ve listeler font boyutundan asla tahmin edilmez

Her düğüm, TPdfReadingOrderSource türünde bir Source alanı taşır: rol structure treeen geldiyse rosStructure, yalnızca düzenden geldiyse rosHeuristic. Dışa aktarılan HTML bunu her ögede data-source="structure" ya da data-source="inferred" olarak yineler ve belge düzeyindeki TPdfReflowDocument.Source, ancak aralıktaki her sayfa etiketliyse rosStructuredur. Tablolar daima rosHeuristicdir; Table etiketlerinden değil geometrik algılamadan geldikleri için. Bir alt adım başlıkları gezinme işaretçisi sayıyorsa o alanı önce kontrol edin; etiketli bir belge, yazarın seçtiği işaretçileri verir

Nesne ağacı yerine düz bir düğüm dizisi

TPdfReflowDocument.Nodes, ön-sıra ile düzleştirilmiş bir ağaçtır: her biri ParentIndex ile Depth tutan TPdfReflowNode kayıtlarından tek bir dinamik dizi. Sayfa düğümleri derlik 0da, üst dizini -1 ile durur. Paragraflar, başlıklar, şekiller, altyazılar, listeler ve tablolar derlik 1de sayfaya asılıdır; liste ögeleri derlik 2de kendi listesinin altındadır ve tablo hücreleri bir satırın altında derlik 3e ulaşır. Bitişik liste ögeleri tek bir liste düğümünü paylaşır; aralarına giren başka bir blok ya da bir tablo yeni liste başlatır

Düz yerleşim bir taşınabilirlik kararıdır. Kendisinin dinamik dizisini içeren özyinelemeli bir kayıt, Delphi ile C++Builder ve Free Pascal altında derlenir ama üçü de özyinelemeli yönetilen türleri paket ya da DLL sınırının ötesinde farklı ele alır. Düz kayıtlardan oluşan bir dizi üçünde de aynı davranır ve tek bir for döngüsüyle, özyinelemesiz akıtılabilir

uses
  SysUtils, PDFium;

var
  Pdf: TPdf;
  Options: TPdfReflowOptions;
  Doc: TPdfReflowDocument;
  Node: TPdfReflowNode;
  I: Integer;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'contract.pdf';
    Pdf.LoadDocument;

    Options := TPdfReflowOptions.Default;   // tüm sayfalar, tablolar açık, CSS açık
    Doc := Pdf.BuildReflowDocument(Options);

    for I := 0 to High(Doc.Nodes) do
    begin
      Node := Doc.Nodes[I];
      case Node.Kind of
        prnkHeading:
          Writeln(Format('%sH%d [%s] %s', [StringOfChar(' ', Node.Depth * 2),
            Node.HeadingLevel,
            BoolToStr(Node.Source = rosStructure, True), Node.Text]));
        prnkTable:
          // bir tablo düğümünde RowSpan/ColumnSpan tablonun satır ve sütun sayılarını tutar
          Writeln(Format('%stable %dx%d, page %d, confidence %.2f',
            [StringOfChar(' ', Node.Depth * 2), Node.RowSpan, Node.ColumnSpan,
             Node.PageNumber, Node.Confidence]));
      end;
    end;

    Writeln(Format('%d node(s), %d table(s), %d character(s), pages %d-%d',
      [Length(Doc.Nodes), Doc.TableCount, Doc.CharacterCount,
       Doc.FirstPage, Doc.LastPage]));
  finally
    Pdf.Free;
  end;
end;

Açılıştaki etiketsiz sözleşmede o döngü hiç H satırı basmaz ve algılanan her ücret cetveli için bir tablo satırı basar. Aynı belgenin etiketli bir kopyasında çalıştırın, başlıklar yanında True ile görünür. Seçeneklerdeki FirstPage ile LastPage öntanımlı 0dır — belgenin ilk ve son sayfası demektir; sayfa sayısının dışında bir aralık, hiçbir sayfa okunmadan bir EPdfError fırlatır

Tablo metni neden iki kez görünmez?

Tablo algılama, yapılandırılmış metin toplandıktan sonra her sayfada koşar; yani bir tablonun içindeki kelimeler iki kez vardır: bir kez metin blokları olarak, bir kez hücreler olarak. İkisini de yayarsanız HTMLdeki her tabloyu, kendi içeriği gevşek paragraflar olarak yeniden izler; saf bir "tabloları metne ekle" birleştirmesinin ürettiği tam olarak budur

Model bunu geometrik çözer. Sınırlayıcı kutusunun en az yarısı algılanmış bir tablonun sınırlarının içinde duran bir metin bloğu düşürülür ve tablo düğümü onun yerine geçer. Tablolar sonra kalan bloklarla dikey konuma göre araya girer (sayfada yukarıda olan önce; üst kenarlar yarım point içindeyse soldan sağa eşitlik bozucu olarak), böylece bir tablo, üstündeki paragraf ile altındaki paragrafın arasına düşer, sayfanın sonuna eklenmez

Delphi reflow için PDFium Component tablo algılamasındaki geometrik kuralın şeması: metin bloğunun en az yarısını kapsayan bir tablo onun yerine geçer, böylece hücre metni asla iki kez görünmez
Algılanan bir tablo bir metin bloğunun en az yarısını kapsadığında tablo düğümü bloğun yerine geçer ve hücre metni tam olarak bir kez görünür

Yarım alan eşiğinin görünen bir kenarı vardır. Tablo sınırını biraz aşan ve çoğunlukla tablonun dışında duran bir blok bozulmadan hayatta kalır; bir metin satırı arada hem son satırda hem onu izleyen paragrafta görünebilir. Hata edilecek doğru taraf budur. Her çakışan bloğu kaldıracak kadar düşük bir eşik, bir tablonun sınırlayıcı kutusuna yalnızca değen gövde metnini de siler ve ikilenmiş bir satır, eksik bir cümleden çok daha kolay fark edilir ve affedilir

Algılanan tablolar bir güven puanı taşır ve iki algılama stratejisi farklı bantlara düşer. Çizgilerinden bulunan bir tablo, hücrelerinin kaçının metin tuttuğuna göre 0,88 ile 1,0 arasında puan alır. Tamamen boşluk hizalamasından çıkarılan bir tablo 0,58 ile 0,88 arasında puan alır. Tablo düğümünün Confidenceı o puanı tutar; her hücre düğümü onu yineler ve HTML, <table> ögesinde data-confidence olarak yazar. TableOptions.MinConfidencein (öntanımlı 0,5) altındaki tablolar hiç kurulmaz ve bir tablo reddedildiğinde kelimeleri sıradan paragraflar olarak modelde kalır

Bir arama indeksi ya da mobil okuma görünümü için yanlış bir tablo az kaybettirir, doğru algılanmış biri büyük kazançtır; öntanımlıları bırakın. İki sütunlu bir adres bloğu etrafında uydurulmuş bir ızgaranın ızgarasız olmaktan kötü olduğu arşiv dönüşümünde algılamayı çizgili tablolara kısıtlayın:

Options := TPdfReflowOptions.Default;
Options.DetectTables := True;
Options.TableOptions.DetectWhitespaceTables := False; // yalnızca çizgili tablolar
Options.TableOptions.MinConfidence := 0.9;            // seyrek çizgili ızgaraları da bırak
Options.TableOptions.MaxTables := 200;                // belge çapı tavan
Options.TableOptions.MaxCells := 50000;               // belge çapı tavan

Doc := Pdf.BuildReflowDocument(Options);
if Doc.TableCount = 0 then
  Writeln('No ruled tables; all page text is emitted as paragraphs');

Bir yeniden akış kurulumunda MaxTables ile MaxCells, sayfa başına değil tüm sayfa aralığı üzerinden sayılır; her sayfasında çizgili bir tablo olan 300 sayfalık bir ekstre, en az 300 MaxTables ister ya da kurulum, sınırı aşan ilk tabloda EPdfError ile durur. Öntanımlılar 1000 tablo ve 100000 hücredir

Kenarlık olarak çizilmiş ince dolu dikdörtgenler ve sayfalar arası devamlılık dâhil, algılama tarafının kendisi için tablo algılama ve çıkarma yazısına bakın

Başka hiçbir şeye ihtiyaç duymayan HTML dışa aktarma

TPdfReflowDocument.ToHtml, çoktan kurulmuş modeli yürür ve PDFiuma bir daha dokunmaz; aynı modeli iki kez dışa aktarmak aynı diziyi verir. FullDocument kuruluysa (öntanımlı) sonuç eksiksiz bir sayfadır: doctype, <meta charset="utf-8">, bir viewport meta etiketi, belgenin Title girdisinden alınan bir <title> (boşsa "PDF document") ve belgenin dilinden bir lang niteliği. FullDocument kapalıyken kendi şablonunuza yerleştireceğiniz tek bir <div class="pdf-reflow"> parçası alırsınız

IncludeCssten gelen isteğe bağlı stil sayfası tek bir satır içi <style> bloğudur: 72remlik bir okuma sütunu, IncludePageSections açıkken beyaz kart olarak her PDF sayfası, çöktürülmüş tablo kenarlıkları ve 40rem altında kart dolgusunu kaldırıp tablo metnini küçülten bir media query. Script yok, web fontu yok, dış URL yok; dosyanın bir e-postanın içinde, CHM tarzı bir yardım görüntüleyicide ya da kum havuzlu bir tarayıcı kontrolünde oturmasını sağlayan budur. 1 ile 6 dışındaki başlık düzeyleri h2 yazılır, başlık hücreleri th olur ve RowSpan ya da ColumnSpanı 1in üstünde olan hücreler rowspan ile colspan alır. IncludeGeometryyi açmak, PDF pointlerinde data-left, data-top, data-right ile data-bottom ekler; render edilmiş sayfada bir arama isabetini vurgulamak için kullanışlıdır

PreserveLineBreaks bilinçli bir seçim ister. PDF paragrafının içindeki bir satır kırılımı tek bir sabit sütun genişliği için yapılmıştır; 360 piksellik bir ekranda tutarsanız her satır iki kez sarar — yeniden akışın var olma sebebi o dağınık deseni gidermektir. Prose için kapalı bırakın (öntanımlı). Kırılımın anlam taşıdığı belgeler için — adresler, manzum ya da kod listeleri — açın; boşluk yerine <br> yazar

Uzun bir belge için bütün sayfayı tek bir WString olarak kurup sonra kodlamak, bellek zirvesini iki katına çıkarır. WriteHtml aynı işaretlemeyi bir TPdfReportWritera akıtır; her ASCII olmayan karakteri sayısal karakter referansı yazarak ASCII yazar, böylece baytlar alıcının kodlamayı nasıl tahmin ettiğinden bağımsız geçerlidir:

uses
  Classes, SysUtils, PDFium, FPdfAsync, FPdfReport;

procedure ExportReflowHtml(Pdf: TPdf; const FileName: string;
  const Token: IPdfCancellationToken);
var
  Options: TPdfReflowOptions;
  Doc: TPdfReflowDocument;
  Limits: TPdfReportLimits;
  Stream: TFileStream;
  Writer: TPdfReportWriter;
begin
  Options := TPdfReflowOptions.Default;
  Options.MaxNodes := 500000;
  Options.MaxCharacters := 20000000;
  Doc := Pdf.BuildReflowDocument(Options, Token);   // page state is restored afterwards

  Limits := TPdfReportLimits.Default;
  Limits.MaxCharacters := 64 * 1024 * 1024;  // output byte ceiling, 64 MiB maximum
  Limits.MaxItems := Options.MaxNodes;       // one item per node, 1048576 maximum

  Stream := TFileStream.Create(FileName, fmCreate);
  try
    Writer := TPdfReportWriter.Create(Limits, Stream);  // stream stays caller owned
    try
      Doc.WriteHtml(Writer);
    finally
      Writer.Free;
    end;
  finally
    Stream.Free;
  end;
end;

WriteHtml, ToHtmlden fazlasını kontrol eder. Options.MaxNodesden fazla düğümlü bir modeli reddeder, yazdığı metne Options.MaxCharacters uygular, yuvalanmayı MaxDepth argümanıyla (öntanımlı 64) sınırlar ve her ParentIndexin daha önceki bir düğümü işaret ettiğini doğrular. Son kontrol, kodunuz dışa aktarmadan önce Nodesu süzüyorsa ya da yeniden yazıyorsa önemlidir: ileriye işaret eden üst dizinli düzenlenmiş bir dizi, etiketleri uyuşmayan işaretleme üretmek yerine EPdfReportLimit fırlatır

Bütçeler, iptal ve güncel sayfa

Bir PDF güvenilmeyen girdidir; bozuk ya da düşmanca bir dosya, minicik metinden binlerce sayfa bildirebilir. BuildReflowDocument, karakter, düğüm, tablo ve hücre bütçelerini her düğüm eklenmeden önce kontrol eder; onları aşan bir dosya, bellek kullanımı hâllâ sınırlıyken, bütçeyi adlandıran bir mesajla (örneğin "Reflow node budget exceeded") EPdfError ile durur. MaxCharacters ile MaxNodesin ikisi de pozitif olmalıdır; öntanımlılar 10.000.000 karakter ve 1.000.000 düğümdür

İsteğe bağlı IPdfCancellationToken, her sayfadan önce, bloklar arasında, her tablodan önce ve her tablo satırından önce kontrol edilir. Formunuzun sahiplendiği bir TPdfCancellationTokenSourceun Tokenını geçirin, düğme handlerından Cancel çağırın ve kurulum, bir sonraki kontrol noktasında EPdfOperationCancelled fırlatır. Onu EPdfErrorden ayrı yakalayın; kullanıcının iptali bozuk dosya olarak loglanmasın. Kurulum hangi exceptionla biterse bitsin eksik bir şey döndürülmez; başarısızlık daha sonra WriteHtmlin içinde olursa hedef dosya kırılmış bir sayfa tutar, kendi exception handlerınızda silin

Sayfa durumu, GUI kodunun yaslandığı ayrıntıdır. Kurulum, PageNumberı hareket ettirerek aralıktaki her sayfayı ziyaret eder ve bir try/finally, arayanın sayfasını başarıda da bütçe başarısızlığında da iptalde de geri koyar. Kullanıcı 340. sayfayı okurken dışa aktarma başlatan bir görüntüleyici, dışa aktarma döndüğünde hâlâ 340. sayfadadır

Yeniden akışın yeri

Yeniden akış çıktısı, arama indeksleme, erişilebilir okuma görünümleri, telefon ekranı ve bir CMS içerik göçü için iyi bir girdidir. Mutlak konumlandırmayı, tam fontları, vektör grafiklerini ve sayfa geometrisini — isteğe bağlı data-* koordinatları dışında — bilerek bırakır. Bir iş sayfanın birebir aynı görünmesini gerektiriyorsa render edin; kelimelerin başka bir yerde okunabilir olmasını gerektiriyorsa yeniden akıtın

Başlıklar ve listeler yalnızca etiketlerden geldiği için HTMLnin kalitesi, yukarı akıştaki etiketlemenin kalitesini izler. PDF/UA structure tree doğrulamasındaki kontrolleri geçen belgeler gerçek başlık hiyerarşisi taşıyan modeller üretir ve aynı etiketli içerik, erişilebilir bir okuyucu kurmadaki okuma özelliklerini de güdür

Yeniden akış, yapılandırılmış metin, tablo çıkarma ve render, Delphi, C++Builder ve Lazarusta aynı TPdf nesnesine karşı koşar; seçenek kayıtları, exceptionlar ve rapor yazıcı, Delphi için PDFium Component ürün sayfasında belgelenmiştir