Σημειώσεις

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

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

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

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

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

Εκδώστε τα αρχεία σχολίων μαζί με τα αρχεία του viewer. Ελέγχονται από άδεια, έτσι οι ετικέτες τους εμφανίζονται μόνο όταν η δυνατότητα χορηγείται. Στο MVC 5, δημιουργήστε τις ετικέτες στον ελεγκτή (οι προβολές δεν έχουν @inject):

csharp
public class ViewerController : Controller
{
    public ActionResult Index()
    {
        var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
        ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
        {
            IncludeViewerCss     = true,
            IncludeAnnotationCss = true    // jquery-ui.min.css + annotationBar.css
        });
        ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
        {
            IncludeJQuery            = true,
            IncludeViewerScripts     = true,
            IncludeAnnotationScripts = true,  // jquery-ui, raphael.js, annotation.js
            IncludeAnnotationBar     = true   // η ενσωματωμένη κορδέλα σχολιασμού
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

Διατηρήστε τη πλήρη σύνθεση του 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>

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

html
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
    var annBar = null;
    var currentToken = '';

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

    @if ((bool)ViewBag.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: function () { return { token: currentToken }; },
        onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

Χωρίς τη δυνατότητα, το ReferenceScripts παραλείπει το script της Ribbon, έτσι το if στο διακομιστή αποτρέπει μια μη προστατευμένη κλήση doconutAnnotationBar(...) από το να σπάσει τη σελίδα. Στα Web Forms, γράψτε την ίδια προστασία ως <% if (IsAnnotationEnabled) { %> … <% } %>.

Η αποθήκευση από τη Ribbon στέλνει τα δεδομένα στο DocImage.axd (AnnSave), το οποίο τα αποθηκεύει στη συνεδρία εγγράφου ανά σελίδα. Η φόρτωση (AnnLoad) γίνεται αυτόματα όταν μια σελίδα με σχόλια αποδίδεται.

Ανοίξτε και κλείστε τη Ribbon από τη δική σας γραμμή εργαλείων με annBar.open() και annBar.close(). Το δημόσιο API της:

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

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

Δύο είδη 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
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<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));

    // Φόρτωση στη συνεδρία - ο προβολέας τα ανακτά και ο αποτυπωτής τα ενσωματώνει
    // image/PDF εξαγωγές.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

Τύποι σχολιασμών

Όλοι οι τύποι βρίσκονται στο 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)Κωδικοποιημένα δεδομένα σχολιασμού — το φάκελο που καταναλώνει το widget
GetAnnotationXml()Μορφή XML

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

Εξαγωγή με ενσωματωμένους σχολιασμούς

csharp
// PDF όλων των σελίδων με τις σημειώσεις αποτυπωμένες πάνω τους
public async Task<ActionResult> ExportPdf(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", "export.pdf");
}

// Ή ένα ZIP με PNG ανά σελίδα
public async Task<ActionResult> ExportPngZip(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return 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. Ανοίξτε το έγγραφο και αποκτήστε το διακριτικό του.
  2. Φορτώστε το προηγουμένως αποθηκευμένο XML ή κωδικοποιημένα δεδομένα σε αυτό το διακριτικό.
  3. Επιτρέψτε στο widget να διαβάσει και να επεξεργαστεί τα σχόλια της συνεδρίας.
  4. Ανακτήστε XML με GetAnnotationXML(token) όταν η εφαρμογή σας αποφασίσει να αποθηκεύσει.
  5. Εξάγετε PDF ή PNG όταν απαιτείται ένα επίπεδο παραδοτέο.
  6. Κλείστε τη συνεδρία του εγγράφου.

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

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

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

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

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

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