Hızlı Başlangıç

Bu kılavuz, boş bir Program.cs dosyasından tarayıcıda render edilen bir belgeye kadar bir ASP.NET Core uygulamasını adım adım götürür: sunucu kaydı, tam Viewer paketi (Viewer araç çubuğu, Viewer montajı ve isteğe bağlı Arama/Not ekleme şeritleri), varlık referansları, istemci başlatma, belge açma ve yürütme.

Sunucu kurulumu

AddDoconut() hizmetleri kaydeder; UseDoconutResources() ve UseDoconut() ara katmanı (middleware) bağlar. Kaynak çağrısı önce gelmelidir. Oturum çağrıları da gereklidir — Doconut'un varsayılan belge güvenliği, her sayfa isteğini ASP.NET oturum durumuna karşı doğrular. Zaten Kurulum sırasında Doconut kaydedildi mi? Bir sonraki bölüme atlayın.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddSession(); // Doconut document security rides on ASP.NET session state

app.UseSession();          // call UseSession() before UseDoconut()
app.UseDoconutResources(); // must be registered before UseDoconut()
app.UseDoconut();

Üretim tarzı bir yol düzeni için, belge ara katmanını belirli bir dalda eşleyin ve dört yol ayarını hizalı tutun:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath bir koordinasyon değeridir; tek başına bir ASP.NET Core dalını eşlemez. Bu örnekte ana bilgisayar /doconut yolunu eşler, bu yüzden istemci BasePath: '/doconut' kullanmalıdır. ResourcesPath gömülü paketi /doconut-res adresinde sunar ve widget'ın resim kaynağı yolu bu nedenle ResPath: '/doconut-res/images' olur.

Görüntüleyiciyi bir sayfaya ekleyin

Viewer, sayfanın gerekli çekirdeğidir. Render yüzeyi iki iç içe div kullanır:

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

Araç çubuğu, modül montajları ve Viewer yüzeyini tek bir sayfa kompozisyonu olarak ele alın. Arama ve Not ekleme, gömülü şeritlerini isteğe bağlı montajlara enjekte eder, ancak bu modüller asla bağımsız değildir: her zaman aynı sayfadaki Viewer'a eklenirler. Doconut.TestApp ve Doconut.TestApp.Distributed ile aynı sırayı kullanın:

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer navigation, zoom, Search, and Annotation buttons -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

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

Viewer varlıklarını referans alın

Bir Razor görünümünde, enjekte edilen Viewer servisi, viewer'ın <link> ve <script> etiketlerini bağımlılık sırasına göre üretir — widget bir jQuery eklentisidir, bu yüzden jQuery viewer script'lerinden önce yüklenmelidir:

@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
}))

Tam Viewer paketi için, Viewer ve modül kaynaklarını birlikte isteyin:

@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 ve IncludeViewerScripts zorunlu çekirdek bayraklarıdır. Bunlar, Viewer montajı ve bir docViewer örneği olmadan bir Arama veya Not ekleme Şeridi örneği asla yayınlamayın. ReferenceCss ve ReferenceScripts, geçerli lisans bu yeteneği vermediğinde isteğe bağlı bir modülün kaynaklarını atlar; çekirdek Viewer yine de başlar.

Viewer'ı başlatın

İstemci tarafı widget'ı bir jQuery eklentisidir. İşte gerçek başlatma seçeneklerinin minimal bir seti (sözde kod değil):

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 () {
        // pages are visible; safe to hide a loading spinner here
    },
    // Forward annotation lifecycle events to the embedded ribbon when it is present.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Seçenek adlandırması gerçekten karışıktır — showThumbs, autoLoad ve pageZoom camelCase iken, FitType, BasePath ve ResPath PascalCase'dir. Tutarlı bir kural yoktur; büyük/küçük harf kullanımını yanlış yaparsanız seçenek sessizce yok sayılır (widget varsayılanına geri döner ve hata atmaz).

Tam Viewer paketini birleştirin

Her iki .NET 6 referans uygulaması da aşağıdaki parçaları tek bir sayfada birlikte kurar:

Ana Viewer araç çubuğu ana işaretleme olsa da, Viewer ile birlikte kurulur ve asla izole bir kontrol olarak belgelenmemelidir. Bu, düzenini, etiketlerini, simgelerini ve yetkilendirme kurallarını uygulamanızın kontrolü altında tutar ve her düğme aynı Viewer örneğini çalıştırır:

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

Tam referans araç çubuğu ayrıca wwwroot/js/viewerToolbar.js dosyasını döndürme, küçük resim, yazdırma, tam ekran, düzen ve düğme durumu yardımcıları için ana uygulamaya kopyalar. Bu ana dosyayı Viewer.ReferenceScripts(...) sonrasında yükleyin. Tam demo uygulamasını kopyalarken yardımcı dosyayı ve <nav id="toolbar"> işaretlemesini birlikte tutun.

Her iki referans uygulamasında kullanılan paket başlatma sırasını koruyun:

1. Viewer ve lisanslı modüller için CSS'i yayınlayın.
2. Viewer araç çubuğunu, Arama/Not ekleme montajlarını ve Viewer montajını birlikte render edin.
3. Viewer ve lisanslı modüller için script'leri yayınlayın.
4. Ana uygulamanın viewerToolbar.js dosyasını yükleyin.
5. docViewer'ı başlatın ve elde edilen objViewer'ı saklayın.
6. Her lisanslı Arama veya Not ekleme Şeridini başlatın.
7. Her Şeritte attach(objViewer) çağırın.
8. Belgeyi açın ve Viewer ve modül istekleri için token'ı saklayın.

Doconut.TestApp.Distributed bu tam UI bileşimini ve aynı Viewer araç çubuğu yardımcı dosyasını korur. Ek access istek değeri ve eşzamansız render yeniden deneme ayarları dağıtılmış taşıma için geçerlidir; Viewer, araç çubuğu veya Şeritlerin nasıl birleştirildiğini değiştirmez.

Sunucu tarafı korumaları önemlidir: isteğe bağlı bir yetenek mevcut olmadığında, onun script'i yayınlanmaz, bu yüzden jQuery eklenti fonksiyonu mevcut olmaz.

<script>
    let currentToken = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        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>

Her iki gömülü bileşen kendi Şerit DOM'unu üretir. Arama, Bul, Seçenekler ve Sonuçlar gruplarını içerir. Not ekleme, yazar araçlarını, stil kontrollerini, kaydetme eylemlerini ve isteğe bağlı dışa aktarma/görsel eylemlerini içerir. Şeritler open(), close(), reset() ve isOpen() metodlarını sunar; oluşturduktan sonra her zaman bir kez attach(objViewer) çağırın.

Yukarıdaki örnek, başlangıcı minimal tutmak için isteğe bağlı ana geri çağırmaları ve Not ekleme dışa aktarma/görsel uç noktalarını atlar. Tam özellik‑özel kurulum için Arama ve Not eklemeler bölümlerine bakın, ya da ana uygulamaya ait Viewer araç çubuğunu stilize etmek veya değiştirmek için Özel Temalar bölümüne göz atın.

Bir belge açın

Sunucu tarafı tek bir uç noktadır: enjekte edilen Viewer servisi belgeyi açar ve bir oturum token'ı döner.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // The token is opaque — hand it to the widget, never log or persist it.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

İstemci bu token'ı alır ve widget'a objViewer.View(token) ile verir:

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

Belgeyi kapatın

Kullanıcı görüntüleyiciden ayrıldığında veya yerine yeni bir belge açtığında objViewer.Close() çağırın. Sunucu‑tabanlı iş akışlarında, viewer.CloseDocument(token) önbellekteki oturumu hemen kaldırır, render motorunu serbest bırakır, güvenlik işaretçisini siler ve token'ı iptal eder. Kaydırmalı süresi dolma da aynı temizlik işlemini yapar, ancak büyük belgeler için açıkça kapatmak önerilir.

Tamamlanmış istek akışı şudur:

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

Token'ı bir taşıyıcı kimlik bilgisi gibi ele alın: asla kaydetmeyin, asla kalıcı olarak saklamayın, sadece widget'a verin. Sunucuda canlı bir belge oturumunu tanımlar ve oturum süresi dolduğunda çalışmayı durdurur — yeni bir token almak için belgeyi yeniden açın.

Çalıştırın

wwwroot/files/Sample.pdf konumuna bir PDF yerleştirin, dotnet run komutunu çalıştırın ve widget'ı barındıran sayfayı açın. İlk sayfa, sol tarafta bir küçük resim paneliyle görüntüleyicide render edilir. Eğer render olmazsa, Sorun Giderme bölümüne bakın.

Lisans olmadan ne elde edersiniz

Eksik bir lisans hata vermez. Viewer normal şekilde render eder, ancak her sayfa bir değerlendirme filigranı taşır. Doconut'un lisansı nasıl bulduğunu ve bulduktan sonra ne değiştiğini öğrenmek için Lisans Kurulumu bölümüne bakın.