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

Декларативная разметка PDF в Delphi с тегированным выводом

Абзац, который начинается внизу страницы 4 и заканчивается вверху страницы 5, для читателя остаётся одним абзацем. В тегированном PDF он живёт в двух потоках содержимого, и каждая страница нумерует свои последовательности маркированного содержимого независимо, поэтому структурному дереву нужен один элемент P, чей массив /K указывает, скажем, на MCID 7 на странице 4 и на MCID 3 на странице 5. Нарисуйте страницы координатным кодом и прикрутите тегирование потом — и дерево тегов в программе проверки доступности обычно покажет два абзаца там, где был один, плюс набор заголовков колонок, повторённый внутри данных каждой продолженной таблицы

У координатного подхода есть и вторая цена, и она проявляется раньше. Первая версия отчёта работает. Потом адрес клиента разрастается до трёх строк, локализованный заголовок переносится, таблица прирастает сорока строками — и все позиции y ниже этой точки оказываются неверными. Проверки разрывов страниц расползаются по бизнес-логике, а код, который знал только про x и y, понятия не имеет, где начинается абзац, когда через два года появится требование доступности

Построение дерева компоновки HotPDF в Delphi

HotPDF закрывает обе проблемы декларативным деревом компоновки в модуле HPDFLayoutDOM. THPDFDOMDocument владеет разделами; у каждого THPDFDOMSection есть размер страницы, поля, опциональные колонтитулы и стек Body, куда вы добавляете текст, заголовки, распорки, списки, изображения, контейнеры и таблицы. Ни один узел дерева не несёт координаты y. THPDFDOMRenderer измеряет дерево, принимает решения о разрывах страниц, рисует колонтитулы на каждой странице и, поскольку GenerateStructure по умолчанию равен True, попутно записывает структурное дерево

Владение в дереве строгое. Документ владеет своими разделами, раздел владеет телом и колонтитулами, а стеки, контейнеры и таблицы владеют своими потомками, поэтому Section.Body.Add(Table) передаёт таблицу насовсем. Компонент, привязанный к двум родителям, был бы измерен дважды под разными ограничениями и освобождён дважды при разборке. Поэтому повторяющиеся фрагменты вроде блока подписи берутся из Clone, из SetHeaderClone / SetFooterClone или из фабрики, зарегистрированной через RegisterComponent, — и каждый вызов CreateComponent('signature') возвращает свежий экземпляр

Дерево владения декларативного документа компоновки HotPDF, где разделы, колонтитулы и строки таблиц имеют ровно по одному владельцу
Каждый узел дерева раскладки имеет ровно одного владельца, поэтому помощники возвращают свежие экземпляры вместо общих ссылок, а повторяющиеся элементы оформления приходят из зарегистрированной фабрики как новый компонент при каждом вызове
uses
  SysUtils, HPDFDoc, HPDFLayoutDOM;

type
  TAssetRow = record                    // ваш собственный тип данных
    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;          // A4 книжная, поля 36 pt по умолчанию
    Section.MarginLeft := 56;
    Section.MarginRight := 56;
    Section.Style.FontName := 'Helvetica';
    Section.Style.FontSize := 10;
    Section.Style.LineHeight := 13;
    Section.Body.Style.Spacing := 6;    // зазор между потомками тела
    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
    Section.Body.AddText('Every asset inspected during the reporting ' +
      'period is listed below, grouped by site.');

    Table := THPDFDOMTable.Create('assets');  // RepeatHeaders по умолчанию True
    Table.AddColumn(3);                 // веса, а не ширины в пунктах
    Table.AddColumn(1);
    Table.AddColumn(1);
    Row := Table.AddRow(18, True);      // строки заголовка должны идти первыми
    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);            // дальше таблицей владеет тело
    Result := Doc;
  except
    Doc.Free;
    raise;
  end;
end;

Два значения по умолчанию в этом листинге подлавливают многих. LineHeight разворачивается в 12 пунктов, если стиль в цепочке его не задаёт, — что бы ни говорил FontSize, поэтому заголовок 18 pt без собственного LineHeight получает строки в 12 pt и наезжает на следующий. А строка таблицы ровно настолько высока, насколько указано в AddRow: текст ячейки выводится одной строкой, так что закладывайте высоту строк под выбранный шрифт

Render сам открывает и закрывает документ

THPDFDOMRenderer.Render(Doc, Pdf) вызывает BeginDoc у цели, рендерит все разделы и перед возвратом вызывает EndDoc. Не оборачивайте его в собственную пару BeginDoc / EndDoc. Всё, что нужно установить до старта документа, задаётся на экземпляре THotPDF заранее: FileName, Title и PDFUACompliance, если результат должен заявлять PDF/UA. Когда генерация структуры включена, Render ещё и включает EnableTaggedPDF и копирует Doc.Language в Pdf.Lang, если вы оставили его пустым

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;        // заодно включает проверку alt-текста изображений
    // Здесь нет BeginDoc / EndDoc: Render сам открывает и закрывает документ
    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;

Логируйте запись со статистикой при каждом прогоне: она показывает регрессии шаблона, которые ни разу не вызывают исключения. Скачок SplitCount после изменения шаблона обычно означает, что какой-то компонент теперь измеряется выше, чем место, в которое раньше вмещался. Ползущий вверх MaximumContinuationDepth указывает на компонент, чей Split переносит слишком мало содержимого за страницу. ArtifactCount учитывает колонтитулы страниц, декоративные рамки вроде рамки таблицы 0.5 pt по умолчанию и повторяемые строки заголовков, поэтому сравнивайте его между запусками одного шаблона, а не с вручную посчитанной целью

Как длинная таблица разбивается на страницы без копирования себя на каждой странице?

Рендерер разрезает только то, что пересекает границу страницы. Наивный способ разбить дерево на страницы — клонировать всё, что не влезло, и перенести копию на следующую страницу; для таблицы с 10 000 строк это клонирует оставшиеся строки на каждой странице и превращает линейную работу в квадратичную. HotPDF идёт по потомкам тела по индексу и никогда не клонирует раздел или тело целиком. Вложенный стек или контейнер, пересёкший границу страницы, получает клон только своего затронутого поддерева, а два тяжёлых листовых типа несут курсор вместо копии

Продолженный абзац — это ссылка на исходный текст плюс диапазон символов, который он ещё должен, и он переиспользует переносы строк, уже вычисленные для этой ширины. Продолженная таблица — ссылка на исходную таблицу плюс срез строк, которые ещё предстоит разместить. Абзац на 300 строк стоит одинаково, рвётся ли он один раз или пять

Столбчатая диаграмма: квадратичная стоимость разбивки на страницы от клонирования целых поддеревьев против плоской линейной стоимости от узких разрезов на границах страниц в HotPDF
Клонирование всего неразмещённого поддерева на каждой пересекаемой странице превращает лишние строки в квадратичную работу, тогда как узкий разрез позволяет длинному тексту нести курсор диапазона символов, а таблицам — курсор среза строк

Само размещение идёт через публичный THotPDF.PlaceLayoutElement. Он измеряет элемент по оставшейся высоте тела, рисует его целиком, если тот влезает, иначе просит Split, повторно измеряет размещённую половину, рисует её и возвращает остаток как объект переполнения, который рендерер уносит на свежую страницу. Measure не должен ничего рисовать; на одно размещение он может выполниться несколько раз. Поверх этой процедуры DOM-рендерер добавляет колонтитулы, отступы между потомками и решения о новой странице

Почему одна строка заголовка может остановить весь рендер?

У повторяемых заголовков таблицы два правила, и оба существуют, чтобы отчёт не плодил страницы без данных. Строки заголовка должны образовывать первую группу строк: AddRow(Height, True) после любой строки данных поднимает EInvalidOpException с сообщением "Table header rows must precede body rows". И первый разрез таблицы должен вмещать все строки заголовка плюс хотя бы одну строку данных. Таблица, которая оставила бы заголовок сиротой в конце страницы, вместо этого переходит на следующую

У второго правила жёсткий край. Если строки заголовка плюс одна строка данных не влезают даже на пустую страницу, страницы, на которой таблица могла бы начаться, не существует, и Render поднимает "Layout component ... cannot fit an empty body page" с путём компонента, например Sections[0]/Body/Items[2]/assets. Это именно то поведение, которое стоит иметь. Движок компоновки, который продолжал бы добавлять страницы в надежде, что следующая окажется просторнее, превратил бы один негабаритный заголовок в цикл, забивающий диск

Пользовательские компоненты получают ту же защиту. Унаследуйтесь от THPDFDOMComponent, реализуйте Clone, Measure, Draw и Split — и рендерер считает, сколько продолжений даёт каждый потомок тела. Выше THPDFDOMRenderer.MaximumContinuationDepth (100 000 по умолчанию) рендер останавливается с "exceeded the continuation depth limit". Split, который раз за разом возвращает эквивалентный хвост и потому не двигается вперёд, падает с путём компонента вместо того, чтобы работать до заполнения диска

На страницах-продолжениях строки заголовка рисуются заново внутри последовательности маркированного содержимого /Artifact, а структурное дерево хранит исходный TR ровно один раз. Поэтому извлечение текста не вставляет дубликат строки заголовка между строками данных, а ассистивные технологии не объявляют названия колонок заново посреди таблицы. Каждая ячейка заголовка тегируется как TH с атрибутом /Scope /Column

Один логический абзац, несколько страничных фрагментов

Разрезанный абзац остаётся одним элементом структуры P. Каждый видимый фрагмент открывает новую последовательность маркированного содержимого на своей странице, и HotPDF добавляет словарь ссылки на маркированное содержимое, << /Type /MCR /Pg page /MCID n >>, в массив /K этого элемента и регистрирует MCID в записи ParentTree страницы, указывающей обратно на тот же элемент. Именно такую схему ISO 32000-1 §14.7.4 описывает для элементов содержимого, раскиданных по страницам, и именно она позволяет виду дерева тегов показывать один абзац там, где страницы показывают два куска

Причина, по которой копии-продолжения ведут себя не так, как ваши собственные клоны, — семантическая идентичность. Вызов Clone означает "новое логическое содержимое", и результат получает новый элемент структуры при отрисовке. Копии, сделанные при разбивке на страницы, наследуют идентичность компонента, который они продолжают, поэтому стек, разрезанный на три страницы, всё равно даёт один Div, а список, разрезанный на две, — один L. Колонтитулы страниц идут другим путём: на каждой странице они оборачиваются в /Artifact << /Type /Pagination /Subtype /Header >> (или /Footer) и никогда не попадают в структурное дерево

Диаграмма HotPDF: один тегированный абзац хранится как единый элемент структуры PDF, его два фрагмента страниц несут отдельные идентификаторы маркированного содержимого, а перерисованный заголовок тегируется как артефакт
Фрагменты одного абзаца делят один элемент структуры через пары Pg и MCID, собранные в его массиве K, а колонтитул, перерисованный на страницах-продолжениях, едет следом как артефакт, а не содержимое

Правила структуры, проверяемые прямо во время рендера дерева

При включённом GenerateStructure рендерер отказывается строить структуру, которую валидация PDF/UA отвергла бы позже. Первый заголовок обязан быть H1, а последующие не могут перескакивать уровни, поэтому H3 сразу после H1 поднимает "Semantic heading levels cannot skip an intermediate level". LI нужен родитель L, Lbl и LBody требуют LI, TR — таблицу или группу строк, а TH / TD — TR. Когда у цели установлен PDFUACompliance, отвергается и Figure без альтернативного текста. Каждое нарушение останавливает Render исключением

var
  List: THPDFDOMList;
  Bmp: TBitmap;                         // Vcl.Graphics
begin
  Section.Body.AddHeading('Findings', 2);     // H1 был первым, поэтому H2 легален

  List := THPDFDOMList.Create('Decimal');     // тегируется L, 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 и LBody

  Bmp := TBitmap.Create;
  try
    Bmp.LoadFromFile('site-plan.bmp');
    // Изображение копирует графику; пустой alt-текст провалится при PDFUACompliance
    Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
      'Site plan of plant 3 with the inspected pumps circled'));
  finally
    Bmp.Free;
  end;
end;

Проверка во время рендера — правильное место для этих правил. Причина — тайминг. Валидатор, который сообщит о недостающем альтернативном тексте после записи файла, известит, что партию из 10 000 счетов придётся перегенерировать; исключение во время Render называет нарушенное правило, пока породившая его запись ещё в области видимости. Формальная проверка соответствия всё равно нужна в конвейере, и поскольку объекты документа остаются читаемыми после возврата Render, её можно запустить сразу. Этот шаг покрывает валидация PDF/A, PDF/X и PDF/UA, а порядок структуры и извлечение текста показывает, как дерево тегов управляет тем, что инструменты извлечения читают обратно

Когда по-прежнему рисовать вручную

Дерево рисует на тех же объектах THPDFPage, что и прямой API. Поскольку Render владеет документом от BeginDoc до EndDoc, рисованная вручную графика вроде изображения подписи должна жить внутри дерева: Draw пользовательского компонента получает страницу и её границы и может вызывать там обычные методы страницы. Закрытие страницы остаётся за AddPage и EndDoc, поэтому с установленным ImmediateFlushLayout на экземпляре THotPDF готовые страницы записываются по ходу рендера, и рендерер не держит завершённых страниц; память тогда зависит от открытых продолжений, шрифтовых ресурсов и графа объектов документа

Текстовый компонент DOM переносит строки по оценочному среднему шагу 0.55 × кегль на символ и даёт каждой строке вычисленный LineHeight. Это делает измерение дешёвым и одинаковым на любой машине, и для отчётов, управляемых данными, этого достаточно. Текст с широкими глифами — капителью, жирными прогонами или CJK — выходит шире оценки, поэтому оставляйте запас в ширинах таких колонок и один раз прогоните вёрстку с самой длинной реальной строкой. Наборные страницы с точными метриками глифов, смешанными шрифтами в одной строке или выключкой по формату лучше обслуживает прямой текстовый API; этот путь разобран в выключке текста, а если болит только разбивка таблиц на страницы, меньшим изменением станет генерация таблиц в PDF

Дерево компоновки, его рендерер, описанное здесь тегирование и прямой API рисования поставляются в одном компоненте для Delphi и C++Builder; редакции и полный список возможностей — на странице компонента HotPDF Delphi PDF