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