Γρήγορη Εκκίνηση

Αποδώστε το πρώτο σας έγγραφο σε λίγα λεπτά

Αυτός ο οδηγός μετατρέπει μια εφαρμογή 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 κατά τη διάρκεια της Εγκατάστασης; Προχωρήστε στην επόμενη ενότητα.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // η κατάσταση συνεδρίας χρειάζεται μια κρυφή μνήμη (MVC/Razor Pages ήδη προσθέτει μία)
builder.Services.AddSession(); // Η ασφάλεια εγγράφων Doconut βασίζεται στην κατάσταση συνεδρίας του ASP.NET

app.UseSession();          // καλέστε το UseSession() πριν το UseDoconut()
app.UseDoconutResources(); // πρέπει να καταχωρηθεί πριν το UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Για μια διάταξη διαδρομών τύπου παραγωγής, αντιστοιχίστε το middleware εγγράφου σε έναν ρητό κλάδο και διατηρήστε τις τέσσερις ρυθμίσεις διαδρομής ευθυγραμμισμένες:

csharp
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:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Θεωρήστε την εργαλειοθήκη, τις τοποθετήσεις μονάδων και την επιφάνεια του Viewer ως μία σύνθεση σελίδας. Η Αναζήτηση και η Σχόλιο ενσωματώνουν τις ενσωματωμένες ταινίες τους σε προαιρετικές τοποθετήσεις, αλλά αυτές οι μονάδες δεν είναι ποτέ αυτόνομες: συνδέονται πάντα με τον Viewer στην ίδια σελίδα. Χρησιμοποιήστε αυτή τη σειρά:

html
<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:

html
@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
@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 είναι οι υποχρεωτικές σημαίες πυρήνα. Ποτέ μην δημοσιεύετε ένα παράδειγμα Αναζήτησης ή Ταινίας Σχολίου χωρίς αυτά, την τοποθέτηση Viewer, και μια docViewer πρόσκληση. ReferenceCss και ReferenceScripts παραλείπουν τους πόρους μιας προαιρετικής μονάδας όταν η τρέχουσα άδεια δεν παρέχει αυτή τη δυνατότητα· ο πυρήνας Viewer εξακολουθεί να εκκινείται.

Αρχικοποίηση του Προβολέα

Το γραφικό στοιχείο στην πλευρά του πελάτη είναι ένα πρόσθετο jQuery. Αυτό είναι ένα ελάχιστο σύνολο πραγματικών επιλογών αρχικοποίησης (όχι ψευδοκώδικας):

javascript
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. Δεν υπάρχει συνεπής κανόνας· αν κάνετε λάθος στην κεφαλοποίηση, η επιλογή αγνοείται σιωπηλά (το γραφικό στοιχείο επιστρέφει στην προεπιλογή του αντί να πετάξει σφάλμα).

Τέσσερις ακόμη λεπτομέρειες αποτυγχάνουν χωρίς μήνυμα σφάλματος:

  • BasePath δεν έχει αρχικό κάθετο. 'doconut' ζητά /doconut/DocImage.axd· '/doconut' δημιουργεί //doconut/DocImage.axd, το οποίο ο φυλλομετρητής διαβάζει ως αίτημα σε άλλο κεντρικό υπολογιστή.
  • ResPath: 'doconut-res/images' — τα εικονίδια βρίσκονται σε έναν φάκελο κάτω από τη ρίζα των πόρων. Με 'doconut-res', κάθε εικονίδιο επιστρέφει 404: δεν υπάρχουν σύμβολα γραμμής εργαλείων και δεν υπάρχει περιστρεφόμενος δείκτης φόρτωσης, ενώ το ίδιο το έγγραφο εξακολουθεί να αποδίδεται. Ένα αρχικό κάθετο το σπάζει με τον ίδιο τρόπο όπως το BasePath.
  • Οι κλήσεις επιστροφής (callbacks) είναι επιλογές. onViewerReady, onError και τα υπόλοιπα τοποθετούνται στο αντικείμενο που περνιέται στο docViewer(...). Μια καθολική συνάρτηση με όνομα το προβολέα, όπως το ctlDoc_ViewerReady, δεν καλείται ποτέ.
  • Διατηρήστε το προβολέα, έπειτα καλέστε το View ξεχωριστά. docViewer(...) επιστρέφει το αντικείμενο με Zoom, Next και FitType· View(...) επιστρέφει κάτι άλλο. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) αποδίδει το έγγραφο, μετά αποτυγχάνει με objViewer.Zoom is not a function στο πρώτο κλικ της γραμμής εργαλείων.

Συναρμολόγηση του πλήρους πακέτου Προβολέα

Μια πλήρης σελίδα προβολέα εγκαθιστά τα παρακάτω μέρη μαζί:

Μέρος του πακέτουΑπαίτησηΠώς συνδέεται
Πόροι Προβολέα, προσάρτηση, και objViewerΑπαιτείταιΚύριος αποδότης εγγράφου
Γραμμή εργαλείων ΠροβολέαΑπαιτείται για πλήρη σελίδαΣύνταξη του φιλοξενητή· τα κουμπιά καλούν το ίδιο objViewer
Λωρίδα αναζήτησηςΠροαιρετικό, αδειοδοτημένη μονάδαdoconutSearchBar(...).attach(objViewer)
Λωρίδα σχολιασμούΠροαιρετικό, αδειοδοτημένη μονάδαdoconutAnnotationBar(...).attach(objViewer)

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

html
<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>

Οι βοηθοί περιστροφής, μικρογραφίας, εκτύπωσης, πλήρους οθόνης, διάταξης και κατάστασης κουμπιών ανήκουν στο δικό σας σενάριο γραμμής εργαλείων, το οποίο καλεί το ίδιο objViewer. Φορτώστε το μετά το Viewer.ReferenceScripts(...) και κρατήστε το μαζί με τη σύνταξη του <nav id="toolbar">.

Διατηρήστε αυτή τη σειρά αρχικοποίησης:

  1. Εκδώστε CSS για το Προβολέα και τις αδειοδοτημένες μονάδες.
  2. Αποδώστε τη γραμμή εργαλείων Προβολέα, τις προσθήκες Αναζήτησης/Σχολιασμού και την προσάρτηση Προβολέα μαζί.
  3. Εκδώστε σενάρια για το Προβολέα και τις αδειοδοτημένες μονάδες.
  4. Φορτώστε το σενάριο βοηθού γραμμής εργαλείων της εφαρμογής-φιλοξενίας.
  5. Αρχικοποιήστε το docViewer και διατηρήστε το προκύπτον objViewer.
  6. Αρχικοποιήστε κάθε αδειοδοτημένη λωρίδα Αναζήτησης ή Σχολιασμού.
  7. Καλέστε το attach(objViewer) σε κάθε λωρίδα.
  8. Ανοίξτε το έγγραφο και διατηρήστε το token του για αιτήματα Προβολέα και μονάδων.

Σε μια κατανεμημένη ανάπτυξη, η πρόσθετη τιμή αιτήματος access και οι ρυθμίσεις επανάληψης ασύγχρονης απόδοσης δεν αλλάζουν τον τρόπο συναρμολόγησης του Προβολέα, της γραμμής εργαλείων ή των λωρίδων.

Οι προστασίες στην πλευρά του διακομιστή είναι σημαντικές: όταν μια προαιρετική δυνατότητα δεν είναι διαθέσιμη, το σενάριο της δεν εκδίδεται, έτσι η λειτουργία πρόσθετου του jQuery δεν υπάρχει.

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

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Το διακριτικό είναι αδιαφανές — δώστε το στο widget, ποτέ μην το καταγράψετε ή το αποθηκεύσετε.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

Ο πελάτης ανακτά αυτό το διακριτικό και το παραδίδει στο widget με objViewer.View(token):

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

Κλείσιμο εγγράφου

Καλέστε objViewer.Close(true) όταν ο χρήστης φεύγει από το viewer ή ανοίγει ένα αντικαταστάσιμο έγγραφο: καθαρίζει το widget και στέλνει αίτημα κλεισίματος στον διακομιστή. objViewer.Close() χωρίς όρισμα καθαρίζει μόνο το widget. Σε ροές εργασίας που ελέγχονται από τον διακομιστή, viewer.CloseDocument(token) αφαιρεί αμέσως τη cached συνεδρία, απελευθερώνει τη μηχανή απόδοσης, διαγράφει το σήμα ασφαλείας της και ανακαλεί το διακριτικό. Η κυλιόμενη λήξη τελικά εκτελεί τον ίδιο καθαρισμό, αλλά συνιστάται ρητό κλείσιμο για μεγάλα έγγραφα.

Η ολοκληρωμένη ροή αιτήματος είναι:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

Αντιμετωπίστε το διακριτικό σαν διαπιστευτήριο τύπου bearer: μην το καταγράφετε ποτέ, μην το αποθηκεύετε ποτέ, παραδώστε το μόνο στο widget. Αναγνωρίζει μια ενεργή συνεδρία εγγράφου στον διακομιστή και σταματά να λειτουργεί όταν η συνεδρία λήξει — ανοίξτε ξανά το έγγραφο για να λάβετε ένα νέο.

Εκτέλεση

Τοποθετήστε ένα PDF στο wwwroot/files/Sample.pdf, εκτελέστε dotnet run και ανοίξτε τη σελίδα που φιλοξενεί το widget. Η πρώτη σελίδα αποδίδεται στο viewer, με ένα πάνελ μικρογραφιών στα αριστερά. Αν δεν συμβαίνει, δείτε Αντιμετώπιση προβλημάτων.

Τι λαμβάνετε χωρίς άδεια

Η έλλειψη άδειας δεν προκαλεί σφάλμα. Το viewer αποδίδει κανονικά, αλλά κάθε σελίδα φέρει υδατογράφημα αξιολόγησης. Δείτε Ρύθμιση άδειας για το πώς το Doconut βρίσκει μια άδεια και τι αλλάζει όταν το κάνει.

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