Σημειώσεις
Προσθέστε υποστήριξη σχολίων στον προβολέα
Τα Σχόλια στο Doconut λειτουργούν σε δύο κατευθύνσεις: οι χρήστες τα σχεδιάζουν στο widget του προγράμματος περιήγησης και ο διακομιστής τα διατηρεί ανά σελίδα, ή ο κώδικάς σας τα δημιουργεί και τα φορτώνει σε μια ανοιχτή συνεδρία. Σε κάθε περίπτωση εμφανίζονται στις σελίδες και μπορούν να ενσωματωθούν σε εξαγωγές PDF ή PNG.
Η υποστήριξη Σχολίων ελέγχεται από τη δυνατότητα άδειας Annotation (χάρηται αυτόματα με ενεργή προσωρινή άδεια).
Ενεργοποίηση του UI σχολίων
Το Σχόλιο είναι μια μονάδα του Viewer, όχι μια ανεξάρτητη γραμμή εργαλείων. Η σελίδα πρέπει να περιλαμβάνει τους πόρους του Viewer, τη γραμμή εργαλείων του Viewer, το mount του Viewer και ένα αρχικοποιημένο objViewer· η Ribbon Σχολίων στη συνέχεια τοποθετείται και συνδέεται με το ίδιο παράδειγμα.
Εκδώστε τα αρχεία σχολίων μαζί με τα αρχεία του viewer. Ελέγχονται από άδεια, έτσι οι ετικέτες τους εμφανίζονται μόνο όταν η δυνατότητα χορηγείται. Στο MVC 5, δημιουργήστε τις ετικέτες στον ελεγκτή (οι προβολές δεν έχουν @inject):
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:
<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.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 της:
| Method | Purpose |
|---|---|
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):
// 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).
Εξαγωγή με ενσωματωμένους σχολιασμούς
// 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 και το μήνυμα σφάλματος σε κόκκινο χρώμα όπου θα ήταν η εικόνα.
Ροή εργασίας διατήρησης
- Ανοίξτε το έγγραφο και αποκτήστε το διακριτικό του.
- Φορτώστε το προηγουμένως αποθηκευμένο XML ή κωδικοποιημένα δεδομένα σε αυτό το διακριτικό.
- Επιτρέψτε στο widget να διαβάσει και να επεξεργαστεί τα σχόλια της συνεδρίας.
- Ανακτήστε XML με
GetAnnotationXML(token)όταν η εφαρμογή σας αποφασίσει να αποθηκεύσει. - Εξάγετε PDF ή PNG όταν απαιτείται ένα επίπεδο παραδοτέο.
- Κλείστε τη συνεδρία του εγγράφου.
Μην χρησιμοποιείτε το διακριτικό του προβολέα ως μόνιμο αναγνωριστικό σχολίου — λήγει με τη συνεδρία, και μια επαναφορά της ομάδας εφαρμογών τερματίζει κάθε συνεδρία σε έναν μοναδικό διακομιστή. Αποθηκεύστε τα δεδομένα σχολίων σε σχέση με το δικό σας έγγραφο και τα αναγνωριστικά έκδοσης.
Σημειώσεις ασφαλείας και απόδοσης
- Τα αιτήματα σχολίων χρησιμοποιούν την ίδια ασφάλεια συνεδρίας και διακριτικού όπως τα αιτήματα σελίδας.
- Επικυρώστε και ελέγξτε οποιαδήποτε URL εικόνας που παρέχεται από τον χρήστη.
- Μεγάλα ελεύθερα φορτία και εξαγωγές υψηλής ανάλυσης αυξάνουν τη χρήση μνήμης· δοκιμάστε ρεαλιστικά έγγραφα και τιμές ζουμ.
Επίλυση προβλημάτων
| Σύμπτωμα | Έλεγχος |
|---|---|
| Η κορδέλα σχολίων λείπει | Η δυνατότητα Annotation και οι τέσσερις σημαίες CSS/σκριπτ σχολίων |
| Η αποθήκευση αναφέρει σφάλμα | Λήξη διακριτικού ή συνεδρίας, και το BasePath του widget |
ctlDoc_Created (ή άλλη λειτουργία συμβάντος) δεν εκτελείται | Το όνομα της λειτουργίας: id προβολέα + _ + συμβάν, ως καθολική λειτουργία |
| Τα σχόλια C# δεν εμφανίζονται | Οι αριθμοί σελίδων είναι από το 1, και τα δεδομένα φορτώθηκαν στο ενεργό διακριτικό |
| Ένα σχόλιο εικόνας εμφανίζεται στην οθόνη αλλά όχι στην εξαγωγή | Ο κεντρικός υπολογιστής της εικόνας έχει ιδιωτική ή loopback διεύθυνση — δείτε παραπάνω |
| Ένα ξανανοιγμένο έγγραφο δεν έχει σχόλια | Αποθηκεύστε XML ή δεδομένα εκτός της συνεδρίας του προβολέα, έπειτα φορτώστε τα στο νέο διακριτικό |
Ήταν αυτή η σελίδα χρήσιμη;