Προβολέας
Η κύρια κλάση προβολής εγγράφων
Viewer (namespace Doconut) είναι το δημόσιο σημείο εισόδου για το άνοιγμα εγγράφων από Razor pages, MVC controllers, Blazor components ή minimal APIs. Είναι sealed, καταχωρημένο ως transient υπηρεσία από AddDoconut(), και επιλύεται μέσω constructor injection — ποτέ μην το δημιουργείτε απευθείας.
Η προηγούμενη βιβλιοθήκη .NET Standard παρείχε έναν δημόσιο κατασκευαστή που έπαιρνε τη μνήμη cache, το HTTP context accessor και μία ή περισσότερες διαδρομές αδειών. Αυτός ο κατασκευαστής δεν υπάρχει πια· το service graph παρέχει αυτές τις εξαρτήσεις.
Viewer δεν διατηρεί κατάσταση ανά αίτημα και σκόπιμα δεν υλοποιεί IDisposable: οι συνεδρίες εγγράφων ζουν ανεξάρτητα στην session cache, έτσι η διαγραφή της υπηρεσίας δεν μπορεί ποτέ να κλείσει ένα ανοιχτό έγγραφο (δείτε Βασικές Έννοιες → Πώς Λειτουργεί ο Προβολέας).
OpenDocumentAsync
Ανοίγει ένα έγγραφο και επιστρέφει το token συνεδρίας που χρησιμοποιεί το widget του πελάτη για όλες τις επόμενες αιτήσεις. Κάθε άνοιγμα είναι ασύγχρονο — δεν υπάρχει συγχρονικό OpenDocument.
| Υπερφόρτωση | Χρήση όταν |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Άνοιγμα από δίσκο με αυτόματη ανίχνευση μορφής και την προεπιλεγμένη ρύθμιση της μορφής |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Χρειάζεστε επιλογές απόδοσης ανά μορφή (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Το έγγραφο δεν είναι αρχείο στον δίσκο (ανέβασμα, βάση δεδομένων, blob). fileInfo πρέπει να περιέχει τη σωστή επέκταση — καθορίζει την ανίχνευση μορφής |
// Απλό άνοιγμα
string token = await viewer.OpenDocumentAsync(path);
// Με διαμόρφωση και επιλογές ανά μορφή
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// Από μια μεταφόρτωση
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));Εξαιρέσεις προς διαχείριση:
LicenseException— μια βρεθείσα άδεια απορρίπτεται (το μήνυμα περιέχει τον λόγο απόρριψης), ή η μορφή χρειάζεται δυνατότητα plugin που δεν παρέχεται πλέον. Η λήξη του ημερολογίου χωρίς μήνυμα απόρριψης μετατρέπεται σε απόδοση με υδατογράφημα αντί για εξαίρεση.FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— το περιεχόμενο του αρχείου είναι κατεστραμμένο ή δεν ταιριάζει με την επέκτασή του.
CloseDocument
void CloseDocument(string token)Αφαιρεί τη συνεδρία από την cache (αποδεσμεύει τη μηχανή εγγράφου αμέσως), διαγράφει το σήμα ασφαλείας και ανακαλεί την άδεια πρόσβασης. Προαιρετικό — η κυλιόμενη λήξη εκτελεί την ίδια εκκαθάριση — αλλά συνιστάται για μεγάλα έγγραφα.
GetPageCount
int GetPageCount(string token)Συνολικές σελίδες της ανοιχτής συνεδρίας. Ρίχνει InvalidOperationException (Document session not found. Please re-open document.) εάν το token είναι άγνωστο ή έχει λήξει, και ArgumentException για κενό token.
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)Το προεπιλεγμένο μέγεθος σελίδας του εγγράφου σε απόδοση 100 % ζουμ — ο χώρος συντεταγμένων για σημειώσεις που δημιουργούνται με κώδικα. page γίνεται αποδεκτό για συμβατότητα· το αποτέλεσμα είναι το προεπιλεγμένο του εγγράφου. Ρίχνει InvalidOperationException (Document session not found. Please re-open document.) εάν το token είναι άγνωστο ή έχει λήξει, και ArgumentException για κενό token.
ΛήψηΟνομάτωνΦύλλων
IReadOnlyList<string> GetWorksheetNames(string token)Επιστρέφει τα ονόματα των φύλλων εργασίας ενός ανοιχτού υπολογιστικού φύλλου, με τη σειρά του βιβλίου εργασίας, ή μια κενή λίστα όταν το ανοιχτό έγγραφο δεν είναι υπολογιστικό φύλλο.
Μόνο τα εμφανιζόμενα φύλλα εργασίας καταχωρούνται: κρυφά και κενά φύλλα εξαιρούνται, και όταν ExcelConfig.SheetNames περιορίζει την απόδοση, εμφανίζονται μόνο αυτά τα φύλλα. Ένα φύλλο εργασίας δεν είναι πάντα μία σελίδα — ένα πολύ μεγάλο μπορεί να εμφανίζεται σε πολλές σελίδες. Εναγείρει InvalidOperationException (Document session not found. Please re-open document.) εάν το διακριτικό είναι άγνωστο ή έχει λήξει, και ArgumentException για κενό διακριτικό.
Προστέθηκε στην έκδοση 26.9.0.
Σημαίες Δυνατοτήτων
| Μέλος | Σημασία |
|---|---|
bool IsSearchEnabled | Η τρέχουσα άδεια παρέχει Search |
bool IsAnnotationEnabled | Η τρέχουσα άδεια παρέχει Annotation |
Χρησιμοποιήστε τα σε μια Razor view για να αποδώσετε ένα αδειοδοτημένο Ribbon μόνο όταν ο διακομιστής θα το εξυπηρετήσει πραγματικά — δείτε Γρήγορη Εκκίνηση.
DocOptions
Επιλογές ανεξάρτητες από τη μορφή, ανά άνοιγμα (namespace Doconut):
| Τύπος | Ιδιότητα | Προεπιλογή | Περιγραφή |
|---|---|---|---|
string | Password | "" | Κωδικός πρόσβασης για προστατευμένα έγγραφα (αντιγράφεται αυτόματα στη διαμόρφωση μορφής). |
int | ImageResolution | 0 | Παρωχημένο. Διατηρείται μόνο για συμβατότητα — ορίστε ImageResolution στη διαμόρφωση μορφής αντί αυτού. |
string | Watermark | "" | Προσαρμοσμένο κείμενο υδατογράφησης σχεδιασμένο στις αποδομένες σελίδες. Συμβολοσειρά μορφής: "^Text~Color~FontSize~FontName~Opacity~Angle", π.χ. "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | Ολιστική λήξη συνεδρίας σε λεπτά. |
bool | IsSecured | true | Δεν επιβάλλεται επί του παρόντος — δεσμευμένο. Η δέσμευση διακριτικού ελέγχεται παγκοσμίως από DoconutOptions.UnsafeMode (δείτε Βασικές Έννοιες → Συνεδρίες & Ασφάλεια). |
Η κλάση εκθέτει επίσης εξειδικευμένες ιδιότητες που είναι σκόπιμα εκτός της κανονικής ροής προβολής ενός μόνο κεντρικού υπολογιστή:
| Τύπος | Ιδιότητα | Προεπιλογή | Περιγραφή |
|---|---|---|---|
bool | IsWebFarm | false | Παρωχημένο — δεν έχει καμία επίδραση. Δημοσιεύστε το έγγραφο με DistributedDocumentPublisher.PublishAsync (ή IDistributedPublishQueue.EnqueueAsync) και ορίστε FileShareConfig.RootPath αντ' αυτού. Σημειώστε τη χρήση κεφαλαίων — η προηγούμενη βιβλιοθήκη το έγραφε ως IsWebfarm. |
string | WebFarmPath | "" | Παρωχημένο — δεν έχει καμία επίδραση. Χρησιμοποιήστε FileShareConfig.RootPath, όπως περιγράφεται στις Κατανεμημένες Αναπτύξεις. Πρώην γραμμένο ως WebfarmPath. |
bool | EditMode | false | Δεσμευμένο για ξεχωριστή διανεμημένη ροή επεξεργασίας· αφήστε το false για τον τυπικό προβολέα. |
Προσαρμοσμένο υδατογράφημα
DocOptions.Watermark χρησιμοποιεί έξι πεδία χωρισμένα με tilde. Ένα προαιρετικό αρχικό ^ ζητά τη διάταξη σε όλες τις γωνίες:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Πεδίο | Παράδειγμα | Σημασία |
|---|---|---|
Leading ^ | ^ | Προαιρετική διάταξη σε όλες τις γωνίες. Χωρίς αυτό, χρησιμοποιείται η κανονική τοποθέτηση υδατογραφήματος. |
| Text | Confidential | Κείμενο που αποδίδεται σε κάθε σελίδα. Δεν πρέπει να είναι κενό. |
| Color | Red | Ονομαστικό χρώμα που κατανοείται από το επίπεδο σχεδίασης. |
| FontSize | 24 | Μέγεθος γραμματοσειράς· εσφαλμένη αριθμητική είσοδος επανέρχεται στην προεπιλογή του αποδοχέα. |
| FontName | Verdana | Ζητούμενη οικογένεια γραμματοσειράς. Βεβαιωθείτε ότι είναι εγκατεστημένη στο περιβάλλον ανάπτυξης. |
| Opacity | 80 | Τιμή byte από 0 έως 255. Πρέπει να αναλυθεί επιτυχώς. |
| Angle | -45 | Γωνία περιστροφής σε μοίρες· εσφαλμένη αριθμητική είσοδος επανέρχεται στην προεπιλογή. |
Ο αναλυτής αναμένει ακριβώς έξι πεδία μετά το προαιρετικό ^. Μια μη έγκυρη ορισμός αντικαθίσταται από το ορατό fallback του SDK Invalid Watermark αντί να εξαφανιστεί σιωπηλά.
Απόφαση άδειας
| Κατάσταση άδειας | Προσαρμοσμένη τιμή παρεχόμενη | Αποτέλεσμα απόδοσης |
|---|---|---|
| Έγκυρη πληρωμένη άδεια προβολέα | Όχι | Καθαρή σελίδα |
| Έγκυρη πληρωμένη άδεια προβολέα | Ναι | Προσαρμοσμένο υδατογράφημα |
| Ενεργός προσωρινός/δείγματος βασικός προβολέας | Όχι | Καθαρή σελίδα βασικού προβολέα |
| Ενεργός προσωρινός/δείγματος βασικός προβολέας | Ναι | Προσαρμοσμένο υδατογράφημα όταν εφαρμόζεται η καθαρή διαδρομή του βασικού προβολέα |
| Άδεια που λείπει, απορρίπτεται, έχει λήξει, λάθος έκδοσης ή άκυρου τομέα | Οποιαδήποτε | Υδατογράφημα επιβολής/αξιολόγησης· η προσαρμοσμένη τιμή δεν το παρακάμπτει |
| Πρόσθετο υπό κανόνες αξιολόγησης | Οποιαδήποτε | Υδατογράφημα αξιολόγησης |
Η ίδια απόφαση εφαρμόζεται στις εικόνες σελίδων που σερβίρονται και στις εξαγωγές σχολίων. Η έξοδος Animated GIF σφραγίζεται καρέ‑καρέ. Έτσι, ένα προσαρμοσμένο υδατογράφημα είναι χαρακτηριστικό εφαρμογής με άδεια, όχι τρόπος αντικατάστασης ή καταστολής του υδατογραφήματος αξιολόγησης.
API Σχολίων
Φόρτωση και εξαγωγή σχολίων στην πλευρά του διακομιστή. Η πλήρης περιήγηση βρίσκεται στα Guides → Annotations· η επιφάνεια είναι:
| Μέλος | Σκοπός |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Διαχειριστής δεσμευμένος στις διαστάσεις σελίδας της ανοιχτής συνεδρίας |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Διαχειριστής με ρητές διαστάσεις σελίδας |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Διαχειριστής ανεξάρτητος από τη συνεδρία |
void LoadAnnotationData(string token, AnnotationManager manager) | Φόρτωση σχολίων που δημιουργήθηκαν σε C# στη συνεδρία |
void LoadAnnotationData(string token, string annotationData) | Φόρτωση σχολίων από την κωδικοποιημένη σελίδα/περιβάλλον Base64 που επιστρέφεται από AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Φόρτωση σχολίων από XML |
XmlDocument GetAnnotationXML(string token) | Εξαγωγή των σχολίων της συνεδρίας ως XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF με ενσωματωμένα σχόλια |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Ένα PNG ανά σελίδα, σχόλια ενσωματωμένα, γραμμένο στο directoryPath (δημιουργείται αν λείπει)· επιστρέφει τον αριθμό των εικόνων που γράφτηκαν |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP με PNG ανά σελίδα με ενσωματωμένα σχόλια |
Κάθε ένα από αυτά λαμβάνει το διακριτικό συνεδρίας. Η μορφή GetAnnotationManager(pageWidth, pageHeight) της προηγούμενης βιβλιοθήκης, χωρίς συνεδρία, παραμένει για τη δημιουργία σχολίων εκτός συνεδρίας, αλλά η φόρτωσή τους απαιτεί ακόμη διακριτικό.
Μεταδεδομένα DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Η μέθοδος υπάρχει για ευθυγράμμιση API, αλλά αυτό το πακέτο δεν μπορεί να παρέχει τεχνικές ετικέτες DICOM: ο αναγνώστης μεταδεδομένων διανέμεται μόνο με έκδοση .NET 8. Επιστρέφει null για συνεδρίες DICOM και μη‑DICOM· σε συνεδρία DICOM γράφει επίσης μια εφάπαξ προειδοποίηση που εξηγεί τον περιορισμό της πλατφόρμας. Η απόδοση σελίδας, πλαισίου και animation παραμένει υποστηριζόμενη.
Βοηθοί πόρων — ReferenceCss / ReferenceScripts
Εκδώστε τις ετικέτες <link>/<script> για τους ενσωματωμένους πόρους που σερβίρονται από UseDoconutResources(), με τη σωστή σειρά εξαρτήσεων. Τα πακέτα για λειτουργίες υπό άδεια όπως η αναζήτηση και τα σχόλια εκδίδονται μόνο όταν η άδεια τις ενεργοποιεί, διατηρώντας το UI του πελάτη συνεπές με τη συμπεριφορά του διακομιστή.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + προβολέας + αναζήτηση + σχόλιο
string ReferenceScripts(ScriptConfig? config = null)CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (υπό άδεια αναζήτησης), IncludeAnnotationCss (υπό άδεια σχολίων).
ScriptConfig flags: IncludeJQuery (απαιτείται από όλα τα άλλα), IncludeBootstrap, IncludeViewerScripts (πυρήνας: docViewer.js + splitter + links), IncludeSearchScripts και IncludeSearchBar (υπό άδεια αναζήτησης), IncludeAnnotationScripts και IncludeAnnotationBar (υπό άδεια σχολίων), EmitFeatureFlags (προεπιλογή true: γράφει επίσης ένα ενσωματωμένο script window.Doconut.features = { search, annotation, editor }· ορίστε το σε false υπό Content-Security-Policy που αποκλείει ενσωματωμένα script).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))Αυτοί οι βοηθοί είναι ο υποστηριζόμενος τρόπος παροχής των πόρων του προγράμματος περιήγησης. Οι εφαρμογές που αντιγράψαν το docViewer.js, documentLinks.js και docViewer.UI.js στο wwwroot πρέπει να αφαιρέσουν αυτά τα αντίγραφα μόλις η σελίδα αποδοθεί από τις εκπεμπόμενες ετικέτες.
Ήταν αυτή η σελίδα χρήσιμη;