Техническая статья

Flexbox, CSS Grid и сноски в PDF из Delphi

Положим, двухколоночная глава ставит ссылку на сноску на предпоследней строке левой колонки. Однострочной заметке нужно примерно 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 дальше двигают только уже измеренные боксы

Диаграмма PDF Library for Delphi: определение размеров flex-строки — измеренные базисы и веса роста, взвешенное распределение остатка пространства по строке и проход выравнивания без сдвигов, дающий панельную строку два-к-одному-к-одному
Размер во Flex — это один ограниченный проход измерения, за которым следует взвешенное распределение остатка пространства; выравнивание лишь перемещает измеренные блоки и никогда не запускает повторное измерение
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 берут каждую свою долю свободного пространства

Диаграмма PDF Library for Delphi: допустимые значения треков сетки, детерминированное размещение по занятости с намеренно разрешённым перекрытием и элемент, охватывающий строки, возвращающий высоту, усреднённую по охваченным строкам
Треки Grid принимают длины, проценты, единицы fr, repeat и minmax, а автоматическое размещение детерминированно обходит матрицу занятости

Размещение детерминировано. Автоматически размещаемые элементы идут по сетке строка за строкой (или столбец за столбцом при 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, прикалывать не к чему, поэтому заметки следуют сразу за телом

Диаграмма PDF Library for Delphi: разбивка сносок по страницам — область сносок резервируется под линией внизу блока, не поместившаяся сноска уходит в продолжение вместе со своим маркером, а нумерация остаётся сквозной между страницами
Место под сноски вырезается из бюджета основного текста до размещения нового текста, а нумерация переживает переходы между колонками и страницами

Нумерация стартует с 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 &deg;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