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()Найдите текст, который аннотация рисует на странице

См. также:

 Русский