PDF Açıklamalarıyla Çalışma

PDF Açıklamalarıyla Çalışma

PDF açıklamaları, Aspose.PDF FOSS for C++‘de Annotation temel sınıfı ve onun somut alt türleri (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation ve diğerleri) tarafından temsil edilir. Her sayfa, Page.Annotations() aracılığıyla açıklamalarını ortaya çıkarır; bu, bir AnnotationCollection döndürür. Bu kılavuz, bir sayfaya açıklama eklemeyi, bunları yinelemeyi ve kaldırmayı, mevcut bir belgeden açıklamaları okumayı, bağlantı eylemleri eklemeyi, görünümü özelleştirmeyi ve açıklamaları düzleştirmeyi kapsar.

Bir Sayfaya Açıklama Eklemek

Somut bir açıklama örneği oluşturun, Rectangle ile konumlandırın ve AnnotationCollection.Add() ile sayfanın koleksiyonuna ekleyin. TextAnnotation, sayfada bir noktaya sabitlenmiş yapışkan-not tarzı yorumu temsil eder:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& page = doc.Pages()[1];

    Aspose::Pdf::Annotations::TextAnnotation note(doc);
    note.Rect(Aspose::Pdf::Rectangle(100.0, 700.0, 200.0, 720.0, false));
    note.Contents("Reviewed and approved");

    page.Annotations().Add(note);
    doc.Save("annotated.pdf");
}

Annotation.Contents() / Contents(value) not metnini alır ve ayarlar, Annotation.Rect() / Rect(value) ise açıklamayı sayfada konumlandırır.

Açıklamaları Yineleme ve Kaldırma

AnnotationCollection, sayma, indeksli erişim, üyelik kontrolleri ve değer ya da indeks ile kaldırma işlemlerini destekler:

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

    std::cout << "Annotation count: " << annotations.Count() << "\n";

    for (int i = 0; i < annotations.Count(); ++i) {
        std::cout << "Contents: " << annotations[i].Contents() << "\n";
    }

    if (annotations.Count() > 0) {
        annotations.Delete(0);   // remove by index
    }
    annotations.Clear();         // remove everything
}

AnnotationCollection.Contains(annotation) ve Remove(annotation) belirli bir açıklama referansı üzerinde çalışır; Delete(index) konuma göre siler ve Delete(annotation) indeksine ihtiyaç duymadan belirli bir açıklamayı siler. IsReadOnly() koleksiyonun değiştirilebilir olup olmadığını raporlar.

Mevcut Bir Belgede Açıklamaları Okuma

Bir belge yüklendiğinde, açıklamaları zaten doldurulmuş olur ve hiçbir şey eklemeden incelenebilir. Annotation.AnnotationType() alt türü raporlar (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark ve diğerleri):

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

    for (int i = 0; i < annotations.Count(); ++i) {
        auto& a = annotations[i];
        if (a.AnnotationType() == Aspose::Pdf::Annotations::AnnotationType::Text) {
            std::cout << "Note: " << a.Contents() << "\n";
        }
    }
}

Açıklama sırası ve alt tür, kaydet/yeniden yükleme döngüsü boyunca korunur, böylece bir belge yüklendikten sonra Annotations() içinde indeksleme yapan kod, dosya yazıldığında mevcut olan aynı diziyi görür.

Bağlantı Açıklamaları ve Eylemler

LinkAnnotation bir sayfaya tıklanabilir bir bölge ekler ve etkinleştirildiğinde bir PdfAction gönderir. NamedAction önceden tanımlanmış bir gezinme hedefine atlar, JavascriptAction bir ECMAScript dizesi çalıştırır ve SubmitFormAction bir FileSpecification aracılığıyla form verilerini bir URL’ye gönderir:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/link_annotation.hpp>
#include <aspose/pdf/annotations/named_action.hpp>
#include <aspose/pdf/annotations/predefined_action.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc;
    auto page = doc.Pages().Add();

    Aspose::Pdf::Annotations::LinkAnnotation link(
        page, Aspose::Pdf::Rectangle(0.0, 0.0, 100.0, 20.0, false));
    link.Action(Aspose::Pdf::Annotations::NamedAction(
        Aspose::Pdf::Annotations::PredefinedAction::LastPage));

    page.Annotations().Add(link);
    doc.Save("linked.pdf");
}

LinkAnnotation.Action(value) herhangi bir PdfAction alt türünü kabul eder ve dahili olarak kopyasını oluşturur, böylece açıklama eylemin kendi kopyasını tutar. LinkAnnotation.Destination() / Destination(value) bir eylem yerine açık bir gezinme hedefi belirler ve Highlighting() / Highlighting(value) bağlantı tıklandığında gösterilen görsel geri bildirimi kontrol eder.

Açıklama Görünümü: Kenarlık, Bayraklar ve Renk

Her Annotation, bir Border, AnnotationFlags bit alanı ve görünümünü oluşturmak için kullanılan bir Color sunar:

#include <aspose/pdf/annotations/border_style.hpp>
#include <aspose/pdf/annotations/annotation_flags.hpp>
#include <aspose/pdf/color.hpp>

// 'note' is an existing Annotation reference, e.g. from AnnotationCollection.
note.Border().Width(2);
note.Border().Style(Aspose::Pdf::Annotations::BorderStyle::Dashed);
note.Flags(Aspose::Pdf::Annotations::AnnotationFlags::Print);
note.Color(Aspose::Pdf::Color::Red());

Border.Style(), BorderStyle::Solid, Dashed, Beveled, Inset veya Underline kabul eder. Border.Effect(), ayrıca EffectIntensity() ile ne kadar belirgin olacağını kontrol eden bir BorderEffect::Cloudy taslağını destekler. AnnotationFlags bir bit alanıdır — Print, NoZoom, ReadOnly ve LockedContents gibi değerleri birleştirerek bir açıklamanın bir görüntüleyicide görünür içeriğini değiştirmeden nasıl davrandığını kontrol edin.

Açıklamaları Düzleştirme

Tek bir açıklama, Annotation.Flatten() doğrudan çağırılarak — sayfa içeriğine birleştirilip etkileşimsiz hâle getirilerek — düzleştirilebilir:

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();
    for (int i = 0; i < annotations.Count(); ++i) {
        annotations[i].Flatten();
    }
    doc.Save("flattened.pdf");
}

Belge çapında açıklama işlemleri için, PdfAnnotationEditor, API boyunca kullanılan ortak Facade desenini izler: bir kaynak belgeyi BindPdf() ile bağlayın, bir veya daha fazla açıklama işlemi uygulayın, ardından sonucu Save() ile yazın:

#include <aspose/pdf/facades/pdf_annotation_editor.hpp>

int main() {
    Aspose::Pdf::Facades::PdfAnnotationEditor editor;
    editor.BindPdf("annotated.pdf");
    editor.FlatteningAnnotations();
    editor.Save("flattened.pdf");
}

PdfAnnotationEditor.DeleteAnnotations(), bağlanmış belgedeki tüm açıklamaları kaldırır; DeleteAnnotations(annotType), kaldırmayı tek bir AnnotationType ile sınırlar. ImportAnnotationsFromXfdf(xfdfFile) ve ImportAnnotationsFromFdf(fdfFile), başka bir PDF görüntüleyicisinden dışa aktarılmış açıklama verilerini yükler.

İpuçları ve En İyi Uygulamalar

• Her zaman yeni oluşturulmuş bir açıklamayı Page.Annotations()‘a ekleyin, ardından Document.Save()‘ı çağırın — bir koleksiyona eklenmeyen açıklama çıktı dosyasına yazılmaz.
• Eğer ek açıklamanın hâlâ mevcut olduğundan emin değilseniz AnnotationCollection.Contains(annotation) kullanın; Remove() çağırmadan önce. Remove(), ek açıklama yokken bir istisna fırlatmak yerine false döndürür.
• Güvenilmeyen veya üçüncü taraf bir PDF dosyasından yüklenen ek açıklamaları yineleme sırasında alt tür davranışına göre tip dönüşümü veya dallanma yapmadan önce Annotation.AnnotationType() kontrol edin.
• Belgeyi arşivlemeden önce ek açıklamaları Annotation.Flatten() ile (veya tüm belge için PdfAnnotationEditor.FlatteningAnnotations() kullanarak) düzleştirin ki diğer araçlardaki inceleyiciler sizin oluşturduğunuz aynı görünümü görebilsin.
• AnnotationFlags bir bit alanıdır — bir seferde yalnızca bir bayrağın aktif olabileceğini varsaymak yerine, bayrakları enum’un temel tamsayı değerleriyle birleştirin.

Yaygın Sorunlar

FAQ

Bir PDF sayfasına yorum tarzı ek açıklama nasıl eklerim?

Hedef Document ile bir TextAnnotation oluşturun, Rect() ve Contents() özelliklerini ayarlayın, ardından kaydetmeden önce page.Annotations() öğesine ekleyin.

Bakmakta olduğum ek açıklamanın türünü nasıl öğrenebilirim?

Annotation.AnnotationType() fonksiyonunu çağırın; bu, Text, Link, Highlight, FreeText, FileAttachment veya Watermark gibi bir AnnotationType enum değeri döndürür.

Bir ek açıklama birden fazla bayrak taşıyabilir mi?

Evet. AnnotationFlags bir bit alanıdır (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents ve diğerleri), bu yüzden bir ek açıklamada birden fazla bayrak birleştirilebilir.

Bir ek açıklamayı düzleştirmekle bir belgeyi düzleştirmek arasındaki fark nedir?

Annotation.Flatten(), tek bir ek açıklamayı sayfanın içeriğine birleştirir. PdfAnnotationEditor.FlatteningAnnotations() (isteğe bağlı olarak sayfa aralığı ve AnnotationType ile, start, end ve annotType kabul eden aşırı yükleme yoluyla) tek bir çağrıda tüm bağlanmış belgeyi düzleştirir.

Bir belgeden aynı türdeki tüm ek açıklamaları nasıl kaldırırım?

Belgeyi PdfAnnotationEditor.BindPdf() ile bağlayın, hedef AnnotationType ile DeleteAnnotations(annotType) fonksiyonunu çağırın, ardından sonucu Save().

API Reference Özeti

Ayrıca Bakınız

• Aspose.PDF — Enterprise Documentation