Teknik Makale

Delphi'de Etiketli Çıktıyla Bildirimsel PDF Yerleşimi

4. sayfanın dibinde başlayıp 5. sayfanın tepesinde biten bir paragraf, onu okuyan kişi için tek paragraftır. Etiketli bir PDF'te ise bu paragraf iki content stream'te yaşar ve her sayfa kendi işaretli içerik dizilerini kendisi numaralandırır; bu yüzden yapı ağacının, /K dizisi diyelim ki 4. sayfada MCID 7'yi, 5. sayfada MCID 3'ü gösteren tek bir P öğesine ihtiyacı vardır. Sayfaları koordinat koduyla çizip etiketlemeyi sonra eklerseniz, erişilebilirlik denetleyicisindeki etiket ağacı genellikle tek paragraf olan yerde iki paragraf gösterir; bir de her devam eden tablonun verisinin içinde tekrarlanan bir sütun başlıkları seti

Koordinat yaklaşımının daha erken gelen ikinci bir maliyeti vardır. Raporun ilk sürümü çalışır. Sonra bir müşteri adresi üç satıra büyür, yerelleştirilmiş bir başlık satır atlar, bir tablo kırk satır kazanır ve o noktanın altındaki her y konumu yanlış olur. Sayfa sonu kontrolleri iş mantığının içine dağılır ve yıllardır yalnızca x ile y bilen kod, erişilebilirlik gereksinimi iki yıl sonra kapıyı çaldığında bir paragrafın nerede başladığı hakkında hiçbir fikri olmaz

Delphi'de bir HotPDF yerleşim ağacı kurmak

HotPDF her iki sorunu da HPDFLayoutDOM ünitesindeki bildirimsel yerleşim ağacıyla yanıtlar. Bir THPDFDOMDocument bölümleri tutar; her THPDFDOMSection bir sayfa boyutuna, kenar boşluklarına, isteğe bağlı bir üstbilgiye ve altbilgiye ve içine metin, başlık, boşluklayıcı, liste, görsel, kapsayıcı ve tablo eklediğiniz bir Body yığınına sahiptir. Ağaçta hiçbir şey y koordinatı taşımaz. THPDFDOMRenderer ağacı ölçer, sayfa sonlarına karar verir, her sayfaya üstbilgiyle altbilgiyi çizer ve GenerateStructure varsayılan olarak True olduğu için, giderken yapı ağacını yazar

Ağaçtaki sahiplik katıdır. Belge kendi bölümlerinin, bir bölüm kendi gövdesinin, üstbilgisinin ve altbilgisinin sahibidir; yığınlar, kapsayıcılar ve tablolar kendi çocuklarının sahibidir, dolayısıyla Section.Body.Add(Table) tabloyu iyice devreder. İki ebeveyne bağlanan bir bileşen, farklı kısıtlarla iki kez ölçülür ve sökümde iki kez serbest bırakılırdı. İmza bloğu gibi tekrar eden parçalar bu yüzden Clone'dan, SetHeaderClone / SetFooterClone'dan ya da RegisterComponent ile kaydedilen bir fabrikadan gelir; o andan sonra her CreateComponent('signature') çağrısı yeni bir örnek döndürür

Bölümlerin, üst bilgilerin, alt bilgilerin ve tablo satırlarının her birinin tam olarak bir sahibi olduğu bir HotPDF bildirimsel düzen belgesinin sahiplik ağacı
Düzen ağacındaki her düğümün tam olarak bir sahibi vardır; bu yüzden yardımcılar paylaşılan referanslar yerine taze örnekler döndürür ve yinelenen öğeler kayıtlı bir fabrikadan her çağrıda yeni bir bileşen olarak gelir
uses
  SysUtils, HPDFDoc, HPDFLayoutDOM;

type
  TAssetRow = record                    // kendi veri türünüz
    Name, ServiceDate, Status: WideString;
  end;

function BuildMaintenanceReport(const Assets: array of TAssetRow): THPDFDOMDocument;
var
  Doc: THPDFDOMDocument;
  Section: THPDFDOMSection;
  Heading: THPDFDOMText;
  Table: THPDFDOMTable;
  Row: THPDFDOMTableRow;
  I: Integer;
begin
  Doc := THPDFDOMDocument.Create;       // GenerateStructure = True, Language = 'en-US'
  try
    Section := Doc.AddSection;          // varsayılan: A4 dikey, 36 pt kenar boşlukları
    Section.MarginLeft := 56;
    Section.MarginRight := 56;
    Section.Style.FontName := 'Helvetica';
    Section.Style.FontSize := 10;
    Section.Style.LineHeight := 13;
    Section.Body.Style.Spacing := 6;    // gövde çocukları arası boşluk
    Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');

    Heading := Section.Body.AddHeading('Annual maintenance report', 1);
    Heading.Style.FontSize := 18;
    Heading.Style.LineHeight := 22;     // LineHeight, FontSize'i izlemez
    Section.Body.AddText('Every asset inspected during the reporting ' +
      'period is listed below, grouped by site.');

    Table := THPDFDOMTable.Create('assets');  // RepeatHeaders varsayılan olarak True
    Table.AddColumn(3);                 // ağırlıklar, punto cinsinden genişlikler değil
    Table.AddColumn(1);
    Table.AddColumn(1);
    Row := Table.AddRow(18, True);      // üstbilgi satırları önce gelmek zorundadır
    Row[0].Text := 'Asset';
    Row[1].Text := 'Last service';
    Row[2].Text := 'Status';
    for I := 0 to High(Assets) do
    begin
      Row := Table.AddRow(16);
      Row[0].Text := Assets[I].Name;
      Row[1].Text := Assets[I].ServiceDate;
      Row[2].Text := Assets[I].Status;
    end;
    Section.Body.Add(Table);            // gövde tabloyu bu noktadan itibaren sahiplenir
    Result := Doc;
  except
    Doc.Free;
    raise;
  end;
end;

Bu listedeki iki varsayılan insanı yakalar. LineHeight, zincirdeki bir stil onu ayarlamadıkça FontSize ne derse desin 12 puntoya çözümlenir; kendi LineHeight'ı olmayan 18 puntoluk bir başlık, 12 puntoluk satırlar alır ve bir sonrakinin üzerine biner. Ve bir tablo satırı, AddRow'a geçilen yüksekliğin ta kendisi kadardır: hücre metni tek satıra çıkar, bu yüzden satırları seçtiğiniz fonta göre boyutlandırın

Render, belgeyi kendi açar ve kendi kapatır

THPDFDOMRenderer.Render(Doc, Pdf) hedef üzerinde BeginDoc çağırır, her bölümü render eder ve dönmeden önce EndDoc çağırır. Bunu kendi BeginDoc / EndDoc çiftinizin içine sarmayın. Belge başlamadan önce ayarlanması gereken her şey önce THotPDF örneğine girer: FileName, Title ve çıktının PDF/UA iddiası varsa PDFUACompliance. Yapı üretimi açıksa, Render ayrıca EnableTaggedPDF'i açar ve boş bıraktıysanız Doc.Language'ı Pdf.Lang'e kopyalar

var
  Doc: THPDFDOMDocument;
  Pdf: THotPDF;
  Renderer: THPDFDOMRenderer;
  Stats: THPDFDOMRenderStatistics;
begin
  Doc := BuildMaintenanceReport(Assets);
  Pdf := THotPDF.Create(nil);
  Renderer := THPDFDOMRenderer.Create;
  try
    Pdf.FileName := 'maintenance-report.pdf';
    Pdf.Title := 'Annual maintenance report';
    Pdf.PDFUACompliance := True;        // şekil alternatif metni denetimini de etkinleştirir
    // Burada BeginDoc / EndDoc yok: Render belgeyi kendi açar ve kapatır
    Stats := Renderer.Render(Doc, Pdf);

    Writeln(Format('%d page(s), %d placement(s), %d split(s)',
      [Stats.PageCount, Stats.PlacementCount, Stats.SplitCount]));
    Writeln(Format('structure elements=%d marked content=%d artifacts=%d',
      [Stats.StructureElementCount, Stats.MarkedContentCount,
       Stats.ArtifactCount]));
    Writeln(Format('header draws=%d footer draws=%d deepest chain=%d',
      [Stats.HeaderDrawCount, Stats.FooterDrawCount,
       Stats.MaximumContinuationDepth]));
  finally
    Renderer.Free;
    Doc.Free;
    Pdf.Free;
  end;
end;

İstatistik kaydını her çalıştırmada günlüğe yazın; çünkü hiçbir zaman istisna üretmeyen şablon regresyonlarını gösterir. Bir şablon değişikliğinden sonra SplitCount'un fırlaması genellikle bir bileşenin artık eskiden sığdığı alandan daha uzun ölçüldüğü anlamına gelir. MaximumContinuationDepth'in yavaşça tırmanması, Split'i sayfa başına çok az içerik taşıyan bir bileşene işaret eder. ArtifactCount sayfa üstbilgilerini ve altbilgilerini, tablonun varsayılan 0,5 pt çerçevesi gibi dekoratif kenarlıkları ve tekrarlanan üstbilgi satırlarını kapsar; bu yüzden onu elle hesaplanmış bir hedefle değil, aynı şablonun çalıştırmaları arasında karşılaştırın

Uzun bir tablo, her sayfada kendini kopyalamadan nasıl sayfalanır?

Render edici yalnızca sayfa sınırına denk gelen şeyi böler. Bir ağacı sayfalamanın saf yolu, sığmayan her şeyi klonlayıp kopyayı bir sonraki sayfaya taşımaktır; 10.000 satırlık bir tabloda bu, kalan satırları sayfa başına bir kez klonlar ve doğrusal bir işi karesel bir işe dönüştürür. HotPDF gövde çocuklarında indekse göre gezinir ve bütün bir bölümü ya da gövdeyi asla klonlamaz. Sayfa sınırını aşan bir iç içe yığın veya kapsayıcı yalnızca etkilenen alt ağacını klonlatır; iki ağır yaprak türü ise kopya yerine imleç taşır

Devam eden bir paragraf, özgün metne bir referans artı hâlâ borçlu olduğu karakter aralığıdır ve o genişlik için zaten hesaplanmış satır kırılımlarını yeniden kullanır. Devam eden bir tablo, özgün tabloya bir referans artı henüz yerleştirilecek satır dilimidir. 300 satırlık bir paragraf, bir kez de kesilse beş kez de kesilse aynı maliyete sahiptir

HotPDF'de tüm-alt ağaç klonlamasından gelen ikinci dereceden sayfalama maliyeti ile dar sayfa-sınırı bölmelerinden gelen düz doğrusal maliyeti karşılaştıran çubuk grafik
Sınır aşan her sayfada bütün yerleştirilmemiş alt ağacı klonlamak, ek satırları ikinci dereceden işe dönüştürür; dar bir bölme ise uzun metnin karakter-aralığı imleci, tabloların satır-dilimi imleci taşımasına izin verir

Yerleştirmenin kendisi, herkese açık THotPDF.PlaceLayoutElement üzerinden yürür. Bu yordam öğeyi kalan gövde yüksekliğine karşı ölçer, sığıyorsa bütün olarak çizer, sığmıyorsa Split ister; yerleşen yarısını yeniden ölçer, çizer ve kalanı, render edicinin taze bir sayfaya taşıdığı bir taşma nesnesi olarak döndürür. Measure asla bir şey çizmemelidir; tek bir yerleştirme için birkaç kez çalışabilir. DOM render edicisi bu yordamın üstüne sayfa süslerini, çocuklar arası boşlukları ve yeni sayfa kararlarını ekler

Tek bir üstbilgi satırı tüm render'ı neden durdurabilir?

Tekrarlanan tablo üstbilgileri iki kural taşır ve ikisi de bir raporun verisiz sayfa üretmesini önlemek için vardır. Üstbilgi satırları ilk satır grubunu oluşturmak zorundadır: herhangi bir gövde satırından sonra verilen AddRow(Height, True), "Table header rows must precede body rows" mesajıyla EInvalidOpException fırlatır. Ve bir tablonun ilk bölünmesi, her üstbilgi satırına artı en az bir gövde satırına sığmak zorundadır. Üstbilgiyi bir sayfanın dibinde mahsur bırakacak bir tablo, bir sonraki sayfaya geçer

İkinci kuralın sert bir sınırı vardır. Üstbilgi satırları artı bir gövde satırı boş bir sayfaya bile sığmıyorsa, tablonun başlayabileceği bir sayfa yoktur ve Render, bileşen yolunu da vererek "Layout component ... cannot fit an empty body page" hatası fırlatır; örneğin Sections[0]/Body/Items[2]/assets gibi. Sahip olunmaya değer davranış budur. Bir sonrakinin daha geniş olacağı umuduyla sayfa eklemeye devam eden bir yerleşim motoru, tek bir aşırı büyük üstbilgiyi diski dolduran bir döngüye çevirirdi

Özel bileşenler aynı korumayı alır. THPDFDOMComponent'i alt sınıflayın, Clone, Measure, Draw ve Split'i gerçekleştirin; render edici her gövde çocuğunun kaç devam ürettiğini sayar. THPDFDOMRenderer.MaximumContinuationDepth'in üzerinde (varsayılan 100.000) render, "exceeded the continuation depth limit" mesajıyla durur. Eşdeğer bir kuyruk döndürmeye devam eden, yani hiç ilerleme kaydetmeyen bir Split, disk dolana dek koşmak yerine bileşen yoluyla başarısız olur

Devam sayfalarında üstbilgi satırları bir /Artifact işaretli-içerik dizisinin içinde yeniden çizilir ve yapı ağacı özgün TR'yi bir kez tutar. Böylece metin çıkarma, veri satırları arasına yinelenen bir üstbilgi satırı eklemez ve yardımcı teknoloji, sütun başlıklarını tablonun ortasında yeniden duyurmaz. Her üstbilgi hücresi, /Scope /Column özniteliğiyle TH olarak etiketlenir

Tek mantıksal öğe, çok sayfa parçası

Bölünmüş bir paragraf tek P yapı öğesi olarak kalır. Her görünür parça kendi sayfasında yeni bir işaretli içerik dizisi açar ve HotPDF, o öğenin /K dizisine bir işaretli içerik referans sözlüğü, << /Type /MCR /Pg page /MCID n >>, ekler; MCID'yi de aynı öğeye geri işaret eden sayfanın ParentTree girişine kaydeder. Bu düzen, ISO 32000-1 §14.7.4'ün sayfalara yayılan içerik öğeleri için tarif ettiği düzendir ve etiket ağacı görünümünün, sayfaların iki parça gösterdiği yerde tek paragraf göstermesini sağlayan şey budur

Anlamsal kimlik, devam klonlarının kendi klonlarınızdan farklı davranmasının nedenidir. Clone çağırmak "yeni mantıksal içerik" demektir ve sonuç, çizildiğinde yeni bir yapı öğesi alır. Sayfalama sırasında yapılan kopyalar ise devam ettikleri bileşenin kimliğini devralır; üç sayfaya bölünen bir yığın hâlâ tek Div üretir, iki sayfaya bölünen bir liste hâlâ tek L. Sayfa üstbilgileri ve altbilgileri başka bir güzergâhtan gider: her sayfada /Artifact << /Type /Pagination /Subtype /Header >> (veya /Footer) olarak sarılırlar ve yapı ağacına hiç girmezler

HotPDF şeması: Tek bir etiketli paragraf tek bir PDF yapı öğesi olarak tutulurken onun iki sayfa parçası ayrı işaretli-içerik tanımlayıcıları taşır ve yeniden çizilen bir başlık yapay öğe olarak etiketlenir
Tek paragrafın parçaları, K dizisinde toplanan Pg ve MCID çiftleri üzerinden tek bir yapı öğesini paylaşır; devam sayfalarında yeniden çizilen başlık ise içerik yerine bir artifact olarak yol alır

Ağaç render edilirken denetlenen yapı kuralları

GenerateStructure açıkken, render edici PDF/UA doğrulamasının sonra reddedeceği yapıyı kabul etmez. İlk başlık H1 olmak zorundadır ve sonraki başlıklar seviye atlayamaz; H1'in hemen ardından gelen bir H3, "Semantic heading levels cannot skip an intermediate level" hatası fırlatır. LI bir L ebeveyne, Lbl ve LBody bir LI'ya, TR bir tabloya ya da satır grubuna, TH / TD ise bir TR'ye ihtiyaç duyar. Hedefte PDFUACompliance ayarlıysa, alternatif metni olmayan bir Figure da reddedilir. Her ihlal Render'ı bir istisna ile durdurur

var
  List: THPDFDOMList;
  Bmp: TBitmap;                         // Vcl.Graphics
begin
  Section.Body.AddHeading('Findings', 2);     // H1 önce geldi, o yüzden H2 geçerli

  List := THPDFDOMList.Create('Decimal');     // L olarak etiketlenir, ListNumbering /Decimal
  List.AddItem('1.', 'Replace the intake filter on pump P-14');
  List.AddItem('2.', 'Re-torque the flange bolts on line 3');
  Section.Body.Add(List);                     // AddItem, LI, Lbl ve LBody üretir

  Bmp := TBitmap.Create;
  try
    Bmp.LoadFromFile('site-plan.bmp');
    // Görüntü, grafiğin kopyasını alır; boş alt metin PDFUACompliance altında başarısız olur
    Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
      'Site plan of plant 3 with the inspected pumps circled'));
  finally
    Bmp.Free;
  end;
end;

Bu kurallar için doğru yer render sırasındaki denetimdir; bunun nedeni zamandır. Belge yazıldıktan sonra eksik bir alternatif metni bildiren bir doğrulayıcı, size 10.000 adet ekstrenin yeniden üretilmesi gerektiğini söyler; Render sırasında fırlayan bir istisna ise, onu üreten kayıt hâlâ kapsamdayken hangi kuralın başarısız olduğunu adıyla söyler. Formal uygunluk denetimi yine de işlem hattındaki yerini korur ve belgenin nesneleri Render döndükten sonra okunabilir kaldığı için bu adım hemen koşabilir. PDF/A, PDF/X ve PDF/UA doğrulama o adımı ele alır; yapı sırası ve metin çıkarma ise etiket ağacının çıkarma araçlarının neyi okuduğunu nasıl yönlendirdiğini gösterir

Elle çizmeye ne zaman devam etmeli

Ağaç, doğrudan API'nin kullandığı aynı THPDFPage nesnelerinin üzerine çizer. Render belgeyi BeginDoc'tan EndDoc'a kadar sahiplendiği için, imza görseli gibi elle konumlanan içerik ağacın içinde yaşamlıdır: özel bir bileşenin Draw'u sayfayı ve sınırlarını alır ve orada sıradan sayfa metotlarını çağırabilir. Sayfa kapatma AddPage ve EndDoc'ta kalır; böylece THotPDF örneğinde ImmediateFlushLayout ayarlıysa, biten sayfalar render ilerledikçe yazılır ve render edici elinde tamamlanmış hiçbir sayfa tutmaz. Bellek sonra açık devamlara, font kaynaklarına ve belgenin nesne grafiğine bağlı kalır

DOM metin bileşeni satırları, karakter başına font boyutunun 0,55 katı olarak kestirilen ortalama genişlikten kırar ve her satıra çözümlenmiş LineHeight'ı verir. Bu, ölçümü ucuz ve her makinede aynı tutar ve veri güdümlü raporlar için fazlasıyla yeterlidir. Geniş glyph'li metin, yani tamamı büyük harf, kalın koşular veya CJK gibi, kestirimden daha geniş çıkar; o sütun genişliklerinde pay bırakın ve yerleşimi bir kez en uzun gerçek metinle test edin. Tam glyph metrikleri, tek satırda karışık fontlar veya iki yana hizalı paragraflarla dizilmiş sayfalar için doğrudan metin API'si daha iyidir; metin hizalama o güzergâhı anlatır ve sıkıntınız yalnızca tablo sayfalamasıysa, PDF'de tablo oluşturma daha küçük bir değişikliktir

Yerleşim ağacı, onun render edicisi, burada anlatılan etiketleme ve doğrudan çizim API'si, Delphi ve C++Builder için tek bileşende gelir; sürümler ve eksiksiz özellik listesi HotPDF Delphi PDF bileşeni sayfasındadır