Положим, двухколоночная глава ставит ссылку на сноску на предпоследней строке левой колонки. Однострочной заметке нужно примерно 14 пунктов внизу той колонки, а осталось 9. Оба очевидных исхода неправильны: нарисовать заметку всё равно — и она напечатается поверх основного текста, или отправить вперёд одну заметку — и она окажется под правой колонкой, рядом с текстом, с которым её ничего не связывает. Браузеру делать такой выбор никогда не приходится, потому что у веб-страницы нет нижней кромки. Flexbox и CSS Grid проектировались под тем же допущением, поэтому как только отчётному HTML приходится укладываться на страницы фиксированного размера, каждому из них нужно правило, что происходит, когда в боксе кончается высота
Гибкий дашборд-ряд в боксе фиксированной ширины
PDF Library for Delphi трактует любой элемент со стилем display: flex или display: inline-flex как настоящий flex-контейнер, поэтому ряд карточек остаётся рядом, а не схлопывается в сложенные блоки. Рисуется он через DrawHTMLTextBox(Left, Top, Width, Height, HTMLText), возвращающий WideString: пустой, когда всё поместилось, иначе — часть, которую ещё предстоит нарисовать где-то ещё
В направлении ряда каждый элемент получает базис, базисы и промежутки суммируются, а остаток на линии раздаётся дальше. Положительное пространство уходит по flex-grow. Отрицательное забирается обратно через flex-shrink, умноженный на базис элемента, — это правило CSS, и у него есть приятный побочный эффект, показанный чуть ниже. При заданном flex-wrap элементы уходят на новую линию, как только следующий базис перестаёт помещаться, и каждая линия распределяет своё свободное пространство сама. justify-content, align-items, align-content, gap и направления -reverse дальше двигают только уже измеренные боксы
uses
SysUtils, PDFlibrary;
var
Lib: TPDFlib;
Html, Remainder: WideString;
begin
Lib := TPDFlib.Create;
try
Lib.SetOrigin(1); // начало в левом верхнем углу: Top растёт вниз по странице
Lib.SetPageSize('A4');
// Процентные базисы держат отношение 2:1:1 точным, промежутки включительно
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 пунктов. Промежуток 12px — это 9 пунктов, два промежутка стоят 18. Базисы в сумме дают все 515, промах ровно на те самые 18 пунктов. Сжатие взвешено базисом, поэтому карточка 50% отдаёт 9 пунктов, а каждая карточка 25% — по 4.5, оставляя 248.5, 124.25 и 124.25. Отношение по-прежнему ровно 2:1:1, и коду ни разу не пришлось вычитать промежутки вручную
Почему равные flex: 1 выходят неравными?
Потому что их базис — это ширина их содержимого. Рендерер берёт базис из flex-basis, из длины внутри сокращения flex (значение с pt, px, em или %) или из width. Когда ни одно из них не даёт положительной длины, базисом становится измеренная ширина содержимого. Голый flex: 1 и браузерная идиома flex: 1 1 0 оба оказываются там, поскольку безразмерный 0 не читается как длина. Равные коэффициенты роста добавляют равные доли свободного пространства поверх неравных стартовых ширин
Соберите тот же дашборд с flex: 1 на каждой карточке — и карточка Revenue, чья семизначная цифра делает её содержимое самым широким из трёх, стартует шире карточки Margin и остаётся шире ровно на эту величину после роста, потому что каждая карточка получает одинаковую треть оставшегося свободного пространства. Для тулбаров, списков тегов и рядов кнопок это часто ровно тот вид, что нужен. Для дашборда — нет. Всё, что обязано выстраиваться с таблицей сверху или снизу, заслуживает явных процентных или пунктовых базисов с ростом 0 — это наша рекомендация и ровно то, что делает пример: три карточки попадают в 248.5, 124.25 и 124.25 пункта на каждой странице, что бы ни говорили цифры внутри них
Направление столбца следует той же логике на вертикальной оси. Базис приходит из flex-basis или height, иначе — из измеренной высоты содержимого, а свободное пространство есть только когда контейнер объявил height. Без него контейнер ровно настолько же высок, как его элементы, и justify-content нечего распределять
Треки сетки, размещение и охват
Для display: grid PDF Library for Delphi читает grid-template-columns и grid-template-rows как фиксированные длины, проценты, единицы fr, repeat(n, track) и minmax(a, b). Фиксированные треки и промежутки вычитаются из доступной ширины, остаток делится по весам fr. Трек minmax() размеряется по второму аргументу, поэтому minmax(120px, 1fr) ведёт себя как 1fr, а треки auto, min-content и max-content берут каждую свою долю свободного пространства
Размещение детерминировано. Автоматически размещаемые элементы идут по сетке строка за строкой (или столбец за столбцом при grid-auto-flow: column) и пропускают занятые ячейки. Элемент с заданной только строкой ищет в той строке свободный столбец; элемент с заданным только столбцом ищет вниз по тому столбцу. Элементы с обеими координатами попадают ровно туда, куда сказано, даже поверх другого элемента — так бейдж оказывается наложенным на карточку
Охватам нужна одна привычка. Рендерер читает охват из части после слеша, как в grid-row: 1 / span 2, или из grid-row-end: span 2 и grid-column-end: span 2. Голый grid-row: span 2, который браузеры принимают как целое значение, в тех написаниях не значится, так что держите стартовую линию и слеш
// Лист осмотра: фиксированная колонка подписей, две гибкие колонки
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);
В том боксе на 515 пунктов колонка подписей — 120 пунктов, два промежутка берут 12, и каждый столбец 1fr получает по 191.5. Ячейка Site plan имеет строку, но не столбец, поэтому попадает в столбец 1 и накрывает строки 1 и 2. Inspector и Date заполняют остаток строки 1. У сводки есть столбец, но нет строки, поэтому размещение ищет вниз по столбцу 2, находит строку 1 занятой и оседает в строке 2 на обеих гибких колонках
Высоты строк приходят из содержимого. Поскольку охватывающий элемент делит свою измеренную высоту поровну между строками, которые покрывает, и каждая строка потом берёт наибольшую долю, которую запросил любой её элемент, лишняя высота высокой ячейки размазывается по каждой строке, которой она касается, а не сваливается на первую. Высокая ячейка Site plan поэтому приподнимает обе строки понемногу, а не растягивает только первую, оставляя Findings summary висеть в дыре
Контейнеры переезжают между боксами целиком
Flex- или grid-контейнер никогда не режется между двумя боксами. Никогда. Когда контейнер целиком не влезает в оставшееся пространство, контейнер и всё после него уходят в возвращаемую строку продолжения, а поскольку продолжение — это ровно то, что вы передаёте следующему боксу или следующей странице, ряд карточек просто открывает следующий кадр с нетронутой измеренной геометрией. Половина плитки KPI внизу страницы 3 и вторая половина на странице 4 хуже дыры — вот компромисс, на который идёт это правило. Исключение — контейнер выше целого пустого бокса: он всё равно рисуется сверху того бокса и перебегает его нижнюю кромку, потому что никакой последующий бокс не был бы больше
Практическое следствие: высоту контейнера стоит знать до того, как вы отправили его на страницу. GetHTMLTextHeight(Width, HTMLText) измеряет без рисования, flex и grid включительно
// GridHtml, Y и PageBottom принадлежат вашему коду отчёта
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;
Измерение ограничено намеренно, что важно, когда шаблоны правят клиенты. Flex- или grid-контейнер берёт первые 256 прямых детей, размещение в сетке работает в пределах 64 строк, а список треков держит максимум 64 трека, с ограниченными соответственно счётчиками repeat(). Flex-контейнер с сотнями детей почти всегда — таблица данных в маскировке, и табличный путь со своим измерением колонок и поддержкой rowspan разложит её лучше
Как сноски удерживаются со своими ссылками?
PDF Library for Delphi измеряет каждую заметку в момент встречи со ссылкой и вычитает её высоту из бюджета тела текущего бокса. Заметка записывается как <aside style="float:footnote">, <aside role="doc-footnote"> или элемент <footnote>. Ссылка становится надстрочным номером в две трети окружающего размера шрифта, а текст заметки набирается 8 пунктами на кегле 10 с тем же номером впереди
Если тело на данный момент плюс новая заметка больше не помещаются, маркер и всё после него уходят в продолжение вместе. Заметка и ссылка путешествуют парой. Это и есть ответ на вводный сценарий: строка ссылки и её заметка открывают следующую колонку, и ни наложение, ни осиротевшая заметка не случаются. В ограниченном боксе область заметок приколота к низу под тонкой серой линией длиной в четверть ширины бокса. При неограниченном измерении, как в GetHTMLTextHeight, прикалывать не к чему, поэтому заметки следуют сразу за телом
Нумерация стартует с 1 для каждой свежей HTML-строки. Следующий номер хранится внутри самой строки продолжения, поэтому цепочки DrawHTMLTextBox и DrawHTMLStory держат одну сквозную последовательность через колонки и страницы — пока продолжение передаётся назад ровно в том виде, в каком вернулось. Пересборка продолжения из собственного исходного текста перезапускает счёт
Chapter :=
'<p>The bearing stayed within tolerance for the full six hours' +
'<aside style="float:footnote">Ambient temperature held at ' +
'21 °C throughout the run.</aside> of the load test.</p>' +
MoreChapterHtml; // остаток вашей главы
// 2 колонки, желоб 16 pt, максимум 20 страниц; история добавляет страницы сама
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode; // читать один раз: чтение сбрасывает
if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
// плохая геометрия: Columns 1..64, MaxPages 1..10000, желоб уже Width
else if Err = PDFLIB_ERROR_HTML_STORY then
// два кадра подряд без прогресса
else if Rest <> '' then
// израсходовано 20 страниц, текст остался: продолжить позже с Rest
;
DrawHTMLStory(Left, Top, Width, Height, Columns, Gutter, MaxPages, HTMLText) стартует на текущей странице, заполняет колонки слева направо и добавляет страницы тех же размеров, пока не кончится текст или не будет достигнут MaxPages. Различить три этих исхода — причина прочитать LastErrorCode до проверки возвращённой строки. Невалидные аргументы возвращают ввод неизменным, что иначе выглядит в точности как история, кончившаяся страницами
Кормим раскладку настоящим содержимым
Для многоколоночного тела колонки и переносы, описанные в статье перенос по слогам и сбалансированные текстовые колонки, управляют тем, как поток выглядит внутри каждой колонки. Там, где разметка приходит из данных, а не из рукописных шаблонов, маршрут — движок отчётов на основе набора данных, который генерирует её до того, как flex и grid разложат по странице. Содержимое, которому позже придётся снова покинуть PDF, идёт через экспорт PDF в Markdown и DOCX
Раскладка HTML с flex, grid и сносками, генерация отчётов и семантический экспорт поставляются в одной библиотеке для Delphi, C++Builder и Free Pascal. Остальную часть HTML-рендерера и API рисования перечисляет страница продукта PDF Library for Delphi