Annotations
Аннотации
Эта страница охватывает создание, чтение, поиск и уплощение PDF-аннотаций. Page предоставляет по одному Add*() методу для каждого подтипа аннотации, каждый из которых возвращает живой Annotation дескриптор; базовый класс Annotation и его подтипы (TextAnnotation, StampAnnotation, MarkupAnnotation и другие) раскрывают свойства аннотации для чтения и редактирования.
Создание разметки, заметок и ссылок в аннотациях
Четыре метода разметки текста — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() и Page.AddStrikeOut() — принимают массив quads (/QuadPoints) и возвращают MarkupAnnotation. Page.AddLink() создаёт кликабельную область с URI или внутренним действием, а Page.AddTextNote() добавляет значок стикер-заметки, который открывает всплывающее окно с текстом contents, возвращая TextAnnotation.
page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' });
page.AddUnderline({ quads, color: [0, 0, 1] });
page.AddStrikeOut({ quads, color: [1, 0, 0] });
page.AddLink({
rect: [100, 700, 220, 716],
action: { type: 'uri', uri: 'https://example.com' },
border: 0,
});
page.AddTextNote({
rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
contents: 'This is a sticky-note annotation.',
});Page также предоставляет методы фигур и свободного рисования — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() и AddStamp() — каждый из которых возвращает соответствующий дескриптор аннотации для данного подтипа, автоматически генерируя её /AP внешний вид.
Чтение и перечисление аннотаций
page.Annotations — это массив всех Annotation на странице. Каждая аннотация, независимо от подтипа, раскрывает Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden и Opacity; подтипы добавляют свои собственные поля, такие как StampAnnotation.StampName или MarkupAnnotation.QuadPoints.
const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
freeText.Contents = 'Updated note text';
}Поиск текста аннотации
Page.SearchAnnotationText() and Page.SearchAnnotations() намеренно разобщены. SearchAnnotationText() находит совпадения в тексте аннотации carries вместо того чтобы рисует — заметка’s /Contents, её автор (/T), или её тема (/Subj) — и возвращает AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() находит совпадения в тексте аннотации draws, например, a FreeTextвидимые слова и возвращает AnnotationMatch[] ({ annot, text, quads }).
// A sticky note's /Contents text — found by SearchAnnotationText, not SearchAnnotations.
const textHits = page.SearchAnnotationText('body secret');
console.log(textHits[0].key, textHits[0].value); // 'Contents' 'body secret'
// A FreeText's rendered words — found by SearchAnnotations, not SearchAnnotationText.
const drawnHits = page.SearchAnnotations('bravo');Уплощение аннотаций
Annotation.Flatten() встраивает внешний вид /AP аннотации непосредственно в поток содержимого страницы в её /Rect, затем удаляет её из /Annots. Результат — постоянный, статический контент — больше не отдельная аннотация, которую пользователь может кликнуть, отредактировать или скрыть.
const note = page.AddTextNote({
rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();Советы и лучшие практики
- Вызовите
Flatten()на объекте, возвращённом непосредственно вызовомAdd*()— аннотация, полученная повторным чтениемpage.Annotationsпозже, это другая ссылка на объект. SearchAnnotationText()иSearchAnnotations()охватывают разный текст: используйте оба, если нужно найти фразу независимо от того, была ли она набрана в заметке или нарисована на странице.- Четыре метода разметки (
AddHighlight,AddUnderline,AddSquiggly,AddStrikeOut) автоматически генерируют их/APвнешний вид — ручное рисование в потоке содержимого не требуется. - Шифрование сохраняется при круговом проходе: аннотации, добавленные до
Document.Save()с опциейencrypt, остаются действительными после повторного открытия и расшифровки документа.
Распространённые проблемы
| Проблема | Причина | Исправление |
|---|---|---|
page.Annotations.find() возвращает undefined для только что добавленной аннотации | Поиск в устаревшем массиве, зафиксированном до добавления аннотации | Перечитайте page.Annotations после вызова Add*(), или используйте непосредственно дескриптор, который вернул вызов |
SearchAnnotationText() ничего не находит для текста, видимого на странице | Текст рисуется аннотацией (например, тело FreeText), а не передаётся в /Contents | Используйте SearchAnnotations() вместо этого — он соответствует нарисованному тексту |
Аннотация всё ещё выглядит редактируемой после Flatten() | Flatten() был вызван на копии, а не на handle Add*(), который был возвращён | Вызовите Flatten() у объекта, возвращённого напрямую методом создания |
FAQ
В чём разница между SearchAnnotationText и SearchAnnotations?
SearchAnnotationText() соответствует тексту аннотации carries — /Contents, /T (author), или /Subj — например, тело стикер-заметки. SearchAnnotations() соответствует тексту аннотация draws на странице, например, a FreeText’s видимые слова. Они дискретны: совпадение в одном не появится в другом.
Как сделать аннотацию постоянной и неинтерактивной?
Вызовите Flatten() на дескрипторе Annotation, возвращённом методом Add*(), который её создал. Это внедряет её внешний вид в поток содержимого страницы и удаляет её из /Annots.
Какие подтипы аннотаций поддерживаются?
Page предоставляет методы создания для разметки текста (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), заметок и выносов (AddTextNote, AddFreeText, AddCaret), ссылок (AddLink), фигур (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), свободного рисования (AddInk), штампов (AddStamp) и вложений файлов (AddFileAttachment).
Как вывести список всех аннотаций, уже находящихся на странице?
Прочитайте page.Annotations, массив дескрипторов Annotation. Каждый предоставляет Subtype, Rect, Color, Contents и другие общие свойства, поэтому вы можете фильтровать или исследовать их с помощью стандартных методов массива.
API Reference Сводка
| Класс/Метод | Описание: |
|---|---|
Annotation | Базовый обработчик для любой аннотации; предоставляет Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity |
Annotation.Flatten() | Запечь внешний вид аннотации в статическое содержимое страницы |
TextAnnotation | Ручка /Text липкой записки; добавляет Icon, Open, Author |
StampAnnotation | Ручка /Stamp резиновой печати; добавляет StampName |
MarkupAnnotation | Ручка разметки текста (Highlight/Underline/StrikeOut/Squiggly); добавляет MarkupType, QuadPoints |
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly() | Создать аннотацию разметки текста над /QuadPoints |
Page.AddTextNote() | Создать аннотацию в виде стикера |
Page.AddLink() | Создать кликабельную ссылку с URI или внутренним действием |
Page.Annotations | Каждый Annotation на странице в виде массива |
Page.SearchAnnotationText() | Найти текст, содержащийся в аннотации (/Contents, /T, /Subj) |
Page.SearchAnnotations() | Найдите текст, который аннотация рисует на странице |