Artykuł techniczny

Flexbox, CSS Grid i przypisy dolne w PDF z Delphi

Załóżmy, że dwukolumnowy rozdział stawia odwołanie przypisu na przedostatniej linii lewej kolumny. Jednoliniowy przypis potrzebuje z grubsza 14 punktów u stóp tej kolumny, a zostało tylko 9. Oba oczywiste rozstrzygnięcia są złe: narysować przypis mimo wszystko i niech nadrukuje się na tekst główny, albo przepchnąć w przód tylko przypis i niech wyląduje pod prawą kolumną, obok tekstu, z którym nie ma nic wspólnego. Przeglądarka nigdy nie musi podejmować tej decyzji, bo strona internetowa nie ma dolnej krawędzi. Flexbox i CSS Grid były projektowane przy tym samym założeniu, więc skoro HTML raportu musi wylądować na stronach o stałym rozmiarze, każdy z nich potrzebuje reguły, co się dzieje, gdy pudełko przestaje mieć wysokości

Wiersz pulpitu we flexie w pudełku o stałej szerokości

PDF Library for Delphi traktuje każdy element z display: flex albo display: inline-flex jako prawdziwy kontener flex, więc rząd kart zostaje rzędem zamiast się zwinąć w ułożone w stos bloki. Rysujesz go przez DrawHTMLTextBox(Left, Top, Width, Height, HTMLText), które zwraca WideString: pusty, gdy wszystko się zmieściło, w przeciwnym razie część, która jeszcze musi być narysowana gdzie indziej

W kierunku wiersza każdy element dostaje bazę, wartości baz i odstępy między elementami są sumowane, a cokolwiek zostanie na linii, jest rozdawane. Dodatnia przestrzeń idzie według flex-grow. Ujemna przestrzeń jest odbierana przez flex-shrink pomnożony przez bazę elementu, co jest regułą CSS i ma przyjemny efekt uboczny pokazany za chwilę. Przy ustawionym flex-wrap elementy przechodzą na nową linię, jak tylko następna baza przestaje się mieścić, a każda linia rozdziela własną wolną przestrzeń. justify-content, align-items, align-content, gap i kierunki -reverse przesuwają wtedy tylko pudełka już zmierzone

Diagram PDF Library for Delphi rozmiarowania wiersza flex: zmierzone podstawy i wagi rozrostu, ważony rozdział pozostałego miejsca na linię oraz przebieg wyrównania wyłącznie przesuwający, dający wiersz pulpitu dwa do jednego do jednego
Wymiarowanie flexa to jeden ograniczony przebieg pomiaru, po którym następuje ważony podział pozostałego miejsca; wyrównanie przesuwa zmierzone pudełka i nigdy nie wywołuje ponownego pomiaru
uses
  SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  Html, Remainder: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetOrigin(1);          // korzeń lewy-górny: Top rośnie w dół strony
    Lib.SetPageSize('A4');

    // Bazy procentowe trzymają proporcję 2:1:1 dokładnie, rynna wliczona
    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;

Policz liczby dla pudełka o 515 punktach. Rynna 12px przelicza się na 9 punktów, więc dwie rynny kosztują 18. Bazy sumują się do pełnych 515, co przestrzeliwuje o dokładnie te 18 punktów. Shrink jest ważony bazą, więc karta 50% oddaje 9 punktów, a każda karta 25% oddaje 4,5, zostawiając 248,5, 124,25 i 124,25. Proporcja nadal jest dokładnie 2:1:1, a kod nigdy nie musiał odejmować rynien ręcznie

Dlaczego równe elementy flex: 1 wychodzą nierówne?

Bo ich bazą jest szerokość ich treści. Renderer bierze bazę z flex-basis, z długości w skrócie flex (wartość z pt, px, em albo %) albo z width. Gdy żadne z nich nie wytwarza dodatniej długości, zmierzona szerokość treści elementu staje się jego bazą. Gołe flex: 1 i browserowy idiom flex: 1 1 0 lądują oba tam, bo bezjednostkowe 0 nie jest czytane jako długość. Równe współczynniki wzrostu dodają wtedy równe porcje wolnej przestrzeni na nierównych szerokościach startowych

Napisz ten sam pulpit z flex: 1 na każdej karcie, a karta Revenue, której siedmiocyfrowa kwota czyni jej treść najszerszą z trzech, startuje szersza niż karta Margin i pozostaje szersza dokładnie o tę różnicę po wzroście, bo każda karta dostaje tę samą jedną trzecią tego, ile wolnej przestrzeni zostało. Dla pasków narzędzi, list etykiet i rzędów przycisków to często i tak pożądany wygląd. Dla pulpitu nie. Cokolwiek musi się układać w linii z tabelą nad albo pod sobą, zasługuje na jawne bazy procentowe albo punktowe z grow ustawionym na 0, co jest naszą rekomendacją i dokładnie tym, co robi przykład: trzy karty lądują wtedy na 248,5, 124,25 i 124,25 punktach na każdej stronie, cokolwiek mówią liczby wewnątrz nich

Kierunek kolumny podąża za tą samą logiką na osi pionowej. Baza pochodzi z flex-basis albo height, w przeciwnym razie ze zmierzonej wysokości treści, a wolna przestrzeń istnieje tylko wtedy, gdy kontener deklaruje height. Bez niej kontener jest dokładnie tak wysoki jak jego elementy, a justify-content nie ma czego rozdawać

Ścieżki grid, rozmieszczanie i rozpiętości

Dla display: grid PDF Library for Delphi czyta grid-template-columns i grid-template-rows jako stałe długości, procenty, jednostki fr, repeat(n, track) i minmax(a, b). Stałe ścieżki i rynny są odejmowane od dostępnej szerokości, a reszta jest dzielona wagą fr. Ścieżka minmax() jest wymiarowana swoim drugim argumentem, więc minmax(120px, 1fr) zachowuje się jak 1fr, a ścieżki auto, min-content i max-content biorą każda jedną część wolnej przestrzeni

Diagram PDF Library for Delphi akceptowanych wartości ścieżek siatki, deterministycznego rozmieszczania zajętości z dozwolonym zamierzonym nakładaniem oraz elementu obejmującego wiersze zwracającego wysokość uśrednioną po wierszach, które pokrywa
Ścieżki siatki przyjmują długości, procenty, jednostki fr, repeat i minmax, podczas gdy automatyczne rozmieszczanie przechodzi macierz zajętości w sposób deterministyczny

Rozmieszczanie jest deterministyczne. Elementy rozmieszczane automatycznie przechodzą siatkę wiersz po wierszu (albo kolumna po kolumnie z grid-auto-flow: column) i pomijają komórki już zajęte. Element z podanym tylko wierszem szuka w tym wierszu wolnej kolumny; element z podaną tylko kolumną szuka w dół tej kolumny. Elementy z obiema współrzędnymi idą dokładnie tam, gdzie mówią, nawet na wierzch innego elementu, i tak odznaka dostaje się warstwą na kartę

Rozpiętości wymagają jednego nawyku. Renderer czyta rozpiętość z części po ukośniku, jak w grid-row: 1 / span 2, albo z grid-row-end: span 2 i grid-column-end: span 2. Gołe grid-row: span 2, które przeglądarki akceptują jako całą wartość, nie jest jedną z tych pisowni, więc trzymaj linię startową i ukośnik

// Arkusz inspekcji: stała kolumna etykiet, dwie elastyczne kolumny
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);

W tym pudełku o 515 punktach kolumna etykiet ma 120 punktów, dwie rynny biorą 12, a każda kolumna 1fr dostaje 191,5. Komórka Site plan ma wiersz, ale nie ma kolumny, więc ląduje w kolumnie 1 i pokrywa wiersze 1 i 2. Inspector i Date wypełniają resztę wiersza 1. Podsumowanie ma kolumnę, ale nie ma wiersza, więc rozmieszczanie szuka w dół kolumny 2, znajduje wiersz 1 zajęty i osiada w wierszu 2 na obu elastycznych kolumnach

Wysokości wierszy pochodzą z treści. Ponieważ element rozpięty dzieli swoją zmierzoną wysokość równo na wiersze, które pokrywa, a każdy wiersz bierze potem największą część, o jaką prosi jakikolwiek element w nim, nadwyżka wysokości wysokiej komórki jest rozsmarowana po każdym wierszu, którego dotyka, zamiast zrzucona na pierwszy. Wysoka komórka Site plan podnosi więc oba wiersze trochę, zamiast rozciągać tylko pierwszy i zostawiać Findings summary unoszące się w dziurze

Kontenery przechodzą między pudełkami w całości

Kontener flex albo grid nigdy nie jest cięty na dwa pudełka. Nigdy. Gdy cały kontener nie mieści się w zostawionej przestrzeni, kontener i wszystko po nim idzie do zwracanej reszty, a skoro ta reszta to dokładnie to, co przekazujesz do następnego pudełka albo następnej strony, rząd kart po prostu otwiera następną ramkę ze swoją zmierzoną geometrią nietkniętą. Połowa kafelka KPI na dole strony 3 i druga połowa na stronie 4 jest gorsza niż dziura, i to jest kompromis, który ta reguła zawiera. Kontener wyższy niż całe puste pudełko to wyjątek: jest rysowany na górze tego pudełka mimo wszystko i przebiega poza jego dolną krawędź, bo żadne późniejsze pudełko nie byłoby większe

Praktyczna konsekwencja jest taka, że powinieneś znać wysokość kontenera, zanim oddasz go stronie. GetHTMLTextHeight(Width, HTMLText) mierzy bez rysowania, flex i grid wliczone

// GridHtml, Y i PageBottom należą do twojego kodu raportu
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;

Pomiar jest ograniczony celowo, co ma znaczenie, gdy klienci edytują szablony. Kontener flex albo grid bierze swoje pierwsze 256 bezpośrednich dzieci, rozmieszczanie grid działa w obrębie 64 wierszy, a lista ścieżek trzyma co najwyżej 64 ścieżki, z liczbami repeat() skorowanymi, by pasować. Kontener flex z setkami dzieci to prawie zawsze tabela danych w przebraniu, a ścieżka tabeli, z własnym pomiarem kolumn i wsparciem rowspan, ułoży ją i tak lepiej

Jak przypisy trzymają się swoich odwołań?

PDF Library for Delphi mierzy każdy przypis w chwili, gdy spotyka jego odwołanie, i odejmuje tę wysokość od budżetu treści bieżącego pudełka. Przypis zapisuje się jako <aside style="float:footnote">, <aside role="doc-footnote"> albo element <footnote>. Odwołanie staje się numerem indeksu górnego o dwóch trzecich otaczającej wielkości czcionki, a tekst przypisu jest składany 8 punktami na interlinii 10 punktów, z tym samym numerem z przodu

Jeśli treść dotychczasowa plus nowy przypis nie mieszczą się już razem, znacznik i wszystko po nim przechodzą do reszty wspólnie. Przypis i odwołanie podróżują jako para. To jest odpowiedź na scenę otwierającą: linia odwołania i jej przypis otwierają następną kolumnę, i ani nadruk, ani osierocony przypis nie mogą się wydarzyć. W ograniczonym pudełku obszar przypisów jest przypięty do dołu pod cienką szarą linią długości jednej czwartej szerokości pudełka. W pomiarze nieograniczonym, jak GetHTMLTextHeight, nie ma dołu, do którego można przypiąć, więc przypisy podążają bezpośrednio za treścią

Diagram PDF Library for Delphi paginacji przypisów: obszar przypisu jest rezerwowany pod linią na dole swojego pola, przypis, który się nie mieści, wędruje do ciągu kontynuacji razem ze swoim znacznikiem, a numeracja pozostaje ciągła między stronami
Przestrzeń na przypisy jest wykrajana z budżetu treści, zanim popłynie więcej tekstu, a numeracja pozostaje ciągła między kolumnami i stronami

Numeracja startuje od 1 dla każdego świeżego łańcucha HTML. Następny numer jest przechowywany wewnątrz samego łańcucha reszty, więc łańcuchy DrawHTMLTextBox i DrawHTMLStory trzymają jedną biegnącą sekwencję przez kolumny i strony, pod warunkiem, że reszta jest przekazywana z powrotem dokładnie tak, jak została zwrócona. Przebudowanie kontynuacji z własnego tekstu źródłowego restartuje licznik

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;                 // reszta twojego rozdziału

// 2 kolumny, rynna 16 pt, co najwyżej 20 stron; historia dokłada strony sama
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode;          // czytaj raz: odczyt go zeruje

if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
  // zła geometria: kolumny 1..64, MaxPages 1..10000, rynny węższe niż Width
else if Err = PDFLIB_ERROR_HTML_STORY then
  // dwie ramki z rzędu nie zrobiły postępu
else if Rest <> '' then
  // 20 stron użyte i tekst został: kontynuuj później z Rest
  ;

DrawHTMLStory(Left, Top, Width, Height, Columns, Gutter, MaxPages, HTMLText) startuje na bieżącej stronie, wypełnia kolumny od lewej do prawej i dokłada strony o tych samych wymiarach, aż tekst się skończy albo zostanie osiągnięte MaxPages. Rozróżnienie tych trzech rozstrzygnięć to powód, by czytać LastErrorCode przed badaniem zwróconego łańcucha. Nieprawidłowe argumenty zwracają wejście niezmienione, co inaczej wygląda dokładnie jak historia, której skończyły się strony

Karmienie układu prawdziwą treścią

Dla wielokolumnowego tekstu głównego zachowanie kolumn i dzielenia wyrazów opisane w dzieleniu wyrazów i wyważonych kolumnach tekstu rządzi tym, jak przepływ wygląda wewnątrz każdej kolumny. Gdy znaczniki pochodzą z danych, a nie z ręcznie pisanych szablonów, silnik raportów ze zbioru danych jest drogą, która je generuje, zanim flex i grid je rozmieszczą na stronie. Treść, która później musi znowu opuścić PDF, przechodzi przez eksport PDF do Markdown i DOCX

Układ HTML z flexem, gridem i przypisami, generowanie raportów i eksport semantyczny płyną w jednej bibliotece dla Delphi, C++Buildera i Free Pascala. Strona produktu PDF Library for Delphi wylicza resztę renderera HTML i API rysowania