Γρήγορη Έναρξη

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

Αυτός ο οδηγός μετατρέπει μια εφαρμογή 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(); // 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 εγγράφου σε έναν σαφή κλάδο και διατηρήστε τις τέσσερις ρυθμίσεις διαδρομής ευθυγραμμισμένες:

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 είναι οι υποχρεωτικές σημαίες πυρήνα. Μην δημοσιεύετε ποτέ ένα παράδειγμα Search ή Annotation Ribbon χωρίς αυτά, τη τοποθέτηση Viewer και μια docViewer παρουσία. ReferenceCss και ReferenceScripts παραλείπουν τους πόρους μιας προαιρετικής μονάδας όταν η τρέχουσα άδεια δεν παρέχει αυτή τη δυνατότητα· ο πυρήνας Viewer εξακολουθεί να ξεκινά.

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

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

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>

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

Διατηρήστε αυτή τη σειρά εκκίνησης:

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

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

Οι προστασίες στην πλευρά του διακομιστή είναι σημαντικές: όταν μια προαιρετική δυνατότητα δεν είναι διαθέσιμη, το script της δεν εκδίδεται, έτσι η λειτουργία plug-in του 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 που ανήκει στον κεντρικό υπολογιστή.

Open a document

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

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

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

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

text
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 βρίσκει μια άδεια και τι αλλάζει όταν το κάνει.

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