Práce s PDF anotacemi

Práce s anotacemi PDF

PDF anotace v Aspose.PDF FOSS pro C++ jsou reprezentovány základní třídou Annotation a jejími konkrétními podtypy (TextAnnotation, LinkAnnotation, HighlightAnnotation, FreeTextAnnotation, CircleAnnotation, WatermarkAnnotation, WidgetAnnotation a dalšími). Každá stránka zpřístupňuje své anotace prostřednictvím Page.Annotations(), která vrací AnnotationCollection. Tento průvodce pokrývá přidávání anotací na stránku, iteraci a odstraňování, čtení anotací z existujícího dokumentu, připojování akcí odkazů, přizpůsobení vzhledu a zploštění anotací.

Přidávání anotací na stránku

Vytvořte konkrétní instanci anotace, umístěte ji pomocí Rectangle a přidejte ji do kolekce stránky pomocí AnnotationCollection.Add(). TextAnnotation představuje komentář ve stylu lepicí poznámky ukotvený k bodu na stránce:

#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) získávají a nastavují text poznámky a Annotation.Rect() / Rect(value) umisťují anotaci na stránku.

Iterace a odstraňování anotací

AnnotationCollection podporuje počítání, indexovaný přístup, kontrolu příslušnosti a odstraňování podle hodnoty nebo podle indexu:

#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) a Remove(annotation) pracují s konkrétní referencí anotace; Delete(index) odstraňuje podle pozice a Delete(annotation) odstraňuje konkrétní anotaci bez nutnosti jejího indexu. IsReadOnly() oznamuje, zda lze kolekci upravovat.

Čtení anotací z existujícího dokumentu

Když je dokument načten, jeho anotace jsou již naplněny a lze je prozkoumat, aniž by se něco přidávalo. Annotation.AnnotationType() oznamuje podtyp (AnnotationType::Text, AnnotationType::Highlight, AnnotationType::Link, AnnotationType::FreeText, AnnotationType::FileAttachment, AnnotationType::Watermark a další):

#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";
        }
    }
}

Pořadí anotací a podtyp jsou zachovány během uložení/načtení, takže kód, který indexuje do Annotations() po načtení dokumentu, vidí stejnou sekvenci, která byla přítomna při zápisu souboru.

Odkazové anotace a akce

LinkAnnotation připojuje klikací oblast ke stránce a po aktivaci spouští PdfAction. NamedAction přeskakuje na předdefinovaný cílový navigační bod, JavascriptAction spouští řetězec ECMAScript a SubmitFormAction odesílá data formuláře na URL pomocí FileSpecification:

#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) přijímá libovolný podtyp PdfAction a interně jej klonuje, takže anotace si uchovává vlastní kopii akce. LinkAnnotation.Destination() / Destination(value) nastavují explicitní navigační cíl místo akce a Highlighting() / Highlighting(value) řídí vizuální zpětnou vazbu zobrazenou během kliknutí na odkaz.

Vzhled anotace: okraj, příznaky a barva

Každý Annotation vystavuje Border, bitové pole AnnotationFlags a Color používané k vykreslení jeho vzhledu:

#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() přijímá BorderStyle::Solid, Dashed, Beveled, Inset nebo Underline. Border.Effect() navíc podporuje BorderEffect::Cloudy obrys s EffectIntensity() řídícím, jak výrazný je. AnnotationFlags je bitové pole — kombinujte hodnoty jako Print, NoZoom, ReadOnly a LockedContents, abyste řídili chování anotace v prohlížeči, aniž byste měnili její viditelný obsah.

Zploštění anotací

Jedna anotace může být zploštěna — sloučena s obsahem stránky a učiněna neinteraktivní — voláním Annotation.Flatten() přímo:

#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");
}

Pro operace anotací na úrovni celého dokumentu PdfAnnotationEditor používá sdílený vzor Facade používaný napříč API: svázat zdrojový dokument s BindPdf(), provést jednu nebo více operací anotací a poté zapsat výsledek pomocí Save():

#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() odstraňuje všechny anotace ze svázaného dokumentu; DeleteAnnotations(annotType) omezuje odstranění na jedinou AnnotationType. ImportAnnotationsFromXfdf(xfdfFile) a ImportAnnotationsFromFdf(fdfFile) načítají data anotací exportovaná z jiného PDF prohlížeče.

Tipy a osvědčené postupy

Vždy přidejte nově vytvořenou anotaci do Page.Annotations() před voláním Document.Save() — anotace, která není přidána do kolekce, není zapsána do výstupního souboru.
Použijte AnnotationCollection.Contains(annotation) před voláním Remove(), pokud si nejste jisti, že anotace stále existuje; Remove() vrací false místo vyhození výjimky, když anotace chybí.
Zkontrolujte Annotation.AnnotationType() před převodem nebo rozvětvením podle chování podtypu při iteraci anotací načtených z nedůvěryhodného nebo třetí strany PDF souboru.
Zploštěte anotace pomocí Annotation.Flatten() (nebo PdfAnnotationEditor.FlatteningAnnotations() pro celý dokument) před archivací dokumentu, aby recenzenti v jiných nástrojích viděli stejný vzhled, který jste vytvořili.
AnnotationFlags je bitové pole — kombinujte příznaky s podkladovými celočíselnými hodnotami výčtu místo předpokladu, že může být aktivní najednou jen jeden příznak.

Časté problémy

Problém	Příčina	Oprava
Anotace není po uložení viditelná	Anotace byla vytvořena, ale nikdy nebyla přidána do `Page.Annotations()`	Zavolejte `page.Annotations().Add(annotation)` před `doc.Save()`
`Remove()` vrací `false`	Předaný odkaz na anotaci neodpovídá žádnému záznamu v aktuální kolekci	Nejprve použijte `Contains()`, nebo odstraňte podle indexu pomocí `Delete(index)`
Špatný typ anotace po načtení	Kód předpokládal konkrétní podtyp, aniž by kontroloval `AnnotationType()`	Rozvětvujte podle `Annotation.AnnotationType()`, než objekt zacházíte jako s konkrétním podtypem
Akce odkazu se po přiřazení zdá být nenastavena	Místní `PdfAction` vypadl z rozsahu; `LinkAnnotation.Action()` vrací klonovanou kopii anotace, nikoli původní objekt	Načtěte akci zpět přes `link.Action()` místo toho, abyste si uchovávali původní místní proměnnou
Operace `PdfAnnotationEditor` nemá žádný účinek	`BindPdf()` nebyl zavolán, nebo byl zavolán s cestou, která neexistuje	Potvrďte, že `BindPdf()` uspěje, než zavoláte `FlatteningAnnotations()` nebo `DeleteAnnotations()`

FAQ

Jak přidám anotaci ve stylu komentáře na stránku PDF?

Vytvořte TextAnnotation s cílovým Document, nastavte jeho Rect() a Contents(), pak jej přidejte do page.Annotations() před uložením.

Jak zjistím, jaký typ anotace si prohlížím?

Zavolejte Annotation.AnnotationType(), který vrací hodnotu výčtu AnnotationType, například Text, Link, Highlight, FreeText, FileAttachment nebo Watermark.

Může jedna anotace obsahovat více než jeden příznak?

Ano. AnnotationFlags je bitové pole (Default, Invisible, Hidden, Print, NoZoom, ReadOnly, LockedContents a další), takže více příznaků lze kombinovat v jedné anotaci.

Jaký je rozdíl mezi zploštěním jedné anotace a zploštěním dokumentu?

Annotation.Flatten() sloučí jednu anotaci s obsahem její stránky. PdfAnnotationEditor.FlatteningAnnotations() (volitelně omezeno rozsahem stránek a AnnotationType přes přetížení, které přijímá start, end a annotType) zploští celý vázaný dokument v jednom volání.

Jak odstraním všechny anotace určitého typu z dokumentu?

Vazte dokument pomocí PdfAnnotationEditor.BindPdf(), zavolejte DeleteAnnotations(annotType) s cílovým AnnotationType a následně Save() výsledek.

API Reference Shrnutí

Třída/Metoda	Popis:
`Annotation`	Abstraktní základní třída pro všechny podtypy anotací PDF
`Annotation.Rect()` / `Rect(value)`	Získá nebo nastaví ohraničující obdélník anotace
`Annotation.Contents()` / `Contents(value)`	Získá nebo nastaví textový obsah anotace
`Annotation.AnnotationType()`	Vrací výčtovou hodnotu `AnnotationType` pro tuto anotaci
`Annotation.Flags()` / `Flags(value)`	Získat nebo nastavit bitové pole `AnnotationFlags`
`Annotation.Border()` / `Border(value)`	Získá nebo nastaví `Border` anotace
`Annotation.Color()` / `Color(value)`	Získá nebo nastaví zobrazení anotace `Color`
`Annotation.Flatten()`	Sloučí tuto anotaci s obsahem stránky, čímž ji učiní neinteraktivní
`AnnotationCollection`	Uspořádaná kolekce anotací na stránce, vrácená pomocí `Page.Annotations()`
`AnnotationCollection.Add(annotation)` / `Add(annotation, considerRotation)`	Přidá anotaci do kolekce
`AnnotationCollection.Count()`	Vrací počet anotací v kolekci
`AnnotationCollection.Contains(annotation)`	Zjišťuje, zda kolekce obsahuje danou anotaci
`AnnotationCollection.Remove(annotation)`	Odstraní konkrétní anotaci; vrátí `false`, pokud není nalezena
`AnnotationCollection.Delete(index)` / `Delete(annotation)`	Odstraní anotaci podle indexu nebo podle reference
`AnnotationCollection.Clear()`	Odstraní všechny anotace z kolekce
`TextAnnotation`	Anotace ve stylu lepicí poznámky s `Open()` a `Icon()` (`TextIcon`)
`LinkAnnotation`	Klikací oblast odesílající `PdfAction` přes `Action()` / `Action(value)`
`LinkAnnotation.Destination()` / `Destination(value)`	Získá nebo nastaví explicitní cíl navigace
`HighlightAnnotation`	Označuje úsek textu zvýrazňovací barvou
`FreeTextAnnotation`	Zobrazuje textový callout; nakonfigurováno pomocí `Justification()`, `DefaultAppearanceObject()`, `Callout()`
`CircleAnnotation`	Vykresluje elipsu uvnitř obdélníku anotace
`WatermarkAnnotation`	Překryvová anotace s `Opacity()` / `Opacity(value)` přístupem
`WidgetAnnotation`	Anotace vzhledu formulářového pole s `ReadOnly()`, `Required()`, `Exportable()`, `DefaultAppearance()`
`NamedAction`	Předdefinovaná navigační akce (`PredefinedAction` enum) připojitelná k `LinkAnnotation`
`JavascriptAction`	Spouští řetězec ECMAScript pomocí `Script()` / `GetECMAScriptString()`
`SubmitFormAction`	Odesílá data formuláře na `FileSpecification` URL pomocí `Url()` / `Url(value)`
`Border`	Okraj anotace s `Width()`, `Style()` (`BorderStyle`), `Effect()` (`BorderEffect`)
`PdfAnnotationEditor`	Fasáda pro import, úpravu, zploštění a mazání anotací v celém dokumentu
`PdfAnnotationEditor.FlatteningAnnotations()`	Zplošťuje anotace v celém svázaném dokumentu
`PdfAnnotationEditor.DeleteAnnotations(annotType)`	Odstraňuje všechny anotace daného `AnnotationType`
`PdfAnnotationEditor.ImportAnnotationsFromXfdf(xfdfFile)`	Importuje anotace ze souboru XFDF

Viz také:

Aspose.PDF — Enterprise Documentation