Σχόλια

Προσθήκη υποστήριξης σχολίων στον προβολέα

Τα σχόλια στο Doconut λειτουργούν σε δύο κατευθύνσεις: οι χρήστες τα σχεδιάζουν στο widget του προγράμματος περιήγησης και ο διακομιστής τα αποθηκεύει ανά σελίδα, ή ο κώδικάς σας τα δημιουργεί προγραμματιστικά και τα φορτώνει σε μια ανοιχτή συνεδρία. Σε κάθε περίπτωση εμφανίζονται στις σελίδες και μπορούν να ενσωματωθούν σε εξαγωγές PDF/PNG.

Η υποστήριξη σχολίων ελέγχεται από τη δυνατότητα άδειας Annotation (χάρη αυτόματα υπό ενεργή προσωρινή άδεια).

Ενεργοποίηση του UI σχολίων

Το σχόλιο είναι ένα μοντέλο Viewer, όχι μια αυτόνομη γραμμή εργαλείων. Η πλήρης σελίδα πρέπει να περιλαμβάνει τους πόρους Viewer, τη γραμμή εργαλείων Viewer, το mount του Viewer και το αρχικοποιημένο objViewer· η Ribbon Σχολίων στη συνέχεια τοποθετείται και συνδέεται με το ίδιο παράδειγμα.

Εκδώστε τα πακέτα σχολίων μαζί με τα πακέτα του viewer — είναι ελεγχόμενα από άδεια, έτσι οι ετικέτες εμφανίζονται μόνο όταν η δυνατότητα είναι διαθέσιμη:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss     = true,
    IncludeAnnotationCss = true   // jquery-ui.min.css + annotationBar.css
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeViewerScripts      = true,
    IncludeAnnotationScripts  = true, // jquery-ui, raphael.js, annotation.js
    IncludeAnnotationBar      = true  // η ενσωματωμένη ταινία σχολιασμού
}))

Διατηρήστε τη πλήρη σύνθεση Viewer ορατή στο markup:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Έλεγχοι προβολέα, συμπεριλαμβανομένου του κουμπιού που ανοίγει Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Το πακέτο Σχολίων δημιουργεί το DOM της Ribbon μέσα στο annBarMount· δεν χρειάζεται να αντιγράψετε τα κουμπιά ή το markup του διαλόγου. Αρχικοποιήστε πρώτα το docViewer, έπειτα δημιουργήστε τη Ribbon μόνο όταν ο διακομιστής επιβεβαιώσει ότι το Σχόλιο είναι αδειοδοτημένο:

html
<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: 'doconut',
        ResPath: 'doconut-res/images',
        onAnnLoaded:    () => annBar?.handleAnnLoaded(),
        onAnnSaved:     () => annBar?.handleAnnSaved(),
        onAnnSaveError: () => annBar?.handleAnnSaveError(),
        onAnnClosed:    () => annBar?.handleAnnClosed(),
        onError:        (message) => console.error('Viewer error:', message)
    });

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onStatus: (message) => console.log(message),
        onToast: (message, type) => console.log(type, message),
        onLayout: () => requestAnimationFrame(() => objViewer.Refit())
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

Χωρίς τη δυνατότητα, το ReferenceScripts παραλείπει το script της Ribbon, έτσι το if στο διακομιστή διατηρεί μια μη προστατευμένη κλήση doconutAnnotationBar(...) ώστε να μην σπάσει η σελίδα.

Η αποθήκευση από τη Ribbon στέλνει δεδομένα μέσω του middleware (AnnSave), το οποίο τα αποθηκεύει στη συνεδρία εγγράφου ανά σελίδα. Η φόρτωση (AnnLoad) συμβαίνει αυτόματα όταν μια σελίδα με σχόλια αποδίδεται. Τα τέσσερα callbacks onAnn* διατηρούν τη Ribbon συγχρονισμένη με τον κύκλο ζωής του viewer.

Ανοίξτε και κλείστε το από οποιαδήποτε γραμμή εργαλείων Viewer που ανήκει στον κεντρικό (host):

javascript
annBar.open();
annBar.close();

Το δημόσιο API της Ribbon είναι:

ΜέθοδοςΣκοπός
attach(objViewer)Συνδέει τη Ribbon με τον αρχικοποιημένο viewer· απαιτείται μία φορά
open() / close()Είσοδος ή έξοδος από την επεξεργασία σχολίων
reset()Επιστρέφει τη Ribbon στην κλειστή, μη-επεξεργαστική κατάσταση
isOpen() / annotating()Ανάγνωση της κατάστασης της Ribbon / της κατάστασης επεξεργασίας σχολίων του viewer
reopenEditable()Επαναφόρτωση των σχολίων της τρέχουσας σελίδας ως επεξεργάσιμα αντικείμενα
updateActionState()Ανανέωση της διαθεσιμότητας των ελέγχων αποθήκευσης/διαγραφής μετά από αλλαγές του host
headerSlot()Λήψη του προαιρετικού υποδοχέα επέκτασης κεφαλίδας για ελέγχους που ανήκουν στον host

Τα onStatus, onToast, onLayout, onEditStart και onEditEnd είναι προαιρετικά callbacks του host. Το αντικείμενο endpoints μπορεί επιπλέον να παρέχει exportPdf, exportPng, imageUpload και imageList· οι έλεγχοι χωρίς ρυθμισμένο endpoint παραμένουν κρυμμένοι. Για τη συνδυασμένη ακολουθία εκκίνησης Viewer, Search και Annotation, δείτε Γρήγορη Εκκίνηση.

Το πακέτο σχολίων προσθέτει τα εργαλεία δημιουργίας του προγράμματος περιήγησης, αλλά τα δεδομένα ανήκουν ακόμη στη συνεδρία εγγράφου στο διακομιστή που προσδιορίζεται από το token. Η επαναφορά του πηγής δημιουργεί μια νέα συνεδρία· διατηρήστε το XML ή το κωδικοποιημένο φάκελο σχολίων στην εφαρμογή σας εάν τα σχόλια πρέπει να παραμείνουν μετά τη διάρκεια της συνεδρίας.

Δύο είδη callback, συνδεδεμένα με δύο τρόπους

Ο κώδικας σημειώσεων χρησιμοποιεί δύο στυλ callback, και το καθένα αποτυγχάνει σιωπηλά όταν συνδεθεί με τον αντίθετο τρόπο:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed είναι επιλογές του docViewer({...}), όπως κάθε callback προβολέα.
  • Created, Changed, Deleted, και Properties είναι καθολικές συναρτήσεις που βρίσκονται με όνομα: το αναγνωριστικό του προβολέα προστίθεται ως πρόθεμα στο γεγονός. Για τον προβολέα στο #div_ctlDoc το αναγνωριστικό είναι ctlDoc, έτσι οι συναρτήσεις είναι ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted, και ctlDoc_Properties. Μια λανθασμένη ή μετονομασμένη συνάρτηση απλώς δεν καλείται ποτέ.

SaveAnnotations() δεν επιστρέφει αν αποθηκεύτηκε: το αποτέλεσμα φτάνει μέσω onAnnSaved ή onAnnSaveError. Ο κώδικας που διαβάζει την τιμή επιστροφής του δεν καθαρίζει ποτέ τη σημαία «αποθηκευμένων αλλαγών».

Δημιουργία σημειώσεων σε C#

Πάρτε έναν διαχειριστή δεσμευμένο στη ανοιχτή συνεδρία, προσθέστε σημειώσεις και φορτώστε τες (με using Doconut.Annotations; για τους τύπους και using System.Drawing; για Rectangle/Color):

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Δεσμευμένο στις διαστάσεις σελίδας της ανοιχτής συνεδρίας
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // Μία σφραγίδα ανά σελίδα
    for (int page = 1; page <= pageCount; page++)
    {
        manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
            $"PAGE {page}", 28, 4, Color.Maroon)
        {
            Opacity = 60,
            Rotate  = -8
        });
    }

    manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
        "Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));

    // Φόρτωση στη συνεδρία — το widget τα ανακτά μέσω AnnLoad και το
    // ο renderer τα ενσωματώνει στις εξαγωγές εικόνας/PDF.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Τύποι Σημειώσεων

Όλοι οι τύποι βρίσκονται στο Doconut.Annotations και κληρονομούν από το BaseAnnotation (αριθμός σελίδας + περιοριστικό Rectangle):

ΤύποςΣημειώσεις
StampAnnotationΣφραγίδα κειμένου με μέγεθος γραμματοσειράς, περιθώριο, χρώμα· υποστηρίζει Opacity, Rotate
NoteAnnotationΣημείωμα αυτοκόλλητο με κείμενο, χρώμα φόντου, μέγεθος γραμματοσειράς, TitleColor
RectangleAnnotationΧρώματα περιγράμματος + γεμίσματος, Title/ShowTitle
CircleAnnotationΠεριθώριο + γέμισμα, ShowBorder
EllipseAnnotationΠεριθώριο + γέμισμα, ShowBorder
TriangleAnnotationΧρώμα περιγράμματος, BackColor, ShowBorder
LineAnnotationΚατά ευθεία γραμμή με πάχος και χρώμα
ArrowAnnotationΓραμμή με κεφαλή βέλους· ρυθμιζόμενο Direction (τύπος ArrowDirection, σημεία πυξίδας, προεπιλογή E)
FreehandAnnotationΕλεύθερη γραμμή από κωδικοποιημένα σημεία FreehandData
ImageAnnotationΕικόνα από URL. Ένα σχετικό URL επιλύεται σε σχέση με τον κεντρικό διακομιστή της αίτησης όταν προστίθεται η σημείωση· ο διακομιστής κατεβάζει την εικόνα μόνο κατά τη φάση εξαγωγής — δείτε την σημείωση εξαγωγής παρακάτω

Το API του AnnotationManager

ΜέλοςΣκοπός
Add(BaseAnnotation)Τοποθετεί μια σημείωση στην ουρά
GetAnnotations() / GetAnnotations(int page)Επιθεωρεί τι κρατά ο διαχειριστής
ClearAnnotations() / ClearAnnotations(int page)Αφαιρεί όλα / ανά σελίδα
GetAnnotationData() / GetAnnotationData(int page)Κωδικοποιημένη συμβολοσειρά δεδομένων σημειώσεων — ένα Base64 φάκελο (αυτό που καταναλώνει το συστατικό)
GetAnnotationXml()Μορφή XML

Viewer αντιγράφει τις λειτουργίες φόρτωσης/ανάγνωσης έναντι μιας συνεδρίας: LoadAnnotationData(token, manager) ή LoadAnnotationData(token, encodedData) (το Base64 φάκελο από GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Εξαγωγή με ενσωματωμένες σημειώσεις

csharp
// PDF όλων των σελίδων με τις σημειώσεις ενσωματωμένες πάνω τους
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
    return Results.File(pdf, "application/pdf", "export.pdf");
});

// Ή ένα ZIP με PNG ανά σελίδα
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
    return Results.File(zip, "application/zip", "annotations-png.zip");
});

Σχόλια εικόνας σε εξαγωγή από intranet host ως "Image blocked"

Ο προβολέας και η εξαγωγή λαμβάνουν την εικόνα ενός ImageAnnotation από διαφορετικές θέσεις:

ΠεριβάλλονΠοιος κατεβάζει την εικόναΣε intranet ή host ανάπτυξης
Ο προβολέας στο πρόγραμμα περιήγησηςΤο πρόγραμμα περιήγησης του χρήστηΗ εικόνα εμφανίζεται
ExportAnnotationsToPdfAsync / …PngZipAsyncΟ διακομιστήςΈνα κόκκινο "Image blocked" σύμβολο κράτησης

Όταν ο διακομιστής ανακτά μια εικόνα για να την ενσωματώσει, απορρίπτει διευθύνσεις που οδηγούν πίσω σε ιδιωτικά δίκτυα: loopback (localhost, 127.0.0.1), 0.0.0.0, link‑local (169.254.x.x), τα ιδιωτικά εύρη 10.x, 172.16–31.x και 192.168.x, carrier‑grade NAT (100.64.0.0/10) και τις IPv6 link‑local και unique‑local διευθύνσεις. Αυτό προστατεύει τον διακομιστή από το να χρησιμοποιηθεί για πρόσβαση σε εσωτερικά συστήματα μέσω μιας προσαρμοσμένης URL εικόνας, και δεν υπάρχει διακόπτης για να το απενεργοποιήσετε.

Μια σχετική URL εικόνας επιλύεται σε σχέση με τον host του τρέχοντος αιτήματος, έτσι ώστε σε localhost, σε intranet διακομιστή, ή σε οποιονδήποτε ιστότοπο που προσεγγίζεται μέσω ιδιωτικής διεύθυνσης, η εικόνα εμφανίζεται στον προβολέα και η εξαγωγή περιέχει το σύμβολο κράτησης αντί αυτού. Αυτό είναι η λειτουργία της προστασίας, όχι αποτυχία απόδοσης. Εάν οι εξαγωγές πρέπει να περιλαμβάνουν την εικόνα, σερβίρετέ την από host με δημόσια διεύθυνση και χρησιμοποιήστε απόλυτη URL. Ένα όνομα host που δεν μπορεί να επιλυθεί απορρίπτεται με τον ίδιο τρόπο· οποιαδήποτε άλλη αποτυχία λήψης σχεδιάζει την URL και το μήνυμα σφάλματος σε κόκκινο εκεί που θα ήταν η εικόνα.

Ροή εργασίας διατήρησης

  1. Ανοίξτε το έγγραφο και αποκτήστε το token του.
  2. Φορτώστε το προηγουμένως αποθηκευμένο XML ή κωδικοποιημένα δεδομένα σε αυτό το token.
  3. Αφήστε το widget να διαβάσει και να επεξεργαστεί τα σχόλια της συνεδρίας.
  4. Ανακτήστε XML με GetAnnotationXML(token) όταν η εφαρμογή σας αποφασίσει να αποθηκεύσει.
  5. Εξάγετε PDF/PNG όταν απαιτείται ένα επίπεδο (flattened) παραδοτέο.
  6. Κλείστε τη συνεδρία του εγγράφου.

Μην χρησιμοποιείτε το αδιαφανές token του προβολέα ως μόνιμο αναγνωριστικό σχολίου. Συνδέστε τα αποθηκευμένα δεδομένα σχολίων με τα δικά σας αναγνωριστικά εγγράφου και έκδοσης.

Σημειώσεις ασφαλείας και απόδοσης

  • Τα αιτήματα σχολίων χρησιμοποιούν την ίδια ασφάλεια συνεδρίας/token όπως τα αιτήματα σελίδας.
  • Επικυρώστε και ελέγξτε οποιαδήποτε URL εικόνας που παρέχεται από χρήστη για να αποφύγετε την πλαστογραφία αιτημάτων στην πλευρά του διακομιστή.
  • Οι εξαγωγές εφαρμόζουν την ίδια απόφαση άδειας/προσαρμοσμένου υδατογραφήματος όπως η απόδοση σελίδας στην οθόνη.
  • Μεγάλα ελεύθερα payloads και εξαγωγές υψηλής ανάλυσης αυξάνουν τη χρήση μνήμης· δοκιμάστε ρεαλιστικά έγγραφα και τιμές ζουμ.

Επίλυση προβλημάτων

ΣύμπτωμαΈλεγχος
Η λωρίδα σχολίων λείπειΔυνατότητα Annotation και οι τέσσερις σημαίες CSS/σκριπτ σχολίων
Η κλήση επιστροφής αποθήκευσης αναφέρει σφάλμαΛήξη token/συνεδρίας και middleware BasePath
ctlDoc_Created (ή άλλη λειτουργία συμβάντος) δεν εκτελείται ποτέΤο όνομα της λειτουργίας: viewer id + _ + event, ως παγκόσμια λειτουργία
Τα σχόλια C# δεν εμφανίζονταιΗ αρίθμηση σελίδων ξεκινά από το 1 και τα δεδομένα φορτώθηκαν στο ενεργό token
Το σχόλιο εικόνας εμφανίζεται στην οθόνη αλλά όχι στην εξαγωγήΟ host της εικόνας έχει ιδιωτική ή loopback διεύθυνση — δείτε παραπάνω
Το ξανανοιγμένο έγγραφο δεν έχει σχόλιαΑποθηκεύστε XML/δεδομένα εκτός της συνεδρίας του προβολέα, έπειτα φορτώστε τα στο νέο token

Ήταν αυτή η σελίδα χρήσιμη;