Teknik Makale

Delphi'den PDF'de Flexbox, CSS Grid ve Dipnotlar

İki sütunlu bir bölümün, sol sütunun sondan ikinci satırına bir dipnot referansı koyduğunu düşünün. Tek satırlık bir not, o sütunun dibinde kabaca 14 puan ister ve yalnızca 9 puan kalmıştır. İki açık sonuç da yanlıştır: notu yine de çizin, gövde metninin üstüne basar; ya da yalnızca notu ileri itin, sağ sütunun altına, bir alakası olmayan metnin yanına düşer. Bir tarayıcı bu karar hiç vermek zorunda kalmaz, çünkü web sayfasının alt kenarı yoktur. Flexbox ile CSS Grid aynı varsayım altında tasarlandı; bu yüzden rapor HTML'i sabit boyutlu sayfalara düşmek zorunda kaldığında, her ikisinin de kutunun yüksekliği bittiğinde ne olacağına dair bir kurala ihtiyacı vardır

Sabit genişlikte bir kutuda flex pano satırı

PDF Library for Delphi, display: flex ya da display: inline-flex biçimlendirilmiş her öğeyi gerçek bir flex kapsayıcısı sayar; böylece bir kart satırı, üst üste binen bloklara çökmeden satır olarak kalır. Onu DrawHTMLTextBox(Left, Top, Width, Height, HTMLText) ile çizersiniz; bu, bir WideString döndürür: her şey sığdığında boş, aksi halde başka bir yere çizilmesi gereken kısmı verir

Satır yönünde her öğe bir temel alır; temel değerleri ile öğeler arasındaki boşluklar toplanır ve satırda arta kalan her şey dağıtılır. Artı alan flex-grow'a gider. Eksi alan, flex-shrink'in öğenin temeliyle çarpımıyla geri alınır; bu CSS kuralıdır ve birazdan göreceğiniz hoş bir yan etkisi vardır. flex-wrap ayarlıyken öğeler, bir sonraki temel artık sığmadığında yeni satıra geçer ve her satır kendi boş alanını dağıtır. justify-content, align-items, align-content, gap ve -reverse yönleri ise sonradan yalnızca ölçülmüş kutuları taşır

PDF Library for Delphi flex satır boyutlandırma şeması: ölçülmüş temeller ve büyüme ağırlıkları, satır başına arta kalan alanın ağırlıklı dağılımı ve yalnızca taşıyan bir hizalama turu ile 2:1:1 pano satırı
Flex boyutlandırma, tek bir sınırlı ölçüm turu ve ardından arta kalan alanın ağırlıklı dağılımından ibarettir; hizalama, ölçülmüş kutuları taşır ve asla yeniden ölçüm tetiklemez
uses
  SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  Html, Remainder: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetOrigin(1);          // sol-üst köken: Top, sayfada aşağı doğru büyür
    Lib.SetPageSize('A4');

    // Yüzde temelleri 2:1:1 oranını boşluk dahil tam korur
    Html :=
      '<div style="display:flex; gap:12px;">' +
      '<div style="flex:0 1 50%; background:#f4f6f8; padding:8px;">' +
        '<b>Revenue</b><br/>EUR 4,182,300</div>' +
      '<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
        '<b>Margin</b><br/>18.4%</div>' +
      '<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
        '<b>Backlog</b><br/>92 days</div>' +
      '</div>';

    Remainder := Lib.DrawHTMLTextBox(40, 40, 515, 120, Html);
    if Remainder <> '' then
      raise Exception.Create('Dashboard row needs more than 120 pt');

    Lib.SaveToFile('dashboard.pdf');
  finally
    Lib.Free;
  end;
end;

515 puanlık kutu için sayıları işletin. 12px'lik boşluk 9 puana dönüşür; dolayısıyla iki boşluk 18 eder. Temeller tam 515'e ulaşır ve tam o 18 puanı aşar. Küçültme temelle ağırlıklıdır; dolayısıyla %50'lik kart 9 puan, her %25'lik kart 4.5 puan geri verir ve 248.5, 124.25 ile 124.25 kalır. Oran hâlâ tam 2:1:1'dir ve kod, boşlukları elle hiç çıkarmak zorunda kalmadı

Eşit flex: 1 öğeleri neden eşitsiz çıkar?

Çünkü temelleri, içeriklerinin genişliğidir. İşleyici temeli flex-basis'den, flex kısayolu içindeki bir uzunluktan (pt, px, em ya da % taşıyan bir değer) ya da width'ten alır. Bunların hiçbiri pozitif bir uzunluk üretmediğinde, öğenin ölçülmüş içerik genişliği temeli olur. Çıplak bir flex: 1 ile tarayıcı deyimi flex: 1 1 0 ikisi de oraya varır; çünkü birimsiz bir 0 uzunluk olarak okunmaz. Eşit büyüme katsayıları sonra eşit olmayan başlangıç genişliklerinin üzerine eşit miktarda boş alan ekler

Aynı panoyu her karta flex: 1 vererek yazın; yedi haneli rakamı içeriğini üçlü arasından en geniş yapan Revenue kartı, Margin kartından geniş başlar ve büyümeden sonra tam o kadar daha geniş kalır; çünkü her kart, artan boş alanın aynı üçte birini alır. Araç çubukları, etiket listeleri ve düğme satırları için bu çoğu zaman zaten istediğiniz görünümüdür. Bir pano için değil. Üstünde ya da altındaki bir tabloyla hizalanması gereken her şey, büyümesi 0'a ayarlanmış açık yüzde ya da puan temellerini hak eder; bu bizim tavsiyemizdir ve örnek tam olarak bunu yapar: üç kart, içindeki rakamlar ne derse desin, her sayfada 248.5, 124.25 ve 124.25 puana düşer

Sütun yönü aynı mantığı dikey eksende izler. Temel flex-basis'den ya da height'ten, aksi halde ölçülmüş içerik yüksekliğinden gelir ve boş alan yalnızca kapsayıcı bir height bildirdiğinde vardır. Bildirmediğinde kapsayıcı tam olarak öğeleri kadar uzundur ve justify-content'in dağıtacak hiçbir şeyi olmaz

Grid rayları, yerleşim ve kapsamalar

display: grid için PDF Library for Delphi, grid-template-columns ile grid-template-rows'u sabit uzunluklar, yüzdeler, fr birimleri, repeat(n, track) ve minmax(a, b) olarak okur. Sabit raylar ve boşluklar erişilebilir genişlikten düşülür ve kalan, fr ağırlığına göre bölünür. Bir minmax() rayı ikinci argümanıyla boyutlanır; dolayısıyla minmax(120px, 1fr) 1fr gibi davranır ve auto, min-content ile max-content rayları, boş alandan birer pay alır

PDF Library for Delphi kabul edilen grid ray değerleri, kasıtlı üst üste binmeye izin veren deterministik doluluk yerleşimi ve kapsadığı satırlar arasında yüksekliğini ortalayarak döndüren satır kapsayan bir öğe şeması
Grid rayları uzunlukları, yüzdeleri, fr birimlerini, repeat ile minmax'i kabul eder; otomatik yerleşim doluluk matrisini deterministik olarak gezinir

Yerleşim deterministiktir. Otomatik yerleşen öğeler, grid'i satır satır (ya da grid-auto-flow: column ile sütun sütun) gezinir ve hâlihazırda alınmış hücreleri atlar. Yalnızca satırı verilmiş bir öğe, o satırda boş bir sütun arar; yalnızca sütunu verilmiş bir öğe, o sütunda aşağı doğru arar. Her iki koordinatı verilmiş öğeler, tam söyledikleri yere gider; öteki bir öğenin üzerine bile. Bir rozetin kartın üzerine katmanlanması böyle olur

Kapsamalar tek bir alışkanlık ister. İşleyici kapsamı, grid-row: 1 / span 2'deki gibi eğik çizgiden sonraki kısımdan ya da grid-row-end: span 2 ile grid-column-end: span 2'den okur. Tarayıcıların bütün değer olarak kabul ettiği çıplak grid-row: span 2, o yazımlardan biri değildir; dolayısıyla başlangıç çizgisini ve eğik çizgiyi koruyun

// Denetim formu: sabit etiket sütunu, iki esnek sütun
Html :=
  '<div style="display:grid; ' +
  'grid-template-columns:120pt repeat(2, 1fr); gap:6pt;">' +
  '<div style="grid-row:1 / span 2; background:#eef2ff;">' +
    'Site plan</div>' +
  '<div>Inspector</div>' +
  '<div>Date</div>' +
  '<div style="grid-column:2 / span 2;">Findings summary</div>' +
  '</div>';

Remainder := Lib.DrawHTMLTextBox(40, 180, 515, 260, Html);

O 515 puanlık kutuda etiket sütunu 120 puandır, iki boşluk 12 alır ve her 1fr sütunu 191.5 alır. Site plan hücresinin satırı vardır ama sütunu yoktur; dolayısıyla 1. sütuna düşer ve 1. ile 2. satırları kapsar. Inspector ile Date, 1. satırın kalanını doldurur. Özetin sütunu vardır ama satırı yoktur; yerleşim 2. sütunda aşağı arar, 1. satırın dolu olduğunu görür ve iki esnek sütuna yayılarak 2. satıra yerleşir

Satır yükseklikleri içerikten gelir. Kapsayan bir öğe, ölçülmüş yüksekliğini kapsadığı satırlara eşit bölüştürdüğü ve her satır, içindeki bir öğenin istediği en büyük payı aldığı için, uzun bir hücrenin fazla yüksekliği yalnızca ilkine yığılmak yerine dokunduğu her satıra yayılır. Uzun bir Site plan hücresi bu yüzden her iki satırı biraz yükseltir; yalnızca ilkini uzatıp Findings summary'yi bir boşlukta yüzüyor bırakmaz

Kapsayıcılar kutular arasında tek parça taşınır

Bir flex ya da grid kapsayıcısı hiçbir zaman iki kutuya bölünmez. Asla. Bütün kapsayıcı, kalan alana sığmadığında kapsayıcı ve ondan sonraki her şey döndürülen artığa gider; o artık bir sonraki kutuya ya da bir sonraki sayfaya geçeceğiniz şeyin ta kendisi olduğundan, kart satırı bir sonraki çerçeveyi ölçülmüş geometrisi bozulmadan açar. 3. sayfanın dibinde yarım bir KPI kutucuğu ve öteki yarısı 4. sayfada, bir boşluktan daha kötüdür ve bu kuralın üstlendiği takas budur. Bütün boş bir kutudan daha uzun bir kapsayıcı istisnadır: o, her koşulda kutunun tepesine çizilir ve alt kenarını aşar, çünkü sonraki hiçbir kutu daha büyük olmayacaktır

Pratik sonucu şu: bir kapsayıcıyı bir sayfaya taahhüt etmeden önce yüksekliğini bilmelisiniz. GetHTMLTextHeight(Width, HTMLText), çizmeden ölçer; flex ve grid dahil

// GridHtml, Y ve PageBottom sizin rapor kodunuza aittir
Needed := Lib.GetHTMLTextHeight(515, GridHtml);
if Y + Needed > PageBottom then
begin
  Lib.NewPage;
  Lib.SetPageSize('A4');
  Y := 40;
end;
Lib.DrawHTMLTextBox(40, Y, 515, Needed, GridHtml);
Y := Y + Needed + 12;

Ölçüm bilinçli olarak sınırlıdır; müşteriler şablonları düzenlediğinde bu önem kazanır. Bir flex ya da grid kapsayıcısı ilk 256 doğrudan çocuğunu alır, grid yerleşimi 64 satır içinde çalışır ve bir ray listesi en çok 64 ray tutar; repeat() sayımları da aynı tavana kırpılır. Yüzlerce çocuğu olan bir flex kapsayıcısı neredeyse her zaman kılık değiştirmiş bir veri tablosudur ve kendi sütun ölçümü ile rowspan desteği olan tablo yolu, onu zaten daha iyi yerleştirir

Dipnotlar referanslarıyla birlikte nasıl tutulur?

PDF Library for Delphi her notu, referansla karşılaştığı anda ölçer ve o yüksekliği geçerli kutunun gövde bütçesinden düşer. Bir not, <aside style="float:footnote">, <aside role="doc-footnote"> ya da bir <footnote> öğesi olarak yazılır. Referans, çevresindeki font boyutunun üçte ikisi boyutunda üst simge bir sayıya dönüşür ve not metni, 10 puan satır aralığında 8 puanla, aynı sayıyla öne eklenerek dizilir

Şu ana kadarki gövde artı yeni not artık sığmıyorsa, işaretçi ve ondan sonraki her şey birlikte artığa taşınır. Not ile referans bir çift olarak yol alır. Açılış senaryosunun cevabı budur: referans satırı ve notu bir sonraki sütunu açar; ne üstüne basma ne de sahipsiz kalan not gerçekleşebilir. Sınırlı bir kutuda not alanı, kutu genişliğinin dörtte biri uzunluğunda ince gri bir çizginin altında dibe sabitlenir. GetHTMLTextHeight gibi sınırsız ölçümde sabitlenecek bir dibin altı yoktur; dolayısıyla notlar gövdeyi doğrudan izler

PDF Library for Delphi dipnot sayfalama şeması: not alanı, kutusunun dibinde bir çizgi altında ayrılır; sığmayan bir not, işaretçisiyle birlikte devam dizesine yol alır ve numaralandırma sayfalar boyunca kesintisiz kalır
Dipnot alanı, daha fazla metin akmadan önce gövde bütçesinden oyulur ve numaralandırma, sütunlar ve sayfalar boyunca yaşar

Numaralandırma her taze HTML dizesi için 1'den başlar. Bir sonraki sayı, artık dizesinin içinde saklanır; böylece DrawHTMLTextBox zincirleri ile DrawHTMLStory, artık geri yazıldığı gibi geri geçirildiği sürece sütunlar ve sayfalar boyunca tek bir kesintisiz dizi korur. Devam metnini kendi kaynak metninizden yeniden kurmak sayımı sıfırlar

Chapter :=
  '<p>The bearing stayed within tolerance for the full six hours' +
  '<aside style="float:footnote">Ambient temperature held at ' +
  '21 &deg;C throughout the run.</aside> of the load test.</p>' +
  MoreChapterHtml;                 // bölümünüzün geri kalanı

// 2 sütun, 16 pt oluk, en çok 20 sayfa; öykü sayfaları kendisi ekler
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode;          // bir kez okuyun: okumak sıfırlar

if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
  // bozuk geometri: Columns 1..64, MaxPages 1..10000, Width'ten dar oluklar
else if Err = PDFLIB_ERROR_HTML_STORY then
  // üst üste iki çerçeve ilerleme kaydetmedi
else if Rest <> '' then
  // 20 sayfa harcandı ve metin kaldı: sonra Rest ile sürdürün
  ;

DrawHTMLStory(Left, Top, Width, Height, Columns, Gutter, MaxPages, HTMLText) geçerli sayfada başlar, sütunları soldan sağa doldurur ve metin bitene ya da MaxPages dolana dek aynı boyutlarda sayfalar ekler. O üç sonucu birbirinden ayırt etmek, döndürülen diziyi sınamadan önce LastErrorCode'u okumanın nedenidir. Geçersiz argümanlar girdiyi değiştirmeden döndürür; bu, sayfaları bitmiş bir öyküden ayırt edilemez görünür

Yerleşimi gerçek içerikle beslemek

Çok sütunlu gövde metni için heceleme ve dengeli metin sütunları yazısındaki sütun ve heceleme davranışı, akışın her sütunun içinde nasıl göründüğüne hükmeder. İşaretleme, elle yazılmış şablonlardan değil veriden geldiğinde, veri kümesi rapor motoru, flex ve grid sayfada dizmeden önce onu üreten yoldur. Sonradan PDF'den yeniden çıkması gereken içerik, PDF'i Markdown ve DOCX'e aktarma yolundan geçer

Flex, grid ve dipnotlu HTML yerleşimi, rapor üretimi ve semantik aktarım, Delphi, C++Builder ve Free Pascal için tek bir kütüphanede gelir. PDF Library for Delphi ürün sayfası, HTML işleyicisinin ve çizim API'sinin geri kalanını listeler