TypeScript'te Açıklamalarla Nasıl Çalışılır

Bu kılavuz, TypeScript için Aspose.PDF FOSS ile PDF açıklamaları ekleme, düzleştirme ve arama yollarını gösterir. Page sınıfı, açıklama alt türü başına bir Add* yöntemi sunar — işaretleme (vurgulama, altı çizili, üstü çizili, dalgalı), şekiller (kare, daire, çizgi, çokgen, mürekkep), metin (yapışkan not, serbest metin) ve bağlantılar — her biri daha sonra okunabilecek veya düzleştirilebilecek bir tiplenmiş Annotation tutamağı döndürür. Node.js 22 veya daha yeni bir sürüm gerektirir.

Adım Adım Kılavuz

Adım 1: Paketi Yükleyin

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

Kurulumu, yeni bir TypeScript dosyasında Document sınıfını içe aktararak doğrulayın — paket yüklendikten sonra bu satır hatasız çözülmelidir:

import { Document } from '@asposefoss/pdf';

Adım 2: Gerekli Sınıfları İçe Aktarın

Dosyayı açmak için Document‘ı içe aktarın ve aşağıdaki adımlarda kullanılan açıklama türü imzaları için Page‘ı kullanın:

import { Document, Page } from '@asposefoss/pdf';

Adım 3: İşaretleme Açıklamaları Ekle

Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() ve Page.AddStrikeOut() hepsi bir quads dizisi alır — vurgulanan metin bölgesi başına bir 8 sayılı dörtgen (x1,y1,x2,y2,x3,y3,x4,y4) — ayrıca bir color ve isteğe bağlı contents. Kütüphane, dört alt tip için görünüm akışını (/AP) otomatik olarak oluşturur:

import { Document } from '@asposefoss/pdf';

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

page.AddHighlight({
  quads: [72, 700, 300, 700, 72, 685, 300, 685],
  color: [1, 1, 0],
  contents: 'Yellow highlight',
});
page.AddUnderline({
  quads: [72, 660, 300, 660, 72, 645, 300, 645],
  color: [0, 0, 1],
});
page.AddStrikeOut({
  quads: [72, 620, 300, 620, 72, 605, 300, 605],
  color: [1, 0, 0],
});

doc.WriteTo('annotated.pdf');

Adım 4: Şekil ve Mürekkep Açıklamaları Ekle

Page.AddSquare() ve Page.AddCircle() bir sınırlayıcı rect ile color (çizgi) ve isteğe bağlı fill alır. Page.AddLine() bir 4 sayılı line (x1,y1,x2,y2) ve isteğe bağlı ok uçları alır. Page.AddInk() paths alır — düz nokta çifti dizilerinden oluşan bir dizi, kalem darbesi başına bir tane:

page.AddSquare({ rect: [100, 500, 220, 560], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [250, 500, 370, 560], color: [0, 0.5, 0], width: 2 });
page.AddLine({
  line: [100, 470, 370, 470],
  color: [0, 0, 0.7],
  width: 2,
  startEnding: 'OpenArrow',
  endEnding: 'ClosedArrow',
});
page.AddInk({
  paths: [[100, 400, 130, 430, 160, 390, 190, 420]],
  color: [0.6, 0, 0.6],
  width: 2,
});

Adım 5: Yapışkan Not ve Serbest Metin Ekle

Page.AddTextNote() bir yorum açılır penceresi açan tıklanabilir bir simge yerleştirir. Page.AddFreeText() metni doğrudan sayfada, kendi rect‘si içinde çizer:

page.AddTextNote({
  rect: [400, 700, 420, 720],
  icon: 'Note',
  author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

page.AddFreeText({
  rect: [400, 600, 550, 660],
  contents: 'FreeText sample',
  fontSize: 10,
  align: 'center',
  fill: [1, 1, 0.8],
  width: 1,
});

Adım 6: Bir Açıklamayı Statik İçeriğe Düzleştir

Bir Add* çağrısı tarafından döndürülen her açıklama tutamacı, açıklamanın görünümünü sayfanın içerik akışına yerleştiren ve /Annots‘den kaldıran bir Flatten() yöntemine sahiptir. Düzleştirildikten sonra bir görüntüleyicide tıklanacak veya düzenlenecek hiçbir şey kalmaz:

const note = page.AddFreeText({
  rect: [210, 535, 470, 590],
  contents: 'Sticky note — flattened into the page.',
  fontSize: 11,
  align: 'left',
});

note.Flatten(); // -> boolean; bakes the annotation, unwires itself from /Annots

Adım 7: Açıklama Metnini Ara

Page.SearchAnnotationText() and Page.SearchAnnotations() her iki yönde de ayrıkdır: SearchAnnotationText() gerçek açıklama meta verileriyle eşleşir (/Contents, /T, /Subj), iken SearchAnnotations() şununla eşleşir rendered şöyle gibi işaretleme açıklamalarının metni FreeText:

const metadataHits = page.SearchAnnotationText('confidential');
for (const hit of metadataHits) {
  console.log(hit.key, hit.value); // e.g. 'Contents', 'confidential'
}

const renderedHits = page.SearchAnnotations('confidential');
console.log(renderedHits.length);

Yaygın Sorunlar ve Çözümler

Page.AddHighlight() (veya başka bir işaretleme yöntemi) yanlış yerde çiziyor. quads 8 sayılı düz dizi (x1,y1,x2,y2,x3,y3,x4,y4), bir değil rect — 4 sayılık bir dikdörtgen geçmek, bozulmuş ya da eksik bir dörtgen üretir. Vurgulanan her satır için bir dörtgen oluşturun.

Düzleştirilmiş bir açıklama hâlâ tıklanabilir. Flatten() şu nesne tarafından döndürülen nesne üzerinde çağrılmalıdır Add* çağrı, ve belge kaydedilmelidir (doc.WriteTo() / doc.Save()) düzleştirmeden sonra — değişiklik yalnızca dosya tekrar yazılana kadar bellekte vardır.

SearchAnnotationText() metin sayfada görünür olmasına rağmen hiç sonuç döndürmez. Yalnızca açıklama meta veri alanlarını arar (/Contents, /T, /Subj) — bir açıklamanın kendi görünümünden oluşturulan görünür işaretleme metni (ör. bir FreeText body) tarafından bulunur SearchAnnotations() yerine, ve ne de normal sayfa içeriğini arar (kullan Page.GetText() or Page.Search() bunun için).

Redaction işaretleri, ek açıklamaları ararken görünmez. Page.AddRedact() bir oluşturur RedactAnnotation, burada kapsanan markup/shape/text ek açıklamalardan farklı bir alt tür — bakınız Redaction kılavuz.

Sık Sorulan Sorular

`Page` kaç ek açıklama alt türünü destekliyor?

Kütüphane, işaretleme (vurgulama, altı çizili, üstü çizili, dalgalı), şekiller (kare, daire, çizgi, çokgen, mürekkep), metin (yapışkan not, serbest metin), bağlantılar ve damgalar için görünümler üretir — ayrıca dosya eki ve redaction ek açıklamaları da bulunur; bunlar kendi nasıl-yapılır kılavuzlarında ele alınmıştır.

Sayfada zaten var olan ek açıklamaları okuyabilir miyim?

Evet — Page.Annotations mevcut ek açıklamaları, inceleyebileceğiniz, düzenleyebileceğiniz veya düzleştirebileceğiniz tiplenmiş tutamaçların bir dizisi olarak döndürür ve Page.RemoveAnnotation(a) bir tanesini kaldırır.

Bir ek açıklamayı düzleştirmek ile bir redaction uygulamak arasındaki fark nedir?

Flatten() bir ek açıklamanın appearance sayfaya ekler ve ek açıklama nesnesini kaldırır, ancak onun altındaki herhangi bir metin ya da görüntü içeriği dokunulmaz kalır. ApplyRedactions() içerik akışını yok edici bir şekilde yeniden yazar, böylece kapsanan içerik tamamen kaybolur — ayrıntılar için Redaction guide’a bakın.

Kaydet/açma döngüsü sırasında ek açıklamalar korunur mu?

Evet — doc.WriteTo() / doc.Save() öncesinde eklenen ek açıklamalar PDF’ye yazılır ve bir sonraki Document.Open() / Document.OpenFile()‘te doğru şekilde geri okunur.