Προβολέας

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

Viewer (namespace Doconut) είναι το δημόσιο σημείο εισόδου για το άνοιγμα εγγράφων από σελίδες Razor, ελεγκτές MVC, στοιχεία Blazor ή ελάχιστα APIs. Είναι sealed, καταχωρημένο ως transient υπηρεσία από AddDoconut(), και επιλύεται μέσω ένεσης κατασκευαστή — ποτέ μην το δημιουργείτε άμεσα.

Viewer δεν διατηρεί κατάσταση ανά αίτημα και σκόπιμα δεν υλοποιεί IDisposable: οι συνεδρίες εγγράφων ζουν ανεξάρτητα στην κρυφή μνήμη συνεδρίας, έτσι η διαγραφή της υπηρεσίας δεν μπορεί ποτέ να κλείσει ένα ανοιχτό έγγραφο (δείτε (δείτε Βασικές Έννοιες → Πώς Λειτουργεί ο Viewer)).

OpenDocumentAsync (Άνοιγμα Εγγράφου Ασύγχρονα)

Ανοίγει ένα έγγραφο και επιστρέφει το διακριτικό συνεδρίας που χρησιμοποιεί το widget του πελάτη για όλες τις επόμενες αιτήσεις.

ΥπερφόρτωσηΧρήση όταν
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.) εάν το διακριτικό είναι άγνωστο ή ληγμένο, και ArgumentException για κενό διακριτικό.

GetPageDimensions (Διαστάσεις Σελίδας)

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

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

GetWorksheetNames (Ονόματα Φύλλων Εργασίας)

text
IReadOnlyList<string> GetWorksheetNames(string token)

Επιστρέφει τα ονόματα των φύλλων εργασίας ενός ανοιχτού λογιστικού φύλλου, με τη σειρά του βιβλίου εργασίας, ή μια κενή λίστα όταν το ανοιχτό έγγραφο δεν είναι λογιστικό φύλλο.

Μόνο τα εμφανιζόμενα φύλλα εργασίας εμφανίζονται: τα κρυφά και κενά φύλλα εξαιρούνται, και όταν το ExcelConfig.SheetNames περιορίζει την απόδοση, εμφανίζονται μόνο αυτά τα φύλλα. Ένα φύλλο εργασίας δεν είναι πάντα μία σελίδα — ένα πολύ μεγάλο μπορεί να εμφανιστεί σε πολλές σελίδες. Ρίχνει InvalidOperationException (Document session not found. Please re-open document.) εάν το διακριτικό είναι άγνωστο ή ληγμένο, και ArgumentException για κενό διακριτικό.

Προστέθηκε στην 26.9.0.

Capability flags

MemberMeaning
bool IsSearchEnabledΗ τρέχουσα άδεια χορηγεί Search
bool IsAnnotationEnabledΗ τρέχουσα άδεια χορηγεί Annotation

Χρησιμοποιήστε αυτά σε μια Razor view για να αποδώσετε μια αδειοδοτημένη Ribbon μόνο όταν ο διακομιστής θα την εξυπηρετήσει πραγματικά — δείτε την Γρήγορη Εκκίνηση.

DocOptions

Per-open, format-independent options (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 αντί αυτού.
stringWebFarmPath""Παρωχημένο — δεν έχει καμία επίδραση. Χρησιμοποιήστε FileShareConfig.RootPath αντί αυτού.
boolEditModefalseΔεσμευμένο για τη ξεχωριστά διανεμημένη ροή εργασίας του Editor· αφήστε το false για τον τυπικό προβολέα.

Custom watermark

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

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Μέγεθος γραμματοσειράς· εσφαλμένη αριθμητική είσοδος επιστρέφει στην προεπιλογή του renderer.
FontNameVerdanaΖητούμενη οικογένεια γραμματοσειράς. Βεβαιωθείτε ότι είναι εγκατεστημένη στο περιβάλλον ανάπτυξης.
Opacity80Τιμή byte από 0 έως 255. Πρέπει να αναλυθεί επιτυχώς.
Angle-45Γωνία περιστροφής σε μοίρες· εσφαλμένη αριθμητική είσοδος επιστρέφει στην προεπιλογή.

Ο αναλυτής αναμένει ακριβώς έξι πεδία μετά το προαιρετικό ^. Μια μη έγκυρη ορισμός αντικαθίσταται από το ορατό εφεδρικό Invalid Watermark του SDK αντί να εξαφανιστεί σιωπηλά.

License decision

Κατάσταση άδειαςΠροσαρμοσμένη τιμή παρεχόμενηΑποδοτέλο αποτέλεσμα
Έγκυρη πληρωμένη άδεια προβολέαΌχιΚαθαρή σελίδα
Έγκυρη πληρωμένη άδεια προβολέαΝαιΠροσαρμοσμένο υδατογράφημα
Ενεργός προσωρινός/δείγματος βασικός προβολέαςΌχιΚαθαρή σελίδα βασικού προβολέα
Ενεργός προσωρινός/δείγματος βασικός προβολέαςΝαιΠροσαρμοσμένο υδατογράφημα όταν εφαρμόζεται η διαδρομή του καθαρού βασικού προβολέα
Άδεια που λείπει, απορρίπτεται, έχει λήξει, λανθασμένη έκδοση ή μη έγκυρο domainΟποιαδήποτεΥδατογράφημα επιβολής/αξιολόγησης· η προσαρμοσμένη τιμή δεν το παρακάμπτει
Απόδοση plugin υπό κανόνες αξιολόγησηςΟποιαδήποτεΥδατογράφημα αξιολόγησης

Η ίδια απόφαση εφαρμόζεται στις εικόνες σελίδων που εξυπηρετούνται και στις εξαγωγές σχολίων. Η έξοδος 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)Φόρτωση σχολιασμών από το κωδικοποιημένο envelope σελίδας/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 ανά σελίδα με ενσωματωμένους σχολιασμούς

Μεταδεδομένα DICOM

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

Επιστρέφει μεταδεδομένα ετικετών DICOM για συνεδρίες που ανοίχτηκαν μέσω του πρόσθετου DICOM· null για μη‑DICOM έγγραφα.

Βοηθητικά πόρων — ReferenceCss / ReferenceScripts

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

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + προβολέας + αναζήτηση + σημείωση
string ReferenceScripts(ScriptConfig? config = null)

CssConfig σημαίες: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (εξαρτώμενο από αναζήτηση), IncludeAnnotationCss (εξαρτώμενο από σχολιασμό).

ScriptConfig σημαίες: IncludeJQuery (απαιτείται από όλα τα άλλα), IncludeBootstrap, IncludeViewerScripts (πυρήνας: docViewer.js + διαχωριστής + σύνδεσμοι), IncludeSearchScripts και IncludeSearchBar (εξαρτώμενο από αναζήτηση), IncludeAnnotationScripts και IncludeAnnotationBar (εξαρτώμενο από σχολιασμό), EmitFeatureFlags (προεπιλογή true: επίσης γράφει ένα ενσωματωμένο window.Doconut.features = { search, annotation, editor } script; ορίστε το σε 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 }))

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