PDF Açıklamaları

PDF Açıklamaları

Page.annotations, bir AnnotationCollection ortaya koyar — sayfa üzerindeki her açıklama için değiştirilebilir, dizi benzeri bir görünüm. Her giriş bir Annotation (veya MarkupAnnotation / LinkAnnotation alt sınıfları) olup, alt tipine özgü veriler (örneğin dört nokta, mürekkep listeleri veya renkler) ayrı ayrı nitelikler yerine get_property() / set_property() aracılığıyla okunur ve yazılır.

Açıklama Ekleme

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties), yeni bir açıklama oluşturur ve sayfaya ekler. subtype, ya basit bir metin ("Text", "Square", "Highlight") ya da bir AnnotationType enum üyesi kabul eder.

import aspose_pdf
from aspose_pdf import Document, AnnotationType

doc = Document()
doc.pages.add()
page = doc.pages[0]

# Plain string subtype
page.annotations.add("Text", (100, 100, 200, 200), "Hello")

# AnnotationType enum, with subtype-specific properties
page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)

Özellikleri Okuma ve Güncelleme

get_property(name, default), alt tipe özgü bir değeri okur; set_property(name, value) ise bir değer yazar ve bir özelliği None olarak ayarlamak, onu açıklamanın properties sözlüğünden kaldırır.

doc = Document()
doc.pages.add()
page = doc.pages[0]

ann = page.annotations.add(
    "Square", (0, 0, 50, 50), "x", properties={"C": [1, 0, 0]},
)
ann.set_property("IC", [0, 0, 1])
print(page.annotations[0].get_property("IC"))  # [0, 0, 1]

ann.set_property("C", None)  # removes the "C" entry entirely
print("C" in page.annotations[0].properties)  # False

Açıklamaları AnnotationName ile Adlandırma

PDF adları (ör. bir Stamp ek açıklamasının Name girişi) AnnotationName kullanılarak düz dizelerden açıkça ayrılır; bu, aspose_pdf.engine.cos sınıfından bir str alt sınıftır. Bu şekilde depolanan bir değer hâlâ sıradan bir dizeye eşit olarak karşılaştırılır.

from aspose_pdf.engine.cos import AnnotationName

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add(
    "Stamp", (10, 10, 110, 60), "",
    properties={"Name": AnnotationName("Approved")},
)

Ekleme, Silme ve Temizleme

insert(index, subtype, rect, contents, title, appearance_normal, properties) yeni bir ek açıklamayı belirli bir konuma yerleştirir; delete(index) birini indeksle kaldırır (aralık dışı bir indeks için IndexError yükseltir); clear() sayfadaki tüm ek açıklamaları kaldırır.

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Text", (0, 0, 100, 100), "A")
page.annotations.add("Text", (200, 200, 300, 300), "C")
page.annotations.insert(1, "Text", (100, 100, 200, 200), "B")
# order is now: A, B, C

page.annotations.delete(1)   # removes "B"
page.annotations.clear()     # removes everything remaining

Ek Açıklama Görünümlerini Oluşturma

Annotation.generate_appearance(force), tek bir ek açıklama için /AP /N görünüm akışını oluşturur ve o alt tür için bir renderlayıcı mevcut olduğunda True döndürür; AnnotationCollection.generate_appearances(force) aynı işlemi sayfadaki tüm ek açıklamalar için tek bir çağrıda yapar ve gerçekten oluşturulan ek açıklamaların sayısını döndürür (desteklenmeyen alt türler atlanır).

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Square", (0, 0, 50, 50), "")
page.annotations.add("Circle", (60, 0, 110, 50), "")
page.annotations.add("Text", (0, 60, 20, 80), "")  # unsupported subtype -> skipped

generated = page.annotations.generate_appearances()
print(generated)  # 2

Ek Açıklama Alt Türleri ve Bayrakları

AnnotationType, standart PDF 32000-1:2008 (Tablo 169) alt tür adlarını sıralar: TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, POLY_LINE, HIGHLIGHT, UNDERLINE, SQUIGGLY, STRIKE_OUT, STAMP, CARET, INK, POPUP, FILE_ATTACHMENT, SOUND, MOVIE, WIDGET, SCREEN, PRINTER_MARK, TRAP_NET, WATERMARK ve REDACT.

AnnotationFlags, ek açıklama görüntüleme/etkileşim davranışını kapsayan bir IntFlagdır: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED ve TOGGLE_NO_VIEW.

Ön sürüm: 3D Açıklamalar

PDF3DAnnotation, PDF3DArtwork, PDF3DContent ve PDF3DView bir sayfaya eklenmiş 3D sanat eserini model alır — bir PDF3DAnnotation bir rect: Rectangle, bir artwork: PDF3DArtwork ve isteğe bağlı bir background_color: Color içerir. PDF3DArtwork.add_view() bir PDF3DView kaydeder, her biri bir render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) ve bir lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM) taşır. Kütüphanenin kendi docstring’i PDF3DAnnotation‘yi “ön sürüm içe aktarmaları için minimal açıklama sarmalayıcısı” olarak işaretler — bu yüzeyi tam geliştirilmiş bir 3D üretim API yerine erken aşama olarak ele alın.

İpuçları ve En İyi Uygulamalar

• Kodunuzun başka yerlerinde değerin karşılaştırılması veya dallanması gerektiğinde, ham alt tip dizgeleri yerine AnnotationType enum üyelerini tercih edin.
• set_property(name, None)‘ı çağırarak bir özelliği tamamen kaldırın, eski bir değeri yerde bırakmak yerine — giriş properties‘den tamamen kaybolur.
• Her açıklama için generate_appearance()‘i döngüye almaktansa AnnotationCollection.generate_appearances ile toplu görünüm üretimi yapın; oluşturulan gerçek sayıyı döndürür, böylece atlanan/ desteklenmeyen alt tipleri tespit edebilirsiniz.
• delete() ve page.annotations‘e dizinleme ikisi de 0 tabanlıdır; kullanıcı girdisinden geliyorsa delete()‘yi çağırmadan önce dizini doğrulayın, çünkü aralık dışı bir indeks IndexError‘yi tetikler.
• PDF adı değerlerini (örneğin bir Stamp‘un Name‘i gibi) AnnotationName içinde sarın, böylece düz metin dizgileri yerine PDF adı olarak çift yönlü kullanılabilir.

Yaygın Sorunlar

FAQ

Düz metin yorum ek açıklamasını nasıl ekleyebilirim?

Çağırın page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Dört sayılık demet, sayfadaki ek açıklamanın dikdörtgenidir.

Annotation, MarkupAnnotation ve LinkAnnotation arasındaki fark nedir?

Annotation, bir sayfadaki herhangi bir ek açıklama için döndürülen canlı görünümdür. MarkupAnnotation, işaretleme tarzı alt tiplerin (vurgulamalar, metin notları, şekiller) temelidir ve LinkAnnotation, bağlantı tarzı ek açıklamalar için tutulur; her ikisi şu anda Annotation ile aynı yöntem/özellik yüzeyini ortaya çıkarır.

Tüm ek açıklamayı silmeden tek bir özelliği kaldırabilir miyim?

Evet — annotation.set_property(name, None) çağırın; ek açıklama kendisi dokunulmaz, yalnızca o giriş properties üzerinden kaldırılır.

Alt tip desteklenmediğinde AnnotationCollection.generate_appearances başarısız olur mu?

Hayır. Yerleşik bir görünüm oluşturucusu olmayan alt tipleri atlar ve görünüm oluşturduğu annotation’ların sayısını döndürür.

3D annotation sınıfları üretim için hazır mı?

PDF3DAnnotation ve ilgili tipler, ön sürüm ithalatları için minimal bir sarmalayıcı olarak belgelenmiştir — üretim 3D içeriği için onlara güvenmeden önce hedef PDF görüntüleyicinizde davranışı doğrulayın.

API Reference Özeti

Ayrıca Bakınız

• Aspose.PDF for Python — Enterprise Documentation