Python'de PDF Açıklamalarıyla Nasıl Çalışılır

Aspose.PDF FOSS for Python, bir sayfadaki her açıklamayı sayfanın AnnotationCollection aracılığıyla canlı bir Annotation nesnesi olarak ortaya çıkarır, böylece işaretleme, bağlantı ve 3D açıklamaları ekleyebilir, tipine özgü özelliklerini inceleyebilir ve PDF görüntüleyicilerin bunları render etmesi için gereken görünüm akışlarını oluşturabilirsiniz — hepsi saf Python ile. Bu kılavuz, kütüphaneyi nasıl kuracağınızı, açıklamaları nasıl ekleyeceğinizi, geri okuyacağınızı ve görünüm akışlarını nasıl oluşturacağınızı gösterir.

Adım Adım Kılavuz

Adım 1: Paketi Kurun

Aspose.PDF FOSS paketini kurun:

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

Kurulumu, aşağıdaki adımlarda kullanılan Document sınıfını ortaya çıkaran üst düzey aspose_pdf modülünü içe aktararak doğrulayın. İçe aktarma başarılı olduğunda kod parçacığı aspose_pdf OK yazdırır; bir ModuleNotFoundError genellikle paketin, betiğinizi çalıştıran ortamdan farklı bir Python ortamına kurulduğunu gösterir:

import aspose_pdf
print("aspose_pdf OK")

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

PDF’yi tutmak için Document‘ı içe aktarın, ayrıca ek açıklamaları oluşturmak ve incelemek için kullanacağınız ek açıklama sınıflarını da ekleyin:

from aspose_pdf import Document
from aspose_pdf.annotations import (
    Annotation,
    AnnotationType,
    AnnotationFlags,
    MarkupAnnotation,
    LinkAnnotation,
)

Adım 3: Bir Sayfaya Ek Açıklama Ekleyin

Her Page, ek açıklamalarını annotations özelliği aracılığıyla, bir AnnotationCollection olarak ortaya çıkarır. add(subtype, rect, contents)‘ı bir alt tip adı, bir (left, bottom, right, top) dikdörtgen ve ek açıklamanın metin içeriği ile çağırın. "Highlight" gibi standart işaretleme alt tipleri bir MarkupAnnotation örneği olarak döndürülür:

from aspose_pdf import Document

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

annotation = page.annotations.add(
    "Highlight",
    (100, 700, 300, 720),
    "Key clause",
)
print(type(annotation).__name__)   # MarkupAnnotation
print(annotation.contents)         # Key clause

Adım 4: Enum Alt Tiplerinden Ek Açıklamalar Oluşturun

AnnotationType, her standart PDF ek açıklama alt tipini (PDF 32000-1:2008, Tablo 169) listeler, böylece ham bir dize yerine bir enum üyesi geçirebilirsiniz. Tür-spesifik veriler — örneğin bir çokgenin köşe noktaları — properties sözlüğüne konur ve get_property ile geri okunur:

from aspose_pdf import Document
from aspose_pdf.annotations import AnnotationType

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

annotation = page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)
print(annotation.subtype)                    # Polygon
print(annotation.get_property("Vertices"))   # [0, 0, 10, 0, 5, 10]

Adım 5: Mevcut Ek Açıklamaları Oku ve Döngüye Al

AnnotationCollection yinelenebilir, bu yüzden bir sayfada zaten bulunan her ek açıklamayı — mevcut bir PDF’den yüklenenler dahil — gezebilir ve her Annotation‘ın ortaya çıkardığı ortak özellikleri (subtype, contents, rect, title, author, color) okuyabilirsiniz:

from aspose_pdf import Document

document = Document()
document.pages.add()
page = document.pages[0]
page.annotations.add("Text", (50, 50, 70, 70), "First note")
page.annotations.add("Text", (80, 80, 100, 100), "Second note")

for annotation in page.annotations:
    print(annotation.subtype, "-", annotation.contents)

Adım 6: Açıklama Görünüm Akışlarını Oluştur

Açık bir appearance_normal olmadan oluşturulan bir açıklama, bir tane üretilene kadar görünür bir işleme (/AP /N) sahip değildir. Tek bir Annotation üzerinde generate_appearance(force) çağırın veya tüm AnnotationCollection üzerinde generate_appearances(force) çağırarak sayfadaki eksik tüm görünüm akışlarını bir kerede sentezleyin:

from aspose_pdf import Document
from aspose_pdf.engine.cos import AnnotationName

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

stamp = page.annotations.add(
    "Stamp",
    (100, 100, 260, 150),
    "",
    properties={"Name": AnnotationName("Approved")},
)
if stamp.generate_appearance():
    print(f"Appearance stream: {len(stamp.appearance_normal)} byte(s)")

# Regenerate every missing appearance stream on the page in one call:
count = page.annotations.generate_appearances(force=True)
print(f"Regenerated {count} appearance stream(s)")

Adım 7: Açıklama Alt Sınıflarını Ayırt Et

AnnotationCollection.add(), alt türe göre belirli bir alt sınıfa yönlendirir: işaretleme tarzı alt türler (Highlight, Square, Stamp ve benzerleri) MarkupAnnotation olarak geri döner, ve "Link" LinkAnnotation olarak geri döner. İkisi de Annotation üzerinden tüm yöntem ve özellikleri devralır, bu yüzden isinstance kontrolleri, subtype dizelerini doğrudan incelemeden açıklama türüne göre dallanmanıza izin verir:

from aspose_pdf import Document
from aspose_pdf.annotations import LinkAnnotation, MarkupAnnotation

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

link = page.annotations.add("Link", (50, 750, 200, 770), "")
highlight = page.annotations.add("Highlight", (50, 700, 200, 720), "")

print(isinstance(link, LinkAnnotation))         # True
print(isinstance(highlight, MarkupAnnotation))  # True

Yaygın Sorunlar ve Çözümler

get_property returns None az önce ayarladığım bir özellik için

properties anahtarları tam, büyük/küçük harfe duyarlı PDF alan adlarıdır ("Vertices", "Name" ve benzerleri) — bir yazım hatası veya yanlış büyük/küçük harf sessizce yok sayılır, hata yükseltilmez. get_property(name, default)‘e bir default argümanı geçirin ve yeni bir alt türü hata ayıklarken bunu açıkça kontrol edin.

generate_appearance() returns False

Yerleşik oluşturucu tarafından her alt tip ve özellik kombinasyonu bir görünüm akışına sentezlenemez. Çağrının başarılı olduğunu varsamadan önce has_appearance kontrol edin ve oluşturucunun kapsam dışı bıraktığı alt tipler için add() üzerine doğrudan önceden oluşturulmuş bir appearance_normal (bytes) sağlayın.

Beklenmeyen ek açıklama alt sınıfı sonrası add()

Gönderdiğiniz alt tip dizesi (veya AnnotationType üyesi) döndürülen sınıfı belirler: işaretleme alt tipleri MarkupAnnotation olarak döner, "Link" LinkAnnotation olarak döner ve tanınan diğer tüm alt tipler temel Annotation olarak döner. Belirli bir alt tip dizesi varsaymak yerine isinstance()‘i MarkupAnnotation/LinkAnnotation karşısında kullanın.

AnnotationFlags değerler rendering’i değiştirmiyor gibi görünüyor

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY ve benzerleri) bir Python IntFlag enum’udur; ek açıklamanın davranış bitlerini | operatörüyle oluşturmak ve yorumlamak için kullanılır — bu bir değer tipidir, Annotation.add()‘in otomatik olarak yazdığı bir özellik değildir. İhtiyacınız olan bayrakları birleştirin ve diğer alt tip-özel verilerde kullanılan aynı tür-özel properties mekanizmasıyla geçirin.

Henüz ek açıklaması olmayan bir sayfayla çalışmak

page.annotations her zaman geçerli (belki boş) bir AnnotationCollection dir — add() çağırmadan, yineleme yapmadan veya clear() çağırmadan önce None kontrol etmenize hiç gerek yok.

Sıkça Sorulan Sorular

Aspose.PDF Python için FOSS hangi ek açıklama alt türlerini destekliyor?

AnnotationType, PDF 32000-1:2008 Tablo 169’da yer alan 25 standart alt türün tamamını, TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT ve daha fazlasını sayar.

Bu kütüphane 3D ek açıklamaları destekliyor mu?

Evet. PDF3DAnnotation, birlikte PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, ve PDF3DRenderMode, ön sürüm PDF 3D iş akışları için minimal bir PDF 3D ek açıklama yüzeyi (bir dikdörtgen, gömülü sanat eseri ve adlandırılmış görünümler) modellemektedir. Bkz. PDF3DAnnotation referansı tam özellik kümesi için.

Bir sayfadan ek açıklamayı nasıl kaldırırım?

Pozisyona göre tek bir ek açıklamayı kaldırmak için page.annotations.delete(index)‘ı, sayfadaki tüm ek açıklamaları kaldırmak için ise page.annotations.clear()‘ı çağırın.

Ek açıklamayı eklemek yerine belirli bir konuma ekleyebilir miyim?

Evet — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties), add() ile aynı argümanları alır ve ayrıca hedef index.

Bir ek açıklamanın rengi nasıl temsil edilir?

color özelliği Annotation üzerinde (ve alt sınıflarında) PDF /C girdisinin bileşen sayısıyla eşleşen bir tuple[float, ...]‘dir (renk ayarlanmamışsa boş olur) — ayrı bir renk nesnesi değildir.