Σχόλια

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

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

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

Ενεργοποίηση της διεπαφής Σχολίων

Το Σχόλιο είναι ένα μοντέλο του 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: '/',
        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()Λαμβάνει το προαιρετικό slot επέκτασης κεφαλίδας για ελέγχους που ανήκουν στον 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 περιτύλιγμα (αυτό που καταναλώνει το widget)
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");
});

Οι εξαγωγές χρησιμοποιούν τον ίδιο καυστήρα με την απόδοση στην οθόνη, έτσι ό,τι βλέπουν οι χρήστες είναι ό,τι περιέχει το αρχείο — εκτός από τις εικόνες σχολιασμών, που περιγράφονται παρακάτω.

Σχόλια εικόνας σε εξαγωγή από εσωτερικό κεντρικό υπολογιστή ως "Image blocked"

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

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

Όταν ο διακομιστής ανακτά μια εικόνα για ενσωμάτωση, απορρίπτει διευθύνσεις που οδηγούν πίσω σε ιδιωτικά δίκτυα: 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 εικόνας επιλύεται σε σχέση με τον κεντρικό υπολογιστή του τρέχοντος αιτήματος, έτσι ώστε στο localhost, σε εσωτερικό διακομιστή ή σε οποιονδήποτε ιστότοπο που προσεγγίζεται μέσω ιδιωτικής διεύθυνσης, η εικόνα εμφανίζεται στον προβολέα και η εξαγωγή περιέχει το placeholder αντί αυτού. Αυτό είναι η λειτουργία της προστασίας, όχι αποτυχία απόδοσης. Εάν οι εξαγωγές πρέπει να περιλαμβάνουν την εικόνα, σερβίρετέ την από κεντρικό υπολογιστή με δημόσια διεύθυνση και χρησιμοποιήστε απόλυτη URL. Ένα όνομα κεντρικού υπολογιστή που δεν μπορεί να επιλυθεί απορρίπτεται με τον ίδιο τρόπο· οποιαδήποτε άλλη αποτυχία λήψης εμφανίζει την URL και το μήνυμα σφάλματος σε κόκκινο χρώμα εκεί όπου θα ήταν η εικόνα.

Διαδικασία διατήρησης

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

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

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

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

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

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

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