Понимание XML-метаданных и закладок PDF: техническое руководство.
Основные темы, рассматриваемые в руководстве.
📍 Места назначения.
Точные маркеры местоположения, определяющие конкретные позиции внутри документов PDF. Они обеспечивают точную навигацию для закладок и гиперссылок, в то время как структура документа обеспечивает функциональность иерархического оглавления.
📄 XML Metadata
Структурированные потоки XML, предоставляющие исчерпывающую информацию о документах с использованием стандартизированных форматов XMP, расширяющие базовые свойства документов и включающие богатую описательную информацию.
📎 Вложенные файлы
Полная возможность встраивания файлов, которая упаковывает внешние ресурсы непосредственно в документы PDF, создавая автономные наборы документов, аналогичные вложениям электронной почты.
📝 Аннотации
Интерактивные элементы наложения, которые добавляют текст, графику и интерактивные функции на страницы PDF, не изменяя при этом основной контент. Включают гиперссылки для бесшовной навигации по документу и различные инструменты для расширенного взаимодействия с читателем.
Закладки и точки перехода
Навигация по документу основана на иерархических структурах закладок, технически известных как структура документаЭта древовидная система представляет собой набор кликабельных элементов, обычно глав, заголовков разделов и названий подразделов, которые позволяют читателям быстро переходить к определенным частям документа. Каждый элемент закладки сочетает в себе отображаемый текст и информацию о назначении, которая точно указывает, куда должна вести ссылка.
Понимание назначений
Назначения в PDF-файлах служат точными маркерами местоположения внутри документа, указывая, какую страницу отображать, где на этой странице расположить вид и какой уровень масштабирования применить. Вы можете создавать назначения двумя способами: определять их непосредственно в тексте (что мы будем использовать в наших примерах для ясности) или ссылаться на них по имени с помощью системы именования, охватывающей весь документ. Большинство программ для чтения PDF-файлов отображают закладки в панели навигации рядом с основным содержимым документа.
Каждое назначение использует структуру массива, где конкретные элементы варьируются в зависимости от желаемого поведения просмотра. Вот основные типы назначений, доступные:
Таблица типов назначений
Обратите внимание: "page" представляет собой косвенную ссылку на объект страницы. По умолчанию эти назначения работают в пределах области обрезки страницы, переходя к области медиа, если область обрезки не определена.
| Array | Description |
|---|---|
| [page /Fit] | Scales the page to fit completely within the viewer window, adjusting both width and height proportionally. |
| [page /FitH top] | Positions the specified top coordinate at the window’s top edge while scaling horizontally to fit the full page width. |
| [page /FitV left] | Aligns the specified left coordinate with the window’s left edge while scaling vertically to fit the full page height. |
| [page /XYZ left top zoom] | Positions the coordinates (left, top) at the window’s upper-left corner and applies the specified zoom factor. Null values preserve current settings for those parameters. |
| [page /FitR left bottom right top] | Zooms and positions the view to display the rectangular area defined by the left, bottom, right, and top coordinates. |
| [page /FitB] | Similar to /Fit, but scales based on the actual content boundaries instead of the defined crop box area. |
| [page /FitBH top] | Functions like /FitH but uses the content bounding box instead of the crop box for horizontal scaling calculations. |
| [page /FitBV left] | Operates like /FitV but calculates vertical scaling based on the content bounding box rather than the crop box boundaries. |
Структура структуры документа
Структура навигации, созданная на основе документа, представляет собой иерархическую систему, которая функционирует как интерактивное оглавление для просмотрщиков PDF. Эта древовидная организация помогает пользователям быстро перемещаться по сложным документам, предоставляя четкий структурный обзор. Система основана на двух основных типах объектов:
- Словарь оглавления – Корень иерархии оглавления
- Словари элементов оглавления – Отдельные записи в оглавлении
Структура словаря оглавления (Таблица)
| Key | Value Type | Value |
|---|---|---|
| /Type | name | If present, must be /Outlines. |
| /First | indirect reference to dictionary | References the initial top-level outline entry in the document hierarchy. This field is mandatory when outline entries exist. |
| /Last | indirect reference to dictionary | References the final top-level outline entry in the document hierarchy. This field is mandatory when outline entries exist. |
| /Count | integer | Specifies how many outline entries are currently expanded across the entire outline tree. Can be omitted when no entries are in an open state. |
Реализация элемента оглавления
Каждый элемент оглавления состоит из словаря, который определяет его отображаемый заголовок, целевое место назначения и связи с другими элементами в иерархии.
Давайте рассмотрим, как структурирован простой конспект документа в синтаксисе PDF:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
8 0 obj <</Type/Outlines/Count 4/First 9 0 R/Last 9 0 R>> endobj 9 0 obj <</Title(Chapter 1: Experiment A)/Count 3/Parent 8 0 R/First 12 0 R/Last 18 0 R>> endobj 12 0 obj <</Title(1: Introduction)/Count 0/Parent 9 0 R/Next 15 0 R>> endobj 15 0 obj <</Title(2: Methodology)/Count 0/Parent 9 0 R/Prev 12 0 R/Next 18 0 R>> endobj 18 0 obj <</Title(3: Result verification)/Count 0/Parent 9 0 R/Prev 15 0 R/>> endobj |
Структура таблицы словаря элементов конспекта
* обозначает обязательный элемент
| Key | Value Type | Value |
|---|---|---|
| /Title* | text string | Text to be displayed for this entry. |
| /Parent* | indirect reference to dictionary | References this item’s parent within the outline hierarchy, which can be either another outline item or the root outline dictionary. |
| /Prev | indirect reference to dictionary | References the preceding sibling item at the same hierarchical level, when applicable. |
| /Next | indirect reference to dictionary | References the following sibling item at the same hierarchical level, when applicable. |
| /First | indirect reference to dictionary | References the initial child item under this entry, when child items exist. |
| /Last | indirect reference to dictionary | References the final child item under this entry, when child items exist. |
| /Count | integer | When the entry is expanded, indicates the count of visible descendant entries. When collapsed, stores a negative value representing the total number of hidden descendants that would become visible upon expansion. |
| /Dest | name, string or array | The destination. Arrays are destinations, names are references to entries in the /Dests entry in the document catalog, strings are references to entries in the /Dests entry in the document’s name dictionary. |
XML-метаданные
Современные PDF-документы могут включать сложные потоки метаданных на основе XML, которые предоставляют гораздо более подробную и структурированную информацию, чем традиционные свойства документа. Эта расширенная система метаданных использует спецификацию XMP (Extensible Metadata Platform) от Adobe для обеспечения стандартизированных, машиночитаемых описаний документов, которые улучшают возможности поиска, организации и автоматической обработки.
Структура XMP-метаданных
XMP-метаданные упаковываются в виде XML-документа, который использует синтаксис RDF (Resource Description Framework) для организации и описания свойств документа в стандартизированном формате. Этот контент метаданных встраивается в специальный объект потока, который включает в себя правильную идентификацию типа для процессоров PDF:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
6 0 obj <</Length 1235/Type/Metadata/Subtype/XML>>stream <?xpacket begin="锘xBF" id="W5M0MpCehiHzreSzNTczkc9d"?> <x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26" ><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" ><rdf:Description rdf:about="" xmlns:pdf="http://ns.adobe.com/pdf/1.3/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xmp="http://ns.adobe.com/xap/1.0/" ><pdf:Producer>losLab PDF Library</pdf:Producer> <dc:creator>losLab.com</dc:creator> <dc:title>Delphi PDF SDKs</dc:title> <xmp:CreateDate>2025-06-29T10:46:27+08:00</xmp:CreateDate> <xmp:ModifyDate>2025-06-29T10:58:57+08:00</xmp:ModifyDate> <xmp:MetadataDate>2025-06-29T10:46:27+08:00</xmp:MetadataDate> <dc:description>Delphi Development Library for PDF creation & editing</dc:description> <xmp:CreatorTool>HotPDF Component</xmp:CreatorTool> <dc:subject>PDF Developer Library for RAD Studio></dc:subject> <pdf:Keywords>Delphi, PDF SDK, PDF Component</pdf:Keywords> </rdf:Description>Robust Delphi PDF development library</rdf:RDF> </x:xmpmeta> <?xpacket end="w"?> endstream endobj |
Стандартные схемы метаданных
Фреймворк XMP организует метаданные с помощью стандартных пространств имен схем, каждое из которых предназначено для конкретных категорий информации.
📋 Dublin Core (dc:)
Базовая библиографическая информация
- dc:title – Название документа
- dc:creator – Автор(ы) документа
- dc:subject – Тема/ключевые слова документа
- dc:description – Описание документа
- dc:format – MIME тип
🏷️ XMP Basic (xmp:)
Основные свойства XMP
- xmp:CreateDate – Дата создания
- xmp:ModifyDate – Дата изменения
- xmp:CreatorTool – Приложение, создавшее файл
- xmp:MetadataDate – Дата изменения метаданных
📄 Схема PDF (pdf:)
Свойства, специфичные для PDF
- pdf:Producer – Производитель PDF.
- pdf:Keywords – Ключевые слова документа.
- pdf:PDFVersion – Версия PDF.
Интеграция с каталогом документов.
Поток XML-метаданных ссылается из каталога документов:
|
1 2 3 |
1 0 obj < < Type Catalog Pages 2 0 R Metadata 10 0 R Outlines 1 0 R>> endobj |
🎯 Рекомендации по работе с XML-метаданными.
- Всегда включайте как словарь информации о документе, так и метаданные XMP для максимальной совместимости.
- Убедитесь, что значения метаданных согласованы в обоих местах.
- Используйте правильную XML-кодировку (UTF-8) для символов, используемых в разных языках.
- Включайте даты создания и изменения в формате ISO 8601.
- Проверяйте структуру XML, чтобы предотвратить ошибки разбора.
Прикрепленные файлы.
Прикрепленные PDF-файлы предоставляют удобный способ встраивания внешних файлов непосредственно в документ PDF, создавая автономные пакеты, включающие все необходимые ресурсы. Эти вложения могут быть связаны со всем документом или с определенными страницами, в зависимости от ваших потребностей. Большинство современных просмотрщиков PDF отображают эти встроенные файлы в специальной панели вложений, что позволяет пользователям легко получать доступ к содержимому, просматривать его или сохранять. Эта функция особенно полезна для создания комплексных пакетов документов, таких как презентации, включающие дополнительные ресурсы, или отчеты с прилагаемыми файлами данных.
Структура встроенных файлов.
В своей основе, встроенный файл состоит из объекта потока, содержащего фактические данные файла, а также записи словаря потока, указывающей /Type /EmbeddedFile. Этот простой подход позволяет хранить файлы любого типа в PDF. Вот как выглядит базовая структура встроенного файла:
|
1 2 3 4 5 6 |
8 0 obj < < Type EmbeddedFile Length 35>> stream This is a text file attachment... endstream endobj |
PDF поддерживает два различных подхода к ссылке на встроенные файлы, каждый из которых предназначен для разных целей: глобальные вложения, доступные во всем документе, и вложения на уровне страницы, которые отображаются в виде интерактивных элементов на определенных страницах.
Вложения на уровне документа
Для вложений, доступных во всем документе, необходимо добавить /EmbeddedFiles запись в словарь имен, который доступен через /Names запись в каталоге документа. Этот подход делает вложение доступным во всем PDF-документе, независимо от того, на какой странице находится пользователь:
|
1 2 3 4 5 6 |
9 0 obj < < Names << EmbeddedFiles << Names [ (attachment.txt) << EF << F 8 0 R>> /F (attachment.txt) /Type /Filespec >> ] >> >> /Pages 1 0 R /Type /Catalog >> endobj |
Объяснение структуры кода
- /Names – Содержит словарь имен для документа.
- /EmbeddedFiles – Специально обрабатывает имена встроенных файлов.
- (attachment.txt) – Имя файла, которое отображается пользователям.
- /EF – Словарь встроенных файлов, содержащий фактическую ссылку на файл.
- /F 8 0 R – Ссылка на объект потока встроенного файла.
- /Type /Filespec – Определяет это как словарь спецификации файла.
Вложения на уровне страницы.
Вложения, специфичные для страницы, требуют другого подхода с использованием аннотаций для вложений файлов. Они добавляются в /Annots массив в словаре целевой страницы, создавая видимый значок вложения, с которым пользователи могут взаимодействовать непосредственно на странице:
|
1 2 3 4 5 6 7 8 |
9 0 obj < < Type Page (Other dictionary entries as usual) Annots [ << FS << EF << F 8 0 R>> /F (attachment.txt) /Type /Filespec >> /Subtype /FileAttachment /Contents (attachment.txt) /Rect [ 18 796.88976378 45 823.88976378 ] >> ] >> endobj |
Свойства вложений для страницы.
- /FS – Словарь спецификации файла (аналогично /EF выше).
- /Subtype /FileAttachment – Определяет эту аннотацию как вложенный файл.
- /Contents – Текст всплывающей подсказки, который отображается при наведении курсора на значок вложения.
- /Rect – Прямоугольник, определяющий положение и размер значка вложения на странице.
Примеры использования вложений.
📊 Файлы данных.
Встраивайте электронные таблицы, базы данных или файлы с необработанными данными вместе с отчетами и аналитическими материалами.
🎨 Исходные файлы.
Включите оригинальные файлы дизайна, чертежи CAD или редактируемые шаблоны.
📹 Медиа-ресурсы.
Прикрепите видеопрезентации, аудиозаписи или интерактивный контент.
📋 Дополнительные документы.
Объедините связанные PDF-файлы, контракты или справочные материалы.
Аннотации.
PDF-аннотации предоставляют мощный способ добавления интерактивных элементов и визуальных пометок в документы, не изменяя при этом исходное содержимое страницы. Эти наложенные элементы улучшают процесс чтения, позволяя пользователям выделять текст, добавлять комментарии или создавать кликабельные ссылки. Среди наиболее полезных типов аннотаций - гиперссылки, которые обеспечивают плавную навигацию между различными разделами документа или внешними ресурсами.
Структура аннотаций
Хотя различные типы аннотаций служат разным целям, все они имеют последовательную базовую структуру, к которой добавляются специфические свойства в зависимости от типа. Страницы PDF могут содержать несколько аннотаций, которые организованы в массиве, на который ссылается запись /Annots в словаре каждой страницы. Каждая аннотация реализована как отдельный объект словаря с определенными свойствами.
Структура словаря аннотаций (таблица)
* обозначает обязательный элемент
| Key | Value Type | Value |
|---|---|---|
| /Type | name | When specified, this value must be set to /Annot to properly identify the dictionary type. |
| /Subtype* | name | Specifies the specific annotation category (e.g., Link, Text, Highlight). |
| /Rect* | rectangle | Defines the annotation’s position and dimensions using standard PDF coordinate units. |
| /Contents | text string | Contains the annotation’s text content or provides an alternative descriptive label for accessibility purposes. |
Пример базового словаря аннотаций:
|
1 2 3 |
12 0 obj < < Type Annot Subtype Link Rect [100 200 300 250] Border [0 0 1] C [0.0 0.0 1.0] Dest [5 0 R XYZ null null null]>> endobj |
Общие типы аннотаций
🔗 Аннотации-ссылки
Создайте области, по которым можно кликнуть, чтобы перейти к разделам внутри документа или к внешним ресурсам.
- /Subtype /Link – Определяет, что это аннотация ссылки.
- /Dest – Массив пунктов назначения или именованный пункт назначения.
- /A – Словарь действий для более сложных операций.
📝 Текстовые аннотации.
Отображает всплывающие заметки и комментарии, которые появляются при нажатии.
- /Subtype /Text – Определяет, что это текстовая аннотация.
- /Contents – Текстовое содержимое аннотации.
- /Open – Указывает, открыта ли аннотация изначально.
🖍️ Markup Annotations
Выделение, подчеркивание или зачеркивание текстового содержимого.
- /Subtype /Highlight – Выделение текста
- /Subtype /Underline – Подчеркивание текста
- /Subtype /StrikeOut – Зачеркивание текста
Расширенные действия для ссылок.
Аннотации ссылок могут выполнять различные действия, выходящие за рамки простой навигации.
|
1 2 3 |
13 0 obj < < Type Annot Subtype Link Rect [50 50 200 100] A << Type Action S URI URI (https: www.example.com)>> >> endobj |
Типы действий
- /S /GoTo – Перейти к указанному месту в документе.
- /S /GoToR – Перейти к указанному месту в другом документе.
- /S /URI – Открыть веб-URL.
- /S /Launch – Запуск внешнего приложения
- /S /JavaScript – Выполнение JavaScript кода
Внешний вид аннотаций
Настройка визуального стиля аннотаций осуществляется с помощью потоков стилей, что обеспечивает точный контроль над тем, как аннотации отображаются пользователям:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
14 0 obj < < Type Annot Subtype Square Rect [100 100 200 150] C [1.0 0.0 0.0] BS << W 2 S S>> /AP < < N 15 0 R>> >> endobj 15 0 obj < < Type XObject Subtype Form BBox [0 0 100 50] Length 85>> stream q 1.0 0.0 0.0 RG 2 w 10 10 80 30 re S Q endstream endobj |
Практические рекомендации по реализации
Интеграция структуры документа
Успешная реализация требует понимания того, как эти элементы взаимодействуют друг с другом в более широкой архитектуре PDF-документа.
|
1 2 3 4 |
1 0 obj < < Type Catalog Pages 2 0 R Outlines 3 0 R Names << EmbeddedFiles 4 0 R>> /Metadata 5 0 R >> endobj |
✅ Список необходимых действий для реализации.
- Настройка каталога документов. – Обеспечьте правильные ссылки на оглавления, имена и метаданные.
- Нумерация объектов. – Поддерживайте согласованную нумерацию объектов и перекрестные ссылки.
- Кодирование потоков. – Применяйте соответствующие фильтры и кодирование для потоков.
- Валидация – Проверка структуры PDF с помощью инструментов валидации.
- Тестирование совместимости – Тестирование на различных программах просмотра PDF и версиях.
Распространенные проблемы и решения.
❌ Закладки не отображаются.
Решение: Убедитесь, что каталог документов содержит /Outlines запись и что иерархия оглавления правильно структурирована с корректными отношениями родитель-потомок.
❌ Метаданные не распознаны.
Решение: Убедитесь, что поток XML-метаданных имеет правильный формат, использует корректные пространства имен и ссылается на каталог документов. /Type /Metadata и /Subtype /XML.
❌ Невозможно получить доступ к вложениям.
Решение: Проверьте, что встроенные файлы правильно ссылаются либо в словаре имен на уровне документа, либо в словаре аннотаций на уровне страницы, и что словари спецификаций файлов имеют правильную структуру.
Заключение.
Освоение метаданных PDF и реализации закладок имеет решающее значение для разработки профессиональных документов, которые обеспечивают превосходный пользовательский опыт и функциональность. Эти мощные функции обеспечивают:
- Улучшенная навигация. – Благодаря хорошо структурированным закладкам и ссылкам.
- Расширенные метаданные. – Обеспечивают лучшую организацию документов и возможности поиска.
- Интеграция файлов. – Объединение связанных ресурсов внутри документов.
- Интерактивные элементы. – Создание привлекательных пользовательских интерфейсов с помощью аннотаций.
Реализуя эти функции правильно, вы можете создавать PDF-документы, которые выходят за рамки простого текста и графики, становясь комплексными, интерактивными ресурсами, эффективно служащими как для людей, так и для автоматизированных систем.
🚀 Следующие шаги.
- Практикуйте внедрение этих структур в ваш процесс создания PDF-документов.
- Экспериментируйте с различными типами аннотаций и иерархиями закладок.
- Протестируйте свои реализации в различных программах просмотра PDF.
- Изучите расширенные функции PDF, опираясь на эти основы.