Вступ

У вступному пості анотації розглянуті стисло: виділення, підкреслення, нотатки-стикери та штампи, додані за допомогою Page.AddHighlight(), Page.AddUnderline() та подібних методів. Це лише невелика частина того, що фактично підтримує Page — галерея анотацій у цій бібліотеці охоплює розмітку, вільні форми, посилання з реальним навігаційним та відправкою форм, а також пошук, усе доступне безпосередньо з Page.

У цьому дописі розглядаються інші аспекти: методи анотації форм і вільного рисування, що саме може робити дія анотації Link, а також два різних способи пошуку вмісту анотації залежно від того, чи знаходиться шуканий текст у вигляді анотації чи у її /Contents коментарі.

Кожен метод анотації повертає типізований дескриптор, прив’язаний до щойно створеної анотації, і кожна анотація на сторінці доступна для читання пізніше через page.Annotations.

Що включено

Анотації розмітки

Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() та Page.AddStrikeOut() приймають однакову структуру параметрів — набір чотирьох точок, що позначають текстовий регіон, та необов’язковий колір — і всі чотири повертають MarkupAnnotation. Чотири точки зазвичай отримуються з пошуку тексту або з відомого прямокутника тексту.

const markup = (body: [number, number, number, number], sample: string,
  add: (quads: number[]) => void): void => {
  const yMid = (body[1] + body[3]) / 2 - 6;
  const textRect: [number, number, number, number] = [body[0] + 4, yMid, body[2] - 4, yMid + 16];
  page.AddText(sample, textRect[0], textRect[1], { fontSize: 12 });
  add(rectToQuads(textRect));
};

markup(cardBody, 'Highlight this phrase', (quads) =>
  page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' }));
markup(cardBody, 'Underline this phrase', (quads) =>
  page.AddUnderline({ quads, color: [0, 0, 1] }));
markup(cardBody, 'Squiggle this phrase', (quads) =>
  page.AddSquiggly({ quads, color: [1, 0.5, 0] }));
markup(cardBody, 'Strike this phrase out', (quads) =>
  page.AddStrikeOut({ quads, color: [1, 0, 0] }));

Примітки та автономний текст

Page.AddTextNote() додає класичну іконку нотатки, яка відкриває спливаюче вікно коментаря при кліку, повертаючи TextAnnotation. Page.AddFreeText() натомість малює свій текст безпосередньо на сторінці всередині рамки, зі своїм розміром шрифту, вирівнюванням та кольором заповнення — корисно для підкреслень, які мають бути видимими без відкриття чого-небудь.

page.AddTextNote({
  rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

page.AddFreeText({
  rect: [220, 60, 520, 96],
  contents: 'FreeText sample', fontSize: 10, align: 'center',
  fill: [1, 1, 0.8], width: 1,
});

Форми та вільний штрих

Page.AddSquare() і Page.AddCircle() малюють прямокутник або еліпс з рамкою, кожен з необов’язковим внутрішнім заповненням. Page.AddLine() малює пряму лінію між двома точками, з незалежно обираними стилями наконечників стрілки (startEnding/endEnding, наприклад 'OpenArrow'/'ClosedArrow') на кожному кінці. Page.AddPolygon() і Page.AddPolyline() малюють закриті та відкриті багатоточкові форми зі сплощеного списку координат, а Page.AddInk() записує один або кілька вільних штрихів пера як paths списків точок.

page.AddSquare({ rect: [50, 400, 130, 435], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [150, 400, 230, 435], color: [0, 0.5, 0], width: 2 });

page.AddLine({
  line: [260, 417, 420, 417],
  color: [0, 0, 0.7], width: 2,
  startEnding: 'OpenArrow', endEnding: 'ClosedArrow',
});

const stroke: number[] = [];
[-8, 6, -4, 10, -2, 8, -6].forEach((dy, i) => stroke.push(440 + i * 12, 417 + dy));
page.AddInk({ paths: [stroke], color: [0.6, 0, 0.6], width: 2 });

Посилання та їх дії

Page.AddLink() повертає LinkAnnotation, чиї action визначає, що відбудеться при кліку: { type: 'uri', uri: '...' } відкриває зовнішню URL-адресу, { type: 'goto', page: N } переходить до сторінки в межах того ж документа, а { type: 'submit', url: '...', format: 'html' } надсилає поточні значення полів форми до кінцевої точки. Номер сторінки goto, що виходить за межі, або неправильно сформований об’єкт дії відхиляються під час створення, а не приймаються без повідомлення.

const uriLink = page.AddLink({
  rect: [10, 10, 100, 30], action: { type: 'uri', uri: 'https://example.com' },
});

const gotoLink = page.AddLink({
  rect: [10, 40, 100, 60], action: { type: 'goto', page: 2 },
});

const submitLink = page.AddLink({
  rect: [10, 70, 100, 90],
  action: { type: 'submit', url: 'https://example.com/post', format: 'html' },
});

// page.AddLink({ rect: [...], action: { type: 'goto', page: 99 } }) throws RangeError
// when 99 is out of range for the document.

Пошук вмісту анотації

Два різні методи шукають текст анотації, і вони навмисно не перетинаються: Page.SearchAnnotations() шукає текст власного вигляду анотації малює — видимою міткою на FreeText або штампом, наприклад — в той час як Page.SearchAnnotationText() шукає текст, що міститься в анотації /Contents запис, наприклад у тілі коментаря липкої нотатки. Співпадіння в одному не означає співпадіння в іншому.

page.SearchAnnotations('bravo');          // finds it if the annotation's drawn appearance contains it
page.SearchAnnotationText('bravo');       // finds it if the annotation's /Contents comment contains it

Анотації, які більше не потрібні, можна видалити безпосередньо за допомогою Page.RemoveAnnotation(), передаючи або дескриптор анотації, або її базовий словник.

Швидкий старт

Встановіть пакет, а потім додайте підсвічування, посилання та липку нотатку до існуючої сторінки:

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build
import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

page.AddHighlight({ quads: [72, 700, 300, 700, 72, 715, 300, 715], color: [1, 1, 0] });

page.AddLink({
  rect: [72, 670, 200, 690], action: { type: 'uri', uri: 'https://example.com' },
});

page.AddTextNote({
  rect: [320, 670, 340, 690], icon: 'Note', author: 'Reviewer',
  contents: 'Please double-check this figure.',
});

doc.WriteTo('annotated.pdf');

Підтримувані формати

ФорматРозширенняЧитатиНаписати
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

Відкритий код та ліцензування

Aspose.PDF FOSS для TypeScript випускається під ліцензією MIT, з вихідним кодом, опублікованим на GitHub. Не передбачено водяного знака оцінки, обмеження використання чи окремого файлу ліцензії для керування, і бібліотеку можна використовувати у комерційних продуктах без роялті.

Пакет наразі має версію 0.1.0, що відображає активну розробку на ранньому етапі. Node.js (>=22) — єдина вимога до середовища виконання, і пакет не має інших сторонніх залежностей.

Початок роботи

Пов’язані ресурси