Σχόλια

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

Τα σχόλια στο 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 του viewer.
  • Created, Changed, Deleted, και Properties είναι παγκόσμιες συναρτήσεις που εντοπίζονται με όνομα: το αναγνωριστικό του viewer προστίθεται ως πρόθεμα στο συμβάν. Για το viewer στο #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 envelope (αυτό που καταναλώνει το widget)
GetAnnotationXml()Μορφή XML

Viewer αντικατοπτρίζει τις λειτουργίες φόρτωσης/ανάγνωσης έναντι μιας συνεδρίας: LoadAnnotationData(token, manager) ή LoadAnnotationData(token, encodedData) (το Base64 envelope από 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");
});

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

Σχόλια εικόνας σε εξαγωγή από εσωτερικό διακομιστή εμφανίζει «Αποκλεισμένη εικόνα»

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

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

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

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