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