Προβολέας

Η κύρια κλάση προβολής εγγράφων

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 πρέπει να περιέχει τη σωστή επέκταση — καθορίζει την ανίχνευση μορφής
csharp
// Απλό άνοιγμα
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

text
void CloseDocument(string token)

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

GetPageCount

text
int GetPageCount(string token)

Συνολικές σελίδες της ανοιχτής συνεδρίας. Ρίχνει InvalidOperationException (Document session not found. Please re-open document.) εάν το token είναι άγνωστο ή έχει λήξει, και ArgumentException για κενό token.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

Το προεπιλεγμένο μέγεθος σελίδας του εγγράφου σε απόδοση 100 % ζουμ — ο χώρος συντεταγμένων για σημειώσεις που δημιουργούνται με κώδικα. page γίνεται αποδεκτό για συμβατότητα· το αποτέλεσμα είναι το προεπιλεγμένο του εγγράφου. Ρίχνει InvalidOperationException (Document session not found. Please re-open document.) εάν το token είναι άγνωστο ή έχει λήξει, και ArgumentException για κενό token.

ΛήψηΟνομάτωνΦύλλων

text
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):

ΤύποςΙδιότηταΠροεπιλογήΠεριγραφή
stringPassword""Κωδικός πρόσβασης για προστατευμένα έγγραφα (αντιγράφεται αυτόματα στη διαμόρφωση μορφής).
intImageResolution0Παρωχημένο. Διατηρείται μόνο για συμβατότητα — ορίστε ImageResolution στη διαμόρφωση μορφής αντί αυτού.
stringWatermark""Προσαρμοσμένο κείμενο υδατογράφησης σχεδιασμένο στις αποδομένες σελίδες. Συμβολοσειρά μορφής: "^Text~Color~FontSize~FontName~Opacity~Angle", π.χ. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Ολιστική λήξη συνεδρίας σε λεπτά.
boolIsSecuredtrueΔεν επιβάλλεται επί του παρόντος — δεσμευμένο. Η δέσμευση διακριτικού ελέγχεται παγκοσμίως από DoconutOptions.UnsafeMode (δείτε Βασικές Έννοιες → Συνεδρίες & Ασφάλεια).

Η κλάση εκθέτει επίσης εξειδικευμένες ιδιότητες που είναι σκόπιμα εκτός της κανονικής ροής προβολής ενός μόνο κεντρικού υπολογιστή:

ΤύποςΙδιότηταΠροεπιλογήΠεριγραφή
boolIsWebFarmfalseΠαρωχημένο — δεν έχει καμία επίδραση. Δημοσιεύστε το έγγραφο με DistributedDocumentPublisher.PublishAsync (ή IDistributedPublishQueue.EnqueueAsync) και ορίστε FileShareConfig.RootPath αντ' αυτού. Σημειώστε τη χρήση κεφαλαίων — η προηγούμενη βιβλιοθήκη το έγραφε ως IsWebfarm.
stringWebFarmPath""Παρωχημένο — δεν έχει καμία επίδραση. Χρησιμοποιήστε FileShareConfig.RootPath, όπως περιγράφεται στις Κατανεμημένες Αναπτύξεις. Πρώην γραμμένο ως WebfarmPath.
boolEditModefalseΔεσμευμένο για ξεχωριστή διανεμημένη ροή επεξεργασίας· αφήστε το false για τον τυπικό προβολέα.

Προσαρμοσμένο υδατογράφημα

DocOptions.Watermark χρησιμοποιεί έξι πεδία χωρισμένα με tilde. Ένα προαιρετικό αρχικό ^ ζητά τη διάταξη σε όλες τις γωνίες:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
ΠεδίοΠαράδειγμαΣημασία
Leading ^^Προαιρετική διάταξη σε όλες τις γωνίες. Χωρίς αυτό, χρησιμοποιείται η κανονική τοποθέτηση υδατογραφήματος.
TextConfidentialΚείμενο που αποδίδεται σε κάθε σελίδα. Δεν πρέπει να είναι κενό.
ColorRedΟνομαστικό χρώμα που κατανοείται από το επίπεδο σχεδίασης.
FontSize24Μέγεθος γραμματοσειράς· εσφαλμένη αριθμητική είσοδος επανέρχεται στην προεπιλογή του αποδοχέα.
FontNameVerdanaΖητούμενη οικογένεια γραμματοσειράς. Βεβαιωθείτε ότι είναι εγκατεστημένη στο περιβάλλον ανάπτυξης.
Opacity80Τιμή 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

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

Η μέθοδος υπάρχει για ευθυγράμμιση API, αλλά αυτό το πακέτο δεν μπορεί να παρέχει τεχνικές ετικέτες DICOM: ο αναγνώστης μεταδεδομένων διανέμεται μόνο με έκδοση .NET 8. Επιστρέφει null για συνεδρίες DICOM και μη‑DICOM· σε συνεδρία DICOM γράφει επίσης μια εφάπαξ προειδοποίηση που εξηγεί τον περιορισμό της πλατφόρμας. Η απόδοση σελίδας, πλαισίου και animation παραμένει υποστηριζόμενη.

Βοηθοί πόρων — ReferenceCss / ReferenceScripts

Εκδώστε τις ετικέτες <link>/<script> για τους ενσωματωμένους πόρους που σερβίρονται από UseDoconutResources(), με τη σωστή σειρά εξαρτήσεων. Τα πακέτα για λειτουργίες υπό άδεια όπως η αναζήτηση και τα σχόλια εκδίδονται μόνο όταν η άδεια τις ενεργοποιεί, διατηρώντας το UI του πελάτη συνεπές με τη συμπεριφορά του διακομιστή.

text
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).

html
@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 πρέπει να αφαιρέσουν αυτά τα αντίγραφα μόλις η σελίδα αποδοθεί από τις εκπεμπόμενες ετικέτες.

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