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() | Знайдіть текст, який анотація малює на сторінці |