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

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

Αυτός ο οδηγός παίρνει μια εφαρμογή ASP.NET Core από ένα κενό Program.cs σε ένα έγγραφο που αποδίδεται στον περιηγητή: εγγραφή διακομιστή, το πλήρες πακέτο Viewer (εργαλειοθήκη Viewer, τοποθέτηση Viewer και προαιρετικές ταινίες Αναζήτησης/Σχόλιου), αναφορές πόρων, αρχικοποίηση πελάτη, άνοιγμα εγγράφου και εκτέλεση.

Η εφαρμογή φιλοξενίας πρέπει να στοχεύει σε ένα runtime που υποστηρίζει netstandard2.1 — .NET Core 3.0 ή νεότερο.

Ρύθμιση διακομιστή

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());

Αυτή η ρύθμιση διατηρεί το ιστορικό σχήμα αίτησης DocImage.axd και τοποθετεί το middleware εγγράφου σε έναν αντίστοιχο κλάδο. Αυτή είναι η διάταξη που πρέπει να αντιγράψετε όταν προωθείτε μια υπάρχουσα εφαρμογή .NET Standard, επειδή ο πελάτης συνεχίζει να καλεί το ίδιο URL που πάντα κάλεσε:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // διατηρήστε τον έλεγχο συνεδρίας του Doconut ενεργό
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // η κατάσταση συνεδρίας χρειάζεται μια κρυφή μνήμη (MVC/Razor Pages ήδη προσθέτουν μία)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// Απαιτείται για κωδικοποιήσεις πολλαπλών byte σε ορισμένες μορφές εγγράφων.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // ΠΡΙΝ το κλαδί του εγγράφου
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() δεν παίρνει επιλογές σε αυτή την έκδοση — όλα μεταφέρθηκαν στο AddDoconut(). MiddlewarePath είναι μια τιμή συντονισμού· δεν αντιστοιχεί σε κλάδο ASP.NET Core από μόνη της. Με τον κλάδο DocImage.axd παραπάνω, ο πελάτης χρησιμοποιεί BasePath: '/'· με το app.Map("/doconut", ...) από την ελάχιστη ρύθμιση, χρησιμοποιεί BasePath: 'doconut'. ResourcesPath εξυπηρετεί το ενσωματωμένο πακέτο στο /doconut-res, και η διαδρομή πόρων εικόνας του widget είναι επομένως ResPath: 'doconut-res/images'.

Προσθήκη του 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>

Αναφορά των πόρων του προβολέα

Σε μια Razor view, η ενσωματωμένη υπηρεσία Viewer εκδίδει τις ετικέτες <link> και <script> του προβολέα με σειρά εξάρτησης — το widget είναι ένα πρόσθετο jQuery, επομένως το jQuery πρέπει να φορτωθεί πριν τα σκριπτά του προβολέα:

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

Αυτές οι κλήσεις αντικαθιστούν τα χειροκίνητα αντιγραμμένα αρχεία script. Εάν η εφαρμογή εξακολουθεί να φορτώνει τα δικά της
docViewer.js, documentLinks.js ή docViewer.UI.js, αφαιρέστε αυτές τις ετικέτες μόλις η σελίδα
λειτουργεί από τους εκπεμπόμενους πόρους — δείτε τον οδηγό μετάπτωσης.

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

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

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // το κλαδί DocImage.axd; 'doconut' με app.Map("/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);
    }
});

Τέσσερις λεπτομέρειες αποφασίζουν αν αυτή η σελίδα λειτουργεί καθόλου:

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

Όλα αυτά αποτυγχάνουν σιωπηρά — δείτε το Αντιμετώπιση προβλημάτων και τον
οδηγό μετάπτωσης.

Η κεφαλαιοποίηση των επιλογών είναι πραγματικά ανάμεικτη — showThumbs, autoLoad και pageZoom είναι camelCase, ενώ FitType, BasePath και ResPath είναι PascalCase. Δεν υπάρχει συνεπής κανόνας· αν κάνετε λάθος στην κεφαλαιοποίηση, η επιλογή αγνοείται σιωπηρά (το widget επανέρχεται στην προεπιλογή του αντί να πετάξει σφάλμα).

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

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

Μέρος του πακέτουΑπαίτησηΠώς συνδέεται
Πόροι Viewer, mount, και 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>

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

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

Και τα δύο ενσωματωμένα στοιχεία δημιουργούν το δικό τους Ribbon DOM. Η Αναζήτηση περιλαμβάνει ομάδες Find, Options και Results. Η Σχολιασμός περιέχει τα εργαλεία δημιουργίας, τους ελέγχους στυλ, τις ενέργειες αποθήκευσης και προαιρετικές ενέργειες εξαγωγής/εικόνας. Οι γραμμές εκθέτουν open(), close(), reset() και isOpen()· πάντα καλέστε attach(objViewer) μία φορά μετά τη δημιουργία τους.

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

Άνοιγμα εγγράφου

Η πλευρά του διακομιστή είναι ένα σημείο άκρου: η ενσωματωμένη υπηρεσία 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);
    });

Δεν υπάρχει κάτι που χρειάζεται προθέρμανση πριν το πρώτο άνοιγμα. Εάν προχωράτε με μια εφαρμογή, διαγράψτε οποιαδήποτε κλήση InitCache() και τη σημαία που την προστατεύει — η μέθοδος δεν υπάρχει πλέον.

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

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

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

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

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