Ereignisbasierte Änderungen der XPS-Seite | .NET

Was ist der ereignisbasierte Ansatz in der Programmierung?

Der ereignisbasierte Ansatz in der Programmierung ist ein Paradigma, das sich um das Konzept von Ereignissen und der Ereignisbehandlung dreht. In diesem Modell wird der Programmablauf durch Ereignisse bestimmt, bei denen es sich um Benutzeraktionen (wie Mausklicks oder Tastendrücke), vom System generierte Benachrichtigungen oder Nachrichten von anderen Anwendungen handeln kann. Hier sind einige Schlüsselaspekte des ereignisbasierten Ansatzes:

• Ereignisse: Ereignisse stellen wichtige Ereignisse in einem Programm dar. Dazu können Benutzerinteraktionen, Datenänderungen oder Nachrichten von anderen Teilen eines Systems gehören. Beispielsweise kann ein Klick auf eine Schaltfläche oder das Laden einer Datei Ereignisse auslösen.

• Ereignis-Listener: Um auf Ereignisse zu reagieren, verwenden Programmierer Ereignis-Listener (oder Handler). Dies sind Funktionen oder Methoden, die so definiert sind, dass sie ausgeführt werden, wenn ein bestimmtes Ereignis eintritt. Beispielsweise kann ein Ereignis-Listener so eingerichtet werden, dass er eine Funktion ausführt, wenn ein Benutzer auf eine Schaltfläche klickt.

• Asynchrone Ausführung: Das ereignisbasierte Modell unterstützt oft die asynchrone Programmierung, sodass Programme reagieren können, während sie auf das Eintreten von Ereignissen warten. Beispielsweise kann eine Webanwendung weiter ausgeführt werden, während sie auf Daten von einem Server wartet.

• Entkopplung: Der ereignisbasierte Ansatz fördert die Entkopplung zwischen verschiedenen Teilen eines Programms. Komponenten können über Ereignisse kommunizieren, ohne die Details der Implementierung der anderen Komponenten kennen zu müssen, wodurch der Code modularer und einfacher zu warten ist.

• Häufige Anwendungsfälle: Ereignisgesteuerte Programmierung wird häufig in grafischen Benutzeroberflächen (GUIs), Webanwendungen und Systemen verwendet, die Echtzeitinteraktionen erfordern. Frameworks und Bibliotheken wie Node.js, React und viele andere nutzen ereignisgesteuerte Muster.

• Zustandsverwaltung: In einem ereignisgesteuerten System kann die Verwaltung des Zustands von entscheidender Bedeutung sein, da sich die Anwendung je nach Benutzerinteraktionen oder Ereignissen in unterschiedlichen Zuständen befinden kann. Um sicherzustellen, dass sich die Anwendung wie erwartet verhält, werden häufig geeignete Strategien zur Zustandsverwaltung eingesetzt.

Insgesamt ist der ereignisbasierte Ansatz eine leistungsstarke Möglichkeit, Interaktionen und Arbeitsabläufe innerhalb eines Programms zu verwalten, was ihn besonders effektiv für Anwendungen macht, die Reaktionsfähigkeit und Benutzerinteraktion erfordern.

Ereignisse, die während der XPS-Dokumentkonvertierung auftreten

Wenn Sie mithilfe der Aspose.Page-API Änderungen an einer bestimmten Seite eines XPS-Dokuments vornehmen müssen, wählen Sie normalerweise das aktive Dokument aus (wenn die XPS-Datei mehrere Dokumente enthält), wählen Sie die aktive Seite aus und nehmen Sie dann die Änderungen selbst vor .

Angenommen, Sie müssen wiederholte Änderungen an allen Seiten in einer XPS-Datei vornehmen und das Ergebnis dann in PDF oder ein Bildformat konvertieren. Einige Beispiele für solche Änderungen umfassen das Platzieren eines Wasserzeichens über den Seiten oder das Hinzufügen von Navigations-Hyperlinks. Der direkte Weg, solche Änderungen vorzunehmen, besteht darin, die Dokumente im XPS-Paket zu durchsuchen, die Seiten im aktuell aktiven Dokument zu durchsuchen und schließlich Ihre Änderungen anzuwenden. Daher würde der Code zum Ausführen dieser Aufgabe wie folgt aussehen:

for (int i = 1; i <= document.DocumentCount; i++)
{
    document.SelectActiveDocument(i);
    for (j = 1; j <= document.PageCount; j++)
    {
        document.SelectActivePage(j);
        // Your changes ...
    }
}
document.SaveAsPdf("file-name.pdf", saveOptions);

Wenn Sie vor den sich wiederholenden Änderungen auch einige unregelmäßige Änderungen vornehmen müssen, kann dieser Ansatz zu Verwirrung oder übermäßigem Durchlaufen von Dokumenten und Seiten führen, ganz zu schweigen davon, dass diese Schleifen etwas umständlich erscheinen. Wenn Sie ein XPS-Dokument in ein PDF oder ein Bild konvertieren, erfolgt der Vorgang Seite für Seite. Wenn der Konvertierungsauftrag bereit ist, die nächste Seite zu verarbeiten, löst er ein „Before-Page“-Ereignis aus. Der Benutzer kann die Behandlung solcher Ereignisse definieren, indem er die Klasse BeforePageSavingEventHandler erweitert und so einige Vorteile nutzt, die im Einführungsabschnitt dieses Artikels beschrieben werden.

Beispiel für das Hinzufügen von Navigations-Hyperlinks

Hier stellen wir ein Beispiel für Navigations-Hyperlinks vor. Und um die Aufgabe etwas komplizierter zu machen, konvertieren wir nur eine Teilmenge aller Seiten in PDF, wie durch die Eigenschaft „PdfSaveOptions.PageNumbers“ angegeben.

Die Event-Handler-Klasse

Unten ist die Erweiterung der Klasse „BeforePageSavingEventHandler“:

/// <summary>
/// The class to handle the before-page event while converting an XPS document.
/// </summary>
public class NavigationInjector : BeforePageSavingEventHandler
{
    // The font in which navigation hyperlinks and page numbers will be displayed.
    private readonly XpsFont _font;
    // The page numbers to convert.
    private readonly SortedList<int, int> _pageNumbers;

    public NavigationInjector(XpsFont font, int[] pageNumbers)
    {
        _font = font;
        if (pageNumbers == null)
            return;

        // Turn the page number array into a sorted collection of unique values.
        _pageNumbers = new SortedList<int, int>();
        foreach (int pn in pageNumbers)
            _pageNumbers[pn] = 0;
    }

    public override void Handle(BeforeSavingEventArgs<PageAPI> args)
    {
        PageAPI api = args.ElementAPI;

        XpsGlyphs glyphs;
        // For all pages in the output PDF except the first one...
        if (args.OutputPageNumber > 1)
        {
            // ...insert a hyperlink to the first page...
            glyphs = api.CreateGlyphs(_font, 15f, 5f, api.Height - 10f, "[First]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(_pageNumbers == null ? 1 : _pageNumbers.Keys[0]);
            api.Add(glyphs);

            // ...and to the previous page.
            glyphs = api.CreateGlyphs(_font, 15f, 60f, api.Height - 10f, "[Prev]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? args.AbsolutePageNumber - 1 : _pageNumbers.Keys[args.OutputPageNumber - 2]);
            api.Add(glyphs);
        }

        // For all pages in the output PDF except the last one...
        if ((_pageNumbers != null && args.OutputPageNumber < _pageNumbers.Count) ||
            (_pageNumbers == null && args.OutputPageNumber < api.TotalPageCount))
        {
            // ...insert a hyperlink to the next page...
            glyphs = api.CreateGlyphs(_font, 15f, 110f, api.Height - 10f, "[Next]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? args.AbsolutePageNumber + 1 : _pageNumbers.Keys[args.OutputPageNumber]);
            api.Add(glyphs);

            // ...and to the last page.
            glyphs = api.CreateGlyphs(_font, 15f, 160f, api.Height - 10f, "[Last]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? api.TotalPageCount : _pageNumbers.Keys[_pageNumbers.Keys.Count - 1]);
            api.Add(glyphs);
        }

        // Insert a page number in the bottom-right corner.
        glyphs = api.CreateGlyphs(_font, 15f, api.Width - 20f, api.Height - 10f, args.OutputPageNumber.ToString());
        glyphs.Fill = api.CreateSolidColorBrush(Color.Black);
        api.Add(glyphs);

        // Add an outline entry to display the links to the converted pages in the navigation pane of a PDF viewer.
        api.AddOutlineEntry(string.Format("Page {0}", args.OutputPageNumber), 1, args.AbsolutePageNumber);
    }
}

Die Handler-Klasse sollte wissen, welche Seiten wir als PDF speichern möchten, um die richtigen Hyperlink-Ziele zu erstellen. Daher sollte der Konstruktor die Array-Eigenschaft der Optionen als Argument verwenden. Wenn das Array von Seitenzahlen angegeben ist, erstellen wir eine sortierte Sammlung davon und vermeiden gleichzeitig Duplikate. (Übrigens ist diese Lösung nicht ganz korrekt. Können Sie herausfinden, was zu Inkonsistenzen in der Ausgabe führen könnte?) Wir benötigen außerdem ein „XpsFont“-Objekt, das die Schriftartdaten für den Hyperlink-Text enthält.

In der überschriebenen Methode „Handle()“ geschieht alles. Das Argument der Methode ist ein Objekt, das die Änderungs-API für die aktuelle Seite, die Dokumentnummer innerhalb des XPS-Pakets, die absolute Seitenzahl über alle Dokumente hinweg, die relative Seitenzahl innerhalb des aktuellen Dokuments (die gleich ist) enthält vorherige Nummer, falls sich nur ein Dokument im Paket befindet und die Ausgabeseitennummer (die der absoluten Seitenzahl entspricht, wenn wir das gesamte Paket konvertieren).

Die Logik der folgenden zwei „Wenn“-Blöcke ist recht einfach. Es basiert auf der Analyse des Ereignisarguments „OutputPageNumber“, um gegebenenfalls einige der Links wegzulassen: Die Links [First] und [Prev] werden allen Ausgabeseiten außer der ersten hinzugefügt, während die Links „ Die Links [Weiter] und [Letzte] werden auf allen Seiten außer der letzten angezeigt. Die Logik ist auch auf beide Fälle zugeschnitten, unabhängig davon, ob Seitenzahlen angegeben sind oder nicht.

Nach den „if“-Blöcken gibt es Code zum Hinzufügen einer Seitenzahl in der unteren rechten Ecke der Seite.

Die letzte Zeile fügt den Gliederungseintrag der Seite hinzu, das Element, das im Navigationsbereich eines PDF-Viewers angezeigt wird (sofern unterstützt).

Der Konvertierungscode

Nachdem nun der Ereignishandler „before-page“ definiert ist, können wir den Code schreiben, der das Dokument konvertiert:

// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithPages();
// Open an XPS document
using (XpsDocument doc = new XpsDocument(dataDir + "Sample3.xps"))
// Create a font
using (Stream fontStream = File.OpenRead(dataDir + "arialbd.ttf"))
{
    // Create options for conversion to PDF
    PdfSaveOptions options = new PdfSaveOptions();
    // Set the filter for the pages that need conversion
    options.PageNumbers = new int[] { 2, 6, 7, 13 };
    // Add the event handler that will execute right before the conversion of each page
    options.BeforePageSavingEventHandlers.Add(new NavigationInjector(doc.CreateFont(fontStream), options.PageNumbers));
    // Save resultant XPS document
    doc.SaveAsPdf(dataDir + "ModifyPageOnConversion_out.pdf", options);
}

Wir öffnen eine XPS-Datei und instanziieren dann ein Stream-Objekt mit der Schriftartdatendatei. Als nächstes erstellen wir eine Instanz der Klasse „PdfSaveOptions“ und geben die Anzahl der Seiten an, die wir konvertieren müssen. In der nächsten Zeile wird der Ereignishandler „before-page“ über die Sammlungsoption „BeforePageSavingEventHandlers“ mit dem Konvertierungsauftrag „verbunden“.

Jetzt müssen Sie nur noch die Konvertierung in PDF mit der Methode „SaveAsPdf()“ des Dokuments durchführen.

Abschluss

In diesem Artikel haben wir die wichtigsten Punkte des ereignisbasierten Ansatzes in der Programmierung untersucht, die direkte Methode zum Ändern von Seiten eines XPS-Dokuments untersucht und eine fortgeschrittenere und ausgefeiltere Technik kennengelernt, um während des Vorgangs wiederholende Änderungen an allen Ausgabeseiten vorzunehmen Konvertierungsprozess am Beispiel des Einfügens von Navigations-Hyperlinks.

Die vollständigen Beispiele finden Sie in unserem Beispielprojekt.