Γρήγορη Έναρξη
Αποδώστε το πρώτο σας έγγραφο σε λίγα λεπτά
Αυτός ο οδηγός μετατρέπει μια εφαρμογή ASP.NET Core από ένα κενό Program.cs σε ένα έγγραφο που αποδίδεται στον περιηγητή: εγγραφή διακομιστή, το πλήρες πακέτο Viewer (εργαλειοθήκη Viewer, τοποθέτηση Viewer και προαιρετικές ταινίες Αναζήτησης/Σχόλιου), αναφορές πόρων, αρχικοποίηση πελάτη, άνοιγμα εγγράφου και εκτέλεση.
Ρύθμιση διακομιστή
AddDoconut() καταχωρεί τις υπηρεσίες· UseDoconutResources() και UseDoconut() συνδέουν το middleware. Η κλήση πόρων πρέπει να γίνει πρώτη. UseDoconut() απαντά σε κάθε αίτημα που το φθάνει, επομένως τοποθετήστε το σε δικό του κλάδο με app.Map. Οι κλήσεις συνεδρίας απαιτούνται επίσης — η προεπιλεγμένη ασφάλεια εγγράφων του Doconut επικυρώνει κάθε αίτημα σελίδας έναντι της κατάστασης συνεδρίας ASP.NET. Η κατάσταση συνεδρίας χρειάζεται μια κρυφή μνήμη: AddDistributedMemoryCache() παρέχει μία. Μια εφαρμογή MVC ή Razor Pages την καταχωρεί ήδη, αλλά μια ελάχιστη εφαρμογή API δεν το κάνει, και χωρίς αυτή η εφαρμογή σταματά κατά την εκκίνηση με Unable to resolve service for type 'IDistributedCache'. Έχετε ήδη καταχωρήσει το Doconut κατά τη διάρκεια της Εγκατάστασης; Προχωρήστε στην επόμενη ενότητα.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state χρειάζεται μια κρυφή μνήμη (MVC/Razor Pages προσθέτει ήδη μία)
builder.Services.AddSession(); // Doconut ασφάλεια εγγράφου εξαρτάται από ASP.NET session state
app.UseSession(); // καλέστε UseSession() πριν από UseDoconut()
app.UseDoconutResources(); // πρέπει να εγγραφεί πριν από UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());Για μια διάταξη διαδρομών τύπου παραγωγής, αντιστοιχίστε το middleware εγγράφου σε έναν σαφή κλάδο και διατηρήστε τις τέσσερις ρυθμίσεις διαδρομής ευθυγραμμισμένες:
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
options.MiddlewarePath = "/doconut";
options.ResourcesPath = "/doconut-res";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());MiddlewarePath είναι μια τιμή συντονισμού· δεν αντιστοιχίζει έναν κλάδο ASP.NET Core από μόνη της. Σε αυτό το παράδειγμα ο κεντρικός υπολογιστής αντιστοιχίζει /doconut, έτσι ο πελάτης χρησιμοποιεί BasePath: 'doconut'. ResourcesPath εξυπηρετεί το ενσωματωμένο πακέτο στο /doconut-res, και η διαδρομή πόρου εικόνας του widget είναι επομένως ResPath: 'doconut-res/images'. Γράψτε και τα δύο χωρίς αρχική κάθετο: ο viewer προσθέτει ένα μόνο του, έτσι '/doconut' θα γίνει //doconut/DocImage.axd, το οποίο ο περιηγητής διαβάζει ως αίτημα σε έναν κεντρικό υπολογιστή με όνομα doconut, και ο viewer αποτυγχάνει με "The viewer handler could not be reached".
Προσθήκη του viewer σε μια σελίδα
Ο Viewer είναι ο απαιτούμενος πυρήνας της σελίδας. Η επιφάνεια απόδοσής του χρησιμοποιεί δύο ένθετα divs:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Αντιμετωπίστε την εργαλειοθήκη, τις τοποθετήσεις μονάδων και την επιφάνεια Viewer ως μία σύνθεση σελίδας. Η Αναζήτηση και το Σχόλιο ενσωματώνουν τις ενσωματωμένες ταινίες τους σε προαιρετικές τοποθετήσεις, αλλά αυτές οι μονάδες δεν είναι ποτέ αυτόνομες: συνδέονται πάντα με τον Viewer στην ίδια σελίδα. Χρησιμοποιήστε αυτή τη σειρά:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Viewer πλοήγηση, ζουμ, Αναζήτηση και κουμπιά Σχολιασμού -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Αναφορά των πόρων του viewer
Σε μια Razor προβολή, η ενσωματωμένη υπηρεσία Viewer εκδίδει τις ετικέτες <link> και <script> του viewer με σειρά εξάρτησης — το widget είναι ένα πρόσθετο jQuery, επομένως το jQuery πρέπει να φορτωθεί πριν τα σενάρια του viewer:
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
}))Για το πλήρες πακέτο Viewer, ζητήστε μαζί τους πόρους Viewer και μονάδας:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true,
IncludeSearchCss = true,
IncludeAnnotationCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true,
IncludeSearchScripts = true,
IncludeSearchBar = true,
IncludeAnnotationScripts = true,
IncludeAnnotationBar = true
}))IncludeViewerCss και IncludeViewerScripts είναι οι υποχρεωτικές σημαίες πυρήνα. Μην δημοσιεύετε ποτέ ένα
παράδειγμα Search ή Annotation Ribbon χωρίς αυτά, τη τοποθέτηση Viewer και μια docViewer
παρουσία. ReferenceCss και ReferenceScripts παραλείπουν τους πόρους μιας προαιρετικής μονάδας όταν
η τρέχουσα άδεια δεν παρέχει αυτή τη δυνατότητα· ο πυρήνας Viewer εξακολουθεί να ξεκινά.
Αρχικοποίηση του προβολέα
Το widget στην πλευρά του πελάτη είναι ένα πρόσθετο jQuery. Αυτό είναι ένα ελάχιστο σύνολο πραγματικών επιλογών εκκίνησης (όχι ψευδοκώδικας):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // χωρίς αρχικό '/'
ResPath: 'doconut-res/images', // χωρίς αρχικό '/'
onViewerReady: function () {
// οι σελίδες είναι ορατές; ασφαλές να κρύψετε έναν δείκτη φόρτωσης εδώ
},
// Προωθήστε τα γεγονότα κύκλου ζωής της σημείωσης στο ενσωματωμένο ribbon όταν είναι παρόν.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});Η κεφαλοποίηση των επιλογών είναι πραγματικά ανάμεικτη — showThumbs, autoLoad, και pageZoom είναι camelCase, αλλά FitType, BasePath, και ResPath είναι PascalCase. Δεν υπάρχει συνεπής κανόνας· αν κάνετε λάθος την κεφαλοποίηση, η επιλογή αγνοείται σιωπηλά (το widget επιστρέφει στην προεπιλογή του αντί να πετάξει σφάλμα).
Τέσσερις ακόμη λεπτομέρειες αποτυγχάνουν χωρίς μήνυμα σφάλματος:
BasePathδεν έχει αρχικό κάθετο.'doconut'ζητά/doconut/DocImage.axd·'/doconut'παράγει//doconut/DocImage.axd, το οποίο ο περιηγητής διαβάζει ως αίτημα σε άλλο κεντρικό υπολογιστή.ResPath: 'doconut-res/images'— τα εικονίδια βρίσκονται σε έναν φάκελο κάτω από τη ρίζα των πόρων. Με'doconut-res', κάθε εικονίδιο επιστρέφει 404: δεν υπάρχουν σύμβολα γραμμής εργαλείων και δεν υπάρχει δείκτης φόρτωσης, ενώ το έγγραφο εξακολουθεί να αποδίδεται. Ένα αρχικό κάθετο το σπάζει με τον ίδιο τρόπο όπως τοBasePath.- Οι κλήσεις επιστροφής είναι επιλογές.
onViewerReady,onErrorκαι τα υπόλοιπα τοποθετούνται στο αντικείμενο που περνιέται στοdocViewer(...). Μια καθολική συνάρτηση με όνομα το ίδιο με το προβολέα, όπως τοctlDoc_ViewerReady, δεν καλείται ποτέ. - Διατηρήστε το προβολέα, έπειτα καλέστε το
Viewξεχωριστά.docViewer(...)επιστρέφει το αντικείμενο μεZoom,NextκαιFitType·View(...)επιστρέφει κάτι άλλο.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)αποδίδει το έγγραφο, μετά αποτυγχάνει μεobjViewer.Zoom is not a functionστο πρώτο κλικ της γραμμής εργαλείων.
Συναρμολόγηση του πλήρους πακέτου Viewer
Μια πλήρης σελίδα προβολέα εγκαθιστά τα παρακάτω μέρη μαζί:
| Μέρος του πακέτου | Απαίτηση | Πώς συνδέεται |
|---|---|---|
Πόροι Viewer, προσάρτηση και objViewer | Απαιτείται | Κύριο σύστημα απόδοσης εγγράφου |
| Γραμμή εργαλείων Viewer | Απαιτείται για πλήρη σελίδα | Σήμανση κεντρικού υπολογιστή· τα κουμπιά καλούν το ίδιο objViewer |
| Λωρίδα Αναζήτησης | Προαιρετικό, αδειοδοτημένο μοντέλο | doconutSearchBar(...).attach(objViewer) |
| Λωρίδα Σχολιασμού | Προαιρετικό, αδειοδοτημένο μοντέλο | doconutAnnotationBar(...).attach(objViewer) |
Παρόλο που η κύρια γραμμή εργαλείων Viewer είναι σήμανση κεντρικού υπολογιστή, εγκαθίσταται παράλληλα με το Viewer και δεν πρέπει ποτέ να τεκμηριώνεται ως απομονωμένος έλεγχος. Αυτό διατηρεί τη διάταξη, τις ετικέτες, τα εικονίδια και τους κανόνες εξουσιοδότησης υπό τον έλεγχο της εφαρμογής σας, ενώ κάθε κουμπί ελέγχει την ίδια παρουσία Viewer:
<nav id="toolbar" aria-label="Document viewer controls">
<button type="button" onclick="objViewer.GotoPage(1)">First</button>
<button type="button" onclick="objViewer.Next(false)">Previous</button>
<button type="button" onclick="objViewer.Next(true)">Next</button>
<button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
<button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
<button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
<button type="button" onclick="objViewer.FitType('width')">Fit width</button>
<button type="button" onclick="objViewer.FitType('height')">Fit height</button>
<button type="button" id="openSearch">Search</button>
<button type="button" id="openAnnotations">Annotations</button>
</nav>Οι βοηθοί περιστροφής, μικρογραφίας, εκτύπωσης, πλήρους οθόνης, διάταξης και κατάστασης κουμπιών ανήκουν στο δικό σας script γραμμής εργαλείων, το οποίο καλεί το ίδιο objViewer. Φορτώστε το μετά το Viewer.ReferenceScripts(...) και κρατήστε το μαζί με τη σήμανση <nav id="toolbar"> του.
Διατηρήστε αυτή τη σειρά εκκίνησης:
- Εκδώστε CSS για το Viewer και τα αδειοδοτημένα modules.
- Αποδώστε τη γραμμή εργαλείων Viewer, τις προσθήκες Αναζήτησης/Σχολιασμού και την προσάρτηση Viewer μαζί.
- Εκδώστε scripts για το Viewer και τα αδειοδοτημένα modules.
- Φορτώστε το δικό σας script βοηθού γραμμής εργαλείων της εφαρμογής-κεντρικού.
- Αρχικοποιήστε το
docViewerκαι διατηρήστε το προκύπτονobjViewer. - Αρχικοποιήστε κάθε αδειοδοτημένη Λωρίδα Αναζήτησης ή Σχολιασμού.
- Καλέστε το
attach(objViewer)σε κάθε Λωρίδα. - Ανοίξτε το έγγραφο και διατηρήστε το token του για αιτήματα Viewer και modules.
Σε μια κατανεμημένη ανάπτυξη, η πρόσθετη τιμή αιτήματος access και οι ρυθμίσεις επανάληψης ασύγχρονης απόδοσης ανήκουν στη μεταφορά· δεν αλλάζουν τον τρόπο με τον οποίο συναρμολογούνται το Viewer, η γραμμή εργαλείων ή οι Λωρίδες.
Οι προστασίες στην πλευρά του διακομιστή είναι σημαντικές: όταν μια προαιρετική δυνατότητα δεν είναι διαθέσιμη, το script της δεν εκδίδεται, έτσι η λειτουργία plug-in του jQuery δεν υπάρχει.
<script>
let token = '';
const refitViewer = () =>
requestAnimationFrame(() => objViewer.Refit());
@if (Viewer.IsSearchEnabled)
{
<text>
searchBar = $('#searchBarMount').doconutSearchBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
searchBar.attach(objViewer);
</text>
}
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
annBar.attach(objViewer);
</text>
}
document.getElementById('openSearch').addEventListener('click', () => {
if (!searchBar) return;
searchBar.isOpen() ? searchBar.close() : searchBar.open();
});
document.getElementById('openAnnotations').addEventListener('click', () => {
if (!annBar) return;
annBar.isOpen() ? annBar.close() : annBar.open();
});
</script>Και τα δύο ενσωματωμένα στοιχεία δημιουργούν το δικό τους DOM Λωρίδας. Η Αναζήτηση περιέχει ομάδες Εύρεση, Επιλογές και Αποτελέσματα. Η Σχολιασμός περιέχει τα εργαλεία συγγραφής, ελέγχους στυλ, ενέργειες αποθήκευσης και προαιρετικές ενέργειες εξαγωγής/εικόνας. Οι γραμμές εκθέτουν τα open(), close(), reset() και isOpen()· πάντα καλέστε το attach(objViewer) μία φορά μετά τη δημιουργία τους.
Το παραπάνω παράδειγμα παραλείπει προαιρετικές κλήσεις επιστροφής κεντρικού υπολογιστή και τελικά σημεία εξαγωγής/εικόνας Σχολιασμού για να διατηρήσει την εκκίνηση ελάχιστη. Δείτε Αναζήτηση και Σχόλια για τη πλήρη ρύθμιση ανά χαρακτηριστικό, ή Προσαρμοσμένα Θέματα για να μορφοποιήσετε ή να αντικαταστήσετε τη γραμμή εργαλείων Viewer που ανήκει στον κεντρικό υπολογιστή.
Open a document
Η πλευρά του διακομιστή είναι ένα άκρο: η ενσωματωμένη υπηρεσία Viewer ανοίγει το έγγραφο και επιστρέφει ένα διακριτικό συνεδρίας.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Το token είναι αδιαφανές — δώστε το στο widget, ποτέ μην το καταγράψετε ή το αποθηκεύσετε.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});Ο πελάτης ανακτά αυτό το διακριτικό και το παραδίδει στο widget με objViewer.View(token):
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Close the document
Καλέστε objViewer.Close(true) όταν ο χρήστης φεύγει από το viewer ή ανοίγει ένα αντικαταστατικό έγγραφο: καθαρίζει το widget και στέλνει ένα αίτημα κλεισίματος στον διακομιστή. objViewer.Close() χωρίς όρισμα καθαρίζει μόνο το widget. Σε ροές εργασίας που ελέγχονται από τον διακομιστή, viewer.CloseDocument(token) αφαιρεί αμέσως τη cached συνεδρία, απελευθερώνει τη μηχανή απόδοσης, διαγράφει το σήμα ασφαλείας της και ανακαλεί το διακριτικό. Η κυλιόμενη λήξη τελικά εκτελεί τον ίδιο καθαρισμό, αλλά συνιστάται ρητό κλείσιμο για μεγάλα έγγραφα.
Η ολοκληρωμένη ροή αιτήματος είναι:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentΑντιμετωπίστε το διακριτικό σαν διαπιστευτήριο κάτοχου: μην το καταγράφετε ποτέ, μην το αποθηκεύετε ποτέ, παραδώστε το μόνο στο widget. Αναγνωρίζει μια ζωντανή συνεδρία εγγράφου στον διακομιστή και σταματά να λειτουργεί όταν αυτή η συνεδρία λήξει — ανοίξτε ξανά το έγγραφο για να λάβετε ένα νέο.
Run it
Τοποθετήστε ένα PDF στο wwwroot/files/Sample.pdf, εκτελέστε dotnet run, και ανοίξτε τη σελίδα που φιλοξενεί το widget. Η πρώτη σελίδα αποδίδεται στο viewer, με ένα πάνελ μικρογραφιών στα αριστερά. Αν δεν συμβαίνει, δείτε Αντιμετώπιση προβλημάτων.
What you get without a license
Η έλλειψη άδειας δεν προκαλεί σφάλμα. Το viewer αποδίδει κανονικά, αλλά κάθε σελίδα φέρει ένα υδατογράφημα αξιολόγησης. Δείτε Ρύθμιση άδειας για το πώς το Doconut βρίσκει μια άδεια και τι αλλάζει όταν το κάνει.
Ήταν αυτή η σελίδα χρήσιμη;