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 замість того, щоб малює — нотатка /Contents, її автор (/T), або її тему (/Subj) — і повертає AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() знаходить збіги в тексті та анотації draws, наприклад, a FreeText’s видимих слів, і повертає 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() був викликаний на копії, а не на дескрипторі, який повернув Add*()Викличте Flatten() на об’єкті, що повернувся безпосередньо методом створення

FAQ

У чому різниця між SearchAnnotationText та SearchAnnotations?

SearchAnnotationText() відповідає тексту анотації carries — /Contents, /T (author), або /Subj — наприклад, тіло липкої нотатки. SearchAnnotations() відповідає текст анотації draws на сторінці, наприклад 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()Знайдіть текст, який анотація малює на сторінці

Дивіться також

 Українська