Annotations
Açıklamalar
Bu sayfa PDF açıklamaları oluşturmayı, okumayı, aramayı ve düzleştirmeyi kapsar. Page, açıklama alt türü başına bir Add*() yöntemi sunar ve her biri canlı bir Annotation tutamacı döndürür; Annotation temel sınıfı ve onun alt türleri (TextAnnotation, StampAnnotation, MarkupAnnotation ve diğerleri) açıklamanın özelliklerini okuma ve düzenleme için ortaya çıkarır.
İşaretleme, Not ve Bağlantı Açıklamaları Oluşturma
Dört metin-işaretleme yöntemi — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() ve Page.AddStrikeOut() — bir quads dizisi (/QuadPoints) alır ve bir MarkupAnnotation döndürür. Page.AddLink(), bir URI veya iç eylem ile tıklanabilir bir bölge oluşturur ve Page.AddTextNote(), contents metniyle bir açılır pencere açan yapışkan not simgesi ekler, bir TextAnnotation döndürür.
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 ayrıca şekil ve serbest el yöntemlerini de sunar — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret() ve AddStamp() — her biri o alt tür için ilgili açıklama tutamacını döndürür, /AP görünümünü otomatik olarak oluşturur.
Açıklamaları Okuma ve Listeleme
page.Annotations, sayfadaki her Annotation öğesinin bir dizisidir. Alt türüne bakılmaksızın her açıklama Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden ve Opacity öğelerini sunar; alt türler kendi alanlarını ekler, örneğin StampAnnotation.StampName veya MarkupAnnotation.QuadPoints.
const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
freeText.Contents = 'Updated note text';
}Ek Açıklama Metnini Arama
Page.SearchAnnotationText() and Page.SearchAnnotations() bilerek ayrıdır. SearchAnnotationText() metinde bir açıklamada eşleşmeleri bulur carries çizmek yerine — bir notun /Contents, yazarını (/T), ya da konusunu (/Subj) — ve döndürür AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() metinde bir açıklamada eşleşmeleri bulur draws, örneğin bir FreeText‘nin görünen kelimeleri ve döndürür 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');Ek Açıklamaları Düzleştirme
Annotation.Flatten(), bir ek açıklamanın /AP görünümünü doğrudan sayfanın içerik akışına /Rect konumunda yerleştirir, ardından /Annots üzerinden kaldırır. Sonuç, kalıcı, statik içeriktir — artık bir izleyicinin tıklayabileceği, düzenleyebileceği veya gizleyebileceği ayrı bir ek açıklama değildir.
const note = page.AddTextNote({
rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();İpuçları ve En İyi Uygulamalar
Flatten()‘ı,Add*()çağrısı tarafından doğrudan döndürülen nesne üzerinde çağırın — daha sonrapage.Annotations‘yi yeniden okuyarak elde edilen bir ek açıklama farklı bir nesne referansıdır.SearchAnnotationText()veSearchAnnotations()farklı metinleri kapsar: bir ifadenin bir nota yazılı olup olmadığına ya da sayfada çizilip çizilmediğine bakmaksızın bulmanız gerekiyorsa ikisini de çalıştırın.- Dört işaretleme yöntemi (
AddHighlight,AddUnderline,AddSquiggly,AddStrikeOut)/APgörünümünü otomatik olarak oluşturur — manuel içerik akışı çizimi gerekmez. - Şifreleme bir turdan sonra da ayakta kalır:
Document.Save()öncesindeencryptseçeneğiyle eklenen açıklamalar, belge yeniden açılıp çözüldükten sonra da geçerli kalır.
Yaygın Sorunlar
| Sorun | Neden | Düzeltme |
|---|---|---|
page.Annotations.find(), yeni eklediğiniz bir açıklama için undefined döndürür | Açıklama eklenmeden önce yakalanan eski bir dizi aranıyor | page.Annotations‘ı Add*() çağrısından sonra yeniden oku, ya da çağrının döndürdüğü tutamacı doğrudan kullan |
SearchAnnotationText(), sayfada görünen metin için hiçbir şey bulamaz | Metin, açıklama tarafından çizilir (ör. bir FreeText‘ın gövdesi), /Contents içinde taşınmaz | SearchAnnotations() kullanın — çizilen metinle eşleşir |
Açıklama, Flatten() sonrasında hâlâ düzenlenebilir görünüyor | Flatten(), Add*() tarafından döndürülen tutamağın yerine bir kopya üzerinde çağrıldı | Flatten()‘ı, oluşturma yöntemi tarafından doğrudan döndürülen nesne üzerinde çağırın |
FAQ
SearchAnnotationText ile SearchAnnotations arasındaki fark nedir?
SearchAnnotationText() metni bir açıklamayla eşleştirir carries — /Contents, /T (author), veya /Subj — bir yapışkan notun gövdesi gibi. SearchAnnotations() metni bir açıklama ile eşleştirir draws sayfada, örneğin bir FreeTextgörünür kelimeler. İkisi birbirinden ayrıdır: birinde bir eşleşme diğerinde ortaya çıkmaz.
Bir açıklamayı kalıcı ve etkileşimsiz nasıl yaparım?
Flatten() işlevini, onu oluşturan Add*() yönteminin döndürdüğü Annotation tutamağı üzerinde çağırın. Bu, görünümünü sayfanın içerik akışına yerleştirir ve /Annots‘den kaldırır.
Hangi açıklama alt türleri destekleniyor?
Page, metin işaretlemesi (AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), notlar ve açıklamalar (AddTextNote, AddFreeText, AddCaret), bağlantılar (AddLink), şekiller (AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), serbest el mürekkebi (AddInk), damgalar (AddStamp) ve dosya ekleri (AddFileAttachment) için oluşturma yöntemlerini sunar.
Bir sayfada zaten bulunan tüm açıklamaları nasıl listeleyebilirim?
page.Annotations‘ı okuyun, Annotation tutamaçlarından oluşan bir dizi. Her biri Subtype, Rect, Color, Contents ve diğer ortak özellikleri ortaya koyar, böylece standart dizi yöntemleriyle filtreleyebilir veya inceleyebilirsiniz.
API Reference Özeti
| Sınıf/Yöntem | Açıklama |
|---|---|
Annotation | Herhangi bir açıklama üzerinde temel tutamaç; Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity öğelerini ortaya çıkarır. |
Annotation.Flatten() | Açıklamanın görünümünü statik sayfa içeriğine göm |
TextAnnotation | Bir /Text yapışkan not tutamağı; Icon, Open, Author ekler |
StampAnnotation | Bir /Stamp kauçuk damga tutamağı; StampName ekler |
MarkupAnnotation | Bir metin işaretleme tutamağı (Highlight/Underline/StrikeOut/Squiggly); MarkupType, QuadPoints ekler |
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly() | /QuadPoints üzerinde bir metin işaretleme açıklaması oluşturun |
Page.AddTextNote() | Yapışkan not açıklaması oluşturun |
Page.AddLink() | Bir URI veya dahili eylem içeren tıklanabilir bir bağlantı oluşturun |
Page.Annotations | Sayfadaki her Annotation, bir dizi olarak |
Page.SearchAnnotationText() | Bir açıklamanın taşıdığı metni bul (/Contents, /T, /Subj) |
Page.SearchAnnotations() | Bir açıklamanın sayfada çizdiği metni bul |