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

Метаданные, оглавления и аннотации PDF: подробное объяснение

Один и тот же PDF может отрапортовать двух разных авторов. Диалог свойств настольного вьюера показывает одно имя, система управления активами, индексирующая XMP, — другое, и обе программы читают файл правильно. PDF хранит метаданные документа дважды, а закладки, ссылки и заметки держит в структурах, которые никогда не касаются содержимого страниц, поэтому любая из них может быть неверной, пока каждая страница рендерится идеально

Объектная модель под этим (косвенные объекты, таблица перекрёстных ссылок, трейлер) разобрана в пошаговом разборе структуры PDF-документа. Здесь фокус остаётся на том, что висит на каталоге документа

Четыре записи в каталоге, четыре независимые подсистемы

Всё обсуждаемое ниже достигается из каталога документа — словаря, на который указывает запись /Root трейлера (ISO 32000-1 §7.7.2). Каталог, подключающий всё это, выглядит так:

1 0 obj
<< /Type /Catalog
   /Pages 2 0 R
   /Outlines 3 0 R
   /Names << /EmbeddedFiles 4 0 R /Dests 6 0 R >>
   /Metadata 5 0 R
>>
endobj
Диаграмма каталога PDF-документа: связи с деревом страниц, корнем оглавления, словарём имён и потоком метаданных XMP как четырьмя опциональными подсистемами
Каталог документа соединяет четыре независимые подсистемы, каждая доступна через свою запись. Любая может отсутствовать, пока страницы всё ещё отображаются нормально

/Pages — видимый документ, и единственная из четырёх записей, которую каталог требует. /Outlines ведёт к дереву закладок, /Metadata — к потоку XMP, /Names — к словарю имён, хранящему вложенные файлы под /EmbeddedFiles и именованные цели под /Dests. Читатель, не нашедший ни одной из трёх опциональных, всё равно покажет каждую страницу, поэтому именно этот слой деградирует первым, когда файл проходит через инструменты, понимающие только страницы. Ничто внутри объекта страницы не указывает назад на оглавление, дерево /Dests или поток XMP. Скопируйте одни страницы в новый файл — и все три останутся позади

Почему PDF несёт два хранилища метаданных?

PDF несёт два хранилища метаданных, потому что формат отрастил второе, не списав первое. Исходный механизм — словарь информации о документе (ISO 32000-1 §14.3.3, Table 317), на который ссылается /Info в трейлере: плоские текстовые записи для /Title, /Author, /Subject, /Keywords, /Creator, /Producer плюс /CreationDate, /ModDate и /Trapped. ISO 32000-2 объявляет устаревшим весь словарь, кроме двух записей о датах, и отправляет писателей к потоку метаданных XMP

Диаграмма сравнения словаря Info PDF и потока метаданных XMP: два хранилища с пересекающимися полями, которые должны оставаться синхронными, при этом XMP — источник истины
Словарь Info и поток XMP отвечают на одни вопросы параллельно. Держите их синхронно, регенерируя оба из одного набора значений

XMP (ISO 32000-1 §14.3.2) — XML-документ, написанный на RDF, хранимый в потоке, чей словарь несёт /Type /Metadata /Subtype /XML. В отличие от словаря Info, пакет XMP спроектирован так, чтобы его находили и разбирали инструменты, не знающие ничего о синтаксисе PDF:

5 0 obj
<< /Type /Metadata /Subtype /XML /Length 1235 >>
stream
<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>
<x:xmpmeta xmlns:x="adobe:ns:meta/">
  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <rdf:Description rdf:about=""
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:xmp="http://ns.adobe.com/xap/1.0/"
        xmlns:pdf="http://ns.adobe.com/pdf/1.3/">
      <dc:title><rdf:Alt><rdf:li xml:lang="x-default">Quarterly Report</rdf:li></rdf:Alt></dc:title>
      <dc:creator><rdf:Seq><rdf:li>A. Author</rdf:li></rdf:Seq></dc:creator>
      <xmp:CreateDate>2026-06-16T10:46:27+08:00</xmp:CreateDate>
      <xmp:CreatorTool>Reporting Service 4.2</xmp:CreatorTool>
      <pdf:Producer>losLab PDF Library</pdf:Producer>
    </rdf:Description>
  </rdf:RDF>
</x:xmpmeta>
<?xpacket end="w"?>
endstream
endobj

Три детали в этом блоке решают, переживёт ли пакет контакт с реальными инструментами. Инструкции обработки xpacket обрамляют пакет, чтобы сканер мог найти его внутри произвольного байтового потока; выбросите закрывающий <?xpacket end="w"?> — файл всё равно откроется, но сканеры потеряют конечный маркер. Типы значений тоже важны: dc:title — языковая альтернатива и требует rdf:Alt, а dc:creator — упорядоченный список и требует rdf:Seq. Записать любое из них голым текстовым узлом — лёгкая ошибка. Префиксы же — только конвенция; парсер ключуется по URI пространства имён, поэтому dc:, привязанный к чужому URI, — уже другое свойство

Ключи Info и их XMP-двойники складываются в пары так. PDF/A-1 (ISO 19005-1 §6.7.3) формулирует сопоставление как правило соответствия: когда присутствуют оба хранилища, значения обязаны быть эквивалентны

Info dictionaryXMP property
/Titledc:title (rdf:Alt)
/Authordc:creator (rdf:Seq)
/Subjectdc:description (rdf:Alt)
/Keywordspdf:Keywords
/Creatorxmp:CreatorTool
/Producerpdf:Producer
/CreationDate, /ModDatexmp:CreateDate, xmp:ModifyDate

Ручные правки и слияния — то место, где два хранилища расходятся. Слияние может унаследовать /Info от одного входа, а пакет XMP — от другого. Более безопасное правило: считать XMP источником истины, держать /Info для старых потребителей и регенерировать оба из одного набора значений всякий раз, когда меняется хоть один

Запись обоих хранилищ из одного набора свойств

HotPDF строит оба хранилища из одних свойств документа. Title, Author, Subject и Keywords идут в /Info; при EnableXMPMetadata в True EndDoc вдобавок пишет пакет XMP из тех же значений — с dc:title как rdf:Alt и dc:creator как rdf:Seq — и связывает его через /Metadata каталога. EnableXMPMetadata по умолчанию False, и стоит включать его для всего, что покидает ваши руки: файл с одним /Info невидим для каждого инструмента, читающего только XMP. CustomXMP подменяет сгенерированный пакет вашим текстом, когда нужны дополнительные схемы

uses
  System.SysUtils, Vcl.Graphics, HPDFDoc;

procedure BuildReport(const FileName: string);
var
  PDF: THotPDF;
  Chapter: THPDFDocOutlineObject;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.AutoLaunch := False;
    PDF.FileName := FileName;
    // Один набор значений кормит и /Info, и пакет XMP
    PDF.Title := 'Quarterly Report';
    PDF.Author := 'A. Author';
    PDF.Subject := 'Results for the third quarter';
    PDF.Keywords := 'quarterly, results';
    PDF.EnableXMPMetadata := True;
    PDF.BeginDoc;

    PDF.CurrentPage.SetFont('Arial', [fsBold], 20);
    PDF.CurrentPage.TextOut(50, 50, 0, 'Chapter 1: Results');
    Chapter := PDF.OutlineRoot.AddChild('Chapter 1: Results', 0, 50);
    Chapter.Opened := True;   // сохраняется как положительный /Count

    PDF.AddPage;
    PDF.CurrentPage.SetFont('Arial', [fsBold], 16);
    PDF.CurrentPage.TextOut(50, 50, 0, 'Introduction');
    Chapter.AddChild('Introduction', 0, 50);

    PDF.AddPage;
    PDF.CurrentPage.SetFont('Arial', [fsBold], 16);
    PDF.CurrentPage.TextOut(50, 50, 0, 'Methodology');
    Chapter.AddChild('Methodology', 0, 50);

    PDF.EndDoc;
  finally
    PDF.Free;
  end;
end;

Редактирование существующего файла устроено иначе. На загруженном документе SetLoadedTitle, SetLoadedAuthor, SetLoadedCreator и их собратья пишут запись словаря Info, а поток XMP — отдельный объект, который вы подменяете через SetLoadedXMPMetadata. Смените автора одним вызовом и не смените другим — и SaveLoadedDocument выдаст ровно тот файл с двумя авторами из первого абзаца

Дерево оглавления за панелью закладок

Панель закладок восстанавливается из двусвязного дерева словарей — оглавления документа (ISO 32000-1 §12.3.3, Tables 152 и 153). Никакого массива закладок в файле нет; вьюер реконструирует панель, следуя ссылкам от /Outlines каталога

Диаграмма дерева оглавления PDF: ссылки Parent, First, Last, Prev, Next и Count, восстанавливающие панель закладок просмотрщика
Панель закладок перестраивается из двусвязного дерева оглавления, прошитого Parent, First, Last, Prev, Next и Count. Одна устаревшая ссылка прячет целую ветку без единой ошибки
8 0 obj                                    % the outline root
<< /Type /Outlines /Count 3 /First 9 0 R /Last 9 0 R >>
endobj
9 0 obj                                    % top-level: a chapter
<< /Title (Chapter 1: Results)
   /Parent 8 0 R /Count 2
   /First 12 0 R /Last 15 0 R
   /Dest [3 0 R /XYZ 0 792 0] >>
endobj
12 0 obj                                   % first child
<< /Title (Introduction)
   /Parent 9 0 R /Next 15 0 R
   /Dest [4 0 R /XYZ 72 720 0] >>
endobj
15 0 obj                                   % second child, last sibling
<< /Title (Methodology)
   /Parent 9 0 R /Prev 12 0 R
   /Dest [5 0 R /Fit] >>
endobj

Инварианты читаются прямо со ссылок. Каждый элемент указывает назад на свой /Parent. Братья сцеплены через /Prev и /Next; у первого ребёнка нет /Prev, у последнего нет /Next. Родитель называет оба конца через /First и /Last, а всё между ними существует лишь как шаг в обходе братьев. Разорвите одну ссылку — и вьюеры покажут то, до чего ещё дотягиваются: устаревший /Next обрезает главу, а /Last, не согласующийся с концом цепочки, оставляет разные вьюеры рисующими разные деревья

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

В HotPDF OutlineRoot — это THPDFDocOutlineObject, и AddChild(Title, X, Y) дописывает элемент, прошивает его /Parent, /Prev, /Next, /First и /Last и целит его в текущую страницу как [page /XYZ left top 0]. Свойство Opened решает знак, а писатель пересчитывает каждый /Count по готовому дереву на EndDoc, так что выставить Opened после добавления детей — нормально. InsertBefore, InsertAfter и MoveTo перестраивают дерево с той же бухгалтерией

Цели перехода: куда на самом деле приземляется щелчок

Закладки и аннотации-ссылки обе разрешаются в цель перехода (ISO 32000-1 §12.3.2, Table 151), а цель — больше, чем номер страницы. Это массив, называющий объект страницы, а затем тип кадрирования, сообщающий вьюеру, как его показать. Рабочая лошадка — [page /XYZ left top zoom]. Любой из трёх операндов может быть null — «оставить, что было у читателя», а zoom 0 значит то же, что null. Поэтому [page /XYZ null null null] меняет страницу и больше ничего — обычно именно это и должна делать ссылка «перейти на страницу»

Семейство /Fit меняет точное позиционирование на устойчивость. [page /Fit] масштабирует всю страницу в окно, [page /FitH top] вписывает ширину страницы с заданным верхним краем, [page /FitR left bottom right top] зумит прямоугольник, чтобы заполнить вид. Они вычисляют масштаб из геометрии страницы в момент щелчка; /XYZ с вшитым зумом сохраняет его даже после изменения размера страницы. Для оглавления /FitH по верхнему краю раздела — дефолт лучше

Координаты — то место, где люди обжигаются. Числа целей заданы в пользовательском пространстве по умолчанию: начало в левом нижнем углу, y растёт вверх (§8.3.2.3), тогда как привычки экранной вёрстки меряют от верха. Canvas-подобные вызовы HotPDF (TextOut, прямоугольники ссылок, X и Y у AddChild) принимают координаты сверху-вниз и конвертируют за вас. RegisterNamedDestination пишет свои Left и Top в массив цели как есть, поэтому они уже обязаны быть в пользовательском пространстве PDF:

// Вызов между BeginDoc и EndDoc, когда страницы 0..2 уже существуют
procedure AddContentsLinks(PDF: THotPDF);
var
  R: TRect;
begin
  // Именованная цель на 50 pt ниже верха страницы 1.
  // Top в пользовательском пространстве PDF, отмеряется вверх от нижнего края
  PDF.CurrentPageNumber := 1;
  PDF.RegisterNamedDestination('chapter-1', 1, dfmFitH,
    0, PDF.CurrentPage.Height - 50, 0, 0, 0);

  // Запрос оглавления на странице 0; прямоугольники в координатах сверху-вниз
  PDF.CurrentPageNumber := 0;
  R := Rect(50, 175, 545, 209);
  PDF.CurrentPage.AddNamedDestinationLink(R, 'chapter-1', 'Chapter 1: Results');

  // YPos = -1 пишет [page /XYZ null null null]: сменить страницу, храня вид
  R := Rect(50, 225, 545, 259);
  PDF.CurrentPage.AddGoToLink(R, 2, -1, 'Methodology');

  R := Rect(50, 275, 545, 309);
  PDF.CurrentPage.AddURILink(R, 'https://www.example.com', 'Project website');
end;

Передайте экранные 50 как Top — и ссылка приземлится на 50 пунктов выше нижнего края, показав подвал вместо заголовка. Именованная цель живёт в дереве имён /Dests каталога, и каждая ссылка разрешается через имя, поэтому при десятках ссылок в одни и те же главы это правильный выбор. Переставьте раздел — вы правите одну запись в /Dests; все ссылки, называющие её, следуют за ней. Порядок страниц, от которого зависят эти цели, разобран в статье о том, почему важен порядок дерева страниц

Аннотации: интерактивные объекты вне content stream

Аннотация сидит на странице, не будучи частью её content stream (ISO 32000-1 §12.5). Ссылки, стикеры, выделения, виджеты форм, значки вложений и штампы живут в массиве /Annots своей страницы. Уберите запись — аннотация исчезнет, а content stream останется байт в байт тем же

Каждая аннотация делит небольшое ядро (Table 164): /Subtype называет вид, /Rect даёт габаритный бокс в пользовательском пространстве по умолчанию, /Contents держит текст, заодно служащий альтернативным описанием, которое зачитывает assistive technology. Аннотации-ссылки (§12.5.6.5, Table 173) бывают двух форм:

20 0 obj                                    % link to a destination
<< /Type /Annot /Subtype /Link
   /Rect [100 200 300 250]
   /Border [0 0 0]
   /Dest [5 0 R /XYZ null null null] >>
endobj
21 0 obj                                    % link that runs an action
<< /Type /Annot /Subtype /Link
   /Rect [50 50 200 100]
   /Border [0 0 0]
   /Contents (Project website)
   /A << /Type /Action /S /URI /URI (https://www.example.com) >> >>
endobj

/Border [0 0 0] тут неспроста: рамка по умолчанию — [0 0 1], одно-пунктовая рамка, которую многие вьюеры рисуют вокруг каждой ссылки. /Dest и /A взаимно исключают друг друга, а /S действия выбирает поведение: /GoTo внутри этого файла (§12.6.4.2), /GoToR для страницы другого PDF (§12.6.4.3), /URI для веб-адреса (§12.6.4.7), /Launch для запуска внешнего приложения или файла (§12.6.4.5). Оставьте /Launch вне распространяемых документов: вьюеры обычно блокируют его или ставят перед ним предупреждение безопасности, а PDF/A запрещает его вовсе (ISO 19005-1 §6.6.1). Аргумент Description вызовов ссылок выше заполняет /Contents, и при включённом PDFUACompliance HotPDF пустое описание бросает исключением, поскольку PDF/UA-1 требует эту запись на каждой ссылке

Аннотации разметки вроде выделений и заметок и фигуры вроде /Square добавляют нюанс: их вид не закреплён типом. Без appearance stream (запись /AP, §12.5.5) каждый вьюер рисует собственную версию. ISO 32000-2 делает /AP обязательным для большинства типов аннотаций, исключая Popup и Link. Вложения используют тот же механизм: поток встроенного файла, завёрнутый в file specification (§7.11), выведенный либо как аннотация /FileAttachment на странице, либо через дерево имён /EmbeddedFiles под /Names каталога

Как проверить этот слой до отправки файла?

Две проверки ловят большую часть: щёлкайте панель закладок и выборку ссылок в настоящем вьюере, затем перечитывайте метаданные программой, потому что никакое число щелчков не выявит /Info, расходящийся с XMP. Вызовы HotPDF для загруженных документов покрывают обе половины. GetLoadedOutlineTitlesDeep обходит цепочку /First и /Next в глубину — тот же обход, что делает вьюер, поэтому ветвь, отрезанная устаревшей ссылкой, отсутствует и в его результате. FindLoadedOutlineByTitle разрешает целевую страницу закладки и докладывает -1, когда цель — именованная цель или не разрешается в страницу

// StripXmlTags — хелпер, который вы добавляете сами; это не вызов call.
// библиотеки. GetLoadedXMPValue возвращает внутреннюю разметку элемента,
// поэтому dc:creator возвращается обёрнутым в теги rdf:Seq и rdf:li
function StripXmlTags(const S: AnsiString): AnsiString;
var
  I: Integer;
  InTag: Boolean;
begin
  Result := '';
  InTag := False;
  for I := 1 to Length(S) do
    if S[I] = '<' then InTag := True
    else if S[I] = '>' then InTag := False
    else if not InTag then Result := Result + S[I];
  Result := AnsiString(Trim(string(Result)));
end;

procedure CheckNavigationLayer(const FileName: string);
var
  PDF: THotPDF;
  Title, Author, Subject, Keywords, Creator, Producer, XmpAuthor: AnsiString;
  Titles: THPDFAnsiStringArray;
  I, PageIndex: Integer;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.AutoLaunch := False;
    if PDF.LoadFromFile(FileName) <= 0 then
      raise Exception.Create('No readable pages');

    if PDF.GetLoadedDocumentInfo(Title, Author, Subject, Keywords,
      Creator, Producer) then
    begin
      XmpAuthor := StripXmlTags(PDF.GetLoadedXMPValue('dc', 'creator'));
      if (XmpAuthor <> '') and (XmpAuthor <> Author) then
        Writeln('Author mismatch: /Info="', Author, '" XMP="', XmpAuthor, '"');
    end;

    Titles := PDF.GetLoadedOutlineTitlesDeep;
    Writeln(Length(Titles), ' bookmarks reachable');
    for I := 0 to High(Titles) do
      if PDF.FindLoadedOutlineByTitle(Titles[I], PageIndex, False, True)
        and (PageIndex < 0) then
        Writeln('No direct page target: ', Titles[I]);
  finally
    PDF.Free;
  end;
end;

Число закладок ниже написанного вами указывает на разорванную цепочку братьев. -1 у закладки с именованной целью — ожидаемо, а FindLoadedOutlineByTitle останавливается на первом совпадении, поэтому дубликаты заголовков докладывают цель первого. GetLoadedXMPValue — простой текстовый поиск по пакету, и сравнение идёт байт в байт, так что с не-ASCII именами посмотрите, как возвращаются оба значения, прежде чем верить расхождению

Всё в этом слое — бухгалтерия ссылок, и бухгалтерия — та часть, которую стоит отдать библиотеке. HotPDF Delphi Component для Delphi и C++Builder пишет оба хранилища метаданных из одного набора свойств, прошивает ссылки оглавления по мере добавления элементов и подключает аннотации-ссылки с их действиями и описаниями; его API загруженных документов перечитывает те же структуры для проверки