Hızlı Başlangıç

İlk belgenizi dakikalar içinde render edin

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

Ana uygulama, netstandard2.1'i destekleyen bir çalışma zamanını hedeflemelidir — .NET Core 3.0 veya daha yeni bir sürüm.

Sunucu kurulumu

AddDoconut() hizmetleri kaydeder; UseDoconutResources() ve UseDoconut() ara katmanı bağlar. Kaynak çağrısı önce gelmelidir. UseDoconut() ona ulaşan her isteğe yanıt verir, bu yüzden onu kendi dalında app.Map ile bağlayın. 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. Oturum durumu bir önbellek gerektirir: AddDistributedMemoryCache() bir tane sağlar. Bir MVC veya Razor Pages uygulaması zaten bunu kaydeder, ancak minimal-API uygulaması kaydetmez ve onsuz uygulama, Unable to resolve service for type 'IDistributedCache' ile başlatma sırasında durur. Kurulum sırasında Doconut zaten kaydedildi mi? Bir sonraki bölüme atlayın.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // oturum durumu bir önbellek gerektirir (MVC/Razor Pages zaten bir tane ekler)
builder.Services.AddSession(); // Doconut belge güvenliği ASP.NET oturum durumuna dayanır

app.UseSession();          // UseSession()'i UseDoconut()'dan önce çağırın
app.UseDoconutResources(); // UseDoconut()'dan önce kaydedilmelidir
app.Map("/doconut", branch => branch.UseDoconut());

Bu kurulum, tarihsel DocImage.axd istek biçimini korur ve belge ara katmanını eşleşen bir dalda bağlar. Mevcut bir .NET Standard uygulamasını ilerletirken kopyalamanız gereken düzen budur, çünkü istemci her zaman yaptığı aynı URL'yi çağırmaya devam eder:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // Doconut'un oturum kontrolünün etkin tutulması
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // oturum durumu bir önbellek gerektirir (MVC/Razor Pages zaten bir tane ekler)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// Bazı belge formatlarında çok baytlı kodlamalar için gereklidir.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // ÖNCE belge dalı
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() bu sürümde seçenek almaz — her şey AddDoconut()'a taşındı. MiddlewarePath bir koordinasyon değeridir; tek başına bir ASP.NET Core dalını eşlemez. Yukarıdaki DocImage.axd dalı ile istemci BasePath: '/' kullanır; minimal kurulumdan app.Map("/doconut", ...) ile ise BasePath: 'doconut' kullanır. ResourcesPath gömülü paketi /doconut-res adresinde sunar ve widget'ın görüntü kaynağı yolu bu nedenle ResPath: 'doconut-res/images''dır.

Görüntüleyiciyi bir sayfaya ekleyin

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

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

Araç çubuğunu, modül bağlamalarını ve Viewer yüzeyini tek bir sayfa bileşeni olarak ele alın. Arama ve Not ekleme, gömülü şeritlerini isteğe bağlı bağlamalara enjekte eder, ancak bu modüller asla bağımsız değildir: her zaman aynı sayfadaki Viewer'a eklenirler.

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer gezinme, yakınlaştırma, Arama ve Açıklama düğmeleri -->
</nav>

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

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

Görünüm varlıklarını referans al

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

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

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

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 ve IncludeViewerScripts zorunlu çekirdek bayraklardır. Bunlar olmadan bir
Arama veya Açıklama Şeridi örneğini, Viewer bağlamını ve bir docViewer örneğini yayınlamayın,
örnek. 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.

Bu çağrılar elle kopyalanmış script dosyalarını değiştirir. Uygulama hâlâ kendi
docViewer.js, documentLinks.js veya docViewer.UI.js dosyalarını yüklüyorsa, sayfa
yayınlanan kaynaklardan çalıştığında bu etiketleri kaldırın — geçiş kılavuzu'na bakın.

Görünümü başlat

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

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // DocImage.axd dalı; 'doconut' app.Map("/doconut", ...) ile
    ResPath:    'doconut-res/images',
    onViewerReady: function () {
        // sayfalar görünür; burada bir yükleme göstergesini gizlemek güvenli
    },
    // Gömülü şerit mevcut olduğunda ek açıklama yaşam döngüsü olaylarını ona yönlendir.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

Bu sayfanın çalışıp çalışmadığını belirleyen dört detay:

  • Geri çağrılar bir seçenektir. onViewerReady, onViewerBusy, onCopy ve onAutoLoadStatus seçenek nesnesine geçirilir. Önceki görüntüleyici, global fonksiyon adlarını konteyner kimliğinden türetir ve çağırırdı; bu sürüm bunu yapmaz. Yalnızca global bir fonksiyon olarak bildirilen bir işleyici hiç çalışmaz ve hiçbir şey raporlanmaz.
  • ResPath, kaynak önekine işaret eder, uygulama köküne değil. Varsayılan ResourcesPath ile bu değer doconut-res/images'dır. ResourcesPath'ı değiştirdiyseniz, kendi önekinizi kullanın. Simgeler kaynak kökünün bir klasör altında bulunur: 'doconut-res' ile her simge 404 dönerken belge hâlâ render edilir.
  • BasePath, site‑kökü değeri '/' dışındaki bir ön ek eğik çizgiye sahip değildir. 'doconut', /doconut/DocImage.axd'ı talep eder; '/doconut', tarayıcının başka bir ana bilgisayara istek olarak yorumladığı //doconut/DocImage.axd üretir.
  • Görünümü tutun, ardından View'ı ayrı ayrı çağırın. docViewer(...), Zoom, Next ve FitType içeren nesneyi döndürür; View(...) başka bir şey döndürür. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) belgeyi render eder, ardından ilk araç çubuğu tıklamasında objViewer.Zoom is not a function ile başarısız olur.

Bunların hepsi sessizce başarısız olur — Sorun Giderme ve geçiş kılavuzu'na bakın.

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

Tam Viewer paketini birleştirin

Tam bir viewer sayfası aşağıdaki parçaları birlikte kurar:

Paketin parçasıGereksinimNasıl bağlanır
Viewer kaynakları, bağlama ve objViewerGerekliÇekirdek belge işleyici
Viewer araç çubuğuTam bir sayfa için gerekliHost işaretlemesi; düğmeler aynı objViewer'yi çağırır
Arama şeridiİsteğe bağlı, lisanslı modüldoconutSearchBar(...).attach(objViewer)
Açıklama şeridiİsteğe bağlı, lisanslı modüldoconutAnnotationBar(...).attach(objViewer)

Ana Viewer araç çubuğu host işaretlemesi 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:

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>

Bu başlatma sırasını koruyun:

  1. Viewer ve lisanslı modüller için CSS yayını yapın.
  2. Viewer araç çubuğunu, Arama/Açıklama bağlamalarını ve Viewer bağlamasını birlikte render edin.
  3. Viewer ve lisanslı modüller için scriptleri yayını yapın.
  4. Host uygulamasının kendi araç çubuğu yardımcı scriptini yükleyin.
  5. docViewer'yi başlatın ve ortaya çıkan objViewer'yi tutun.
  6. Her lisanslı Arama veya Açıklama Şeridini başlatın.
  7. Her Şeritte attach(objViewer)'yi çağırın.
  8. Belgeyi açın ve Viewer ve modül istekleri için token'ını saklayın.

Sunucu tarafı korumaları önemlidir: isteğe bağlı bir yetenek mevcut olmadığında, onun scripti yayını yapılmaz, bu yüzden jQuery eklenti işlevi bulunmaz.

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>

Her iki gömülü bileşen kendi Şerit DOM'unu oluşturur. Arama, Bul, Seçenekler ve Sonuçlar gruplarını içerir. Açıklama, yazar araçlarını, stil kontrollerini, kaydetme eylemlerini ve isteğe bağlı dışa aktarım/görüntü eylemlerini içerir. Çubuklar open(), close(), reset() ve isOpen()'i ortaya çıkar; her zaman oluşturduktan sonra bir kez attach(objViewer)'yi çağırın.

Yukarıdaki örnek, başlangıcı minimumda tutmak için isteğe bağlı host geri çağırmalarını ve Açıklama dışa aktarım/görüntü uç noktalarını atlar. Tam özellik‑spesifik kurulum için Arama ve Açıklamalar bölümlerine bakın, ya da host‑sahibi Viewer araç çubuğunu stil vermek veya değiştirmek için Özel Temalar bölümüne göz atın.

Belge Aç

Sunucu tarafı tek bir uç noktadır: enjekte edilen Viewer hizmeti belgeyi açar ve bir oturum belirteci döndürür. Açma işlemi bu sürümde eşzamansızdır.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Token opaktır — widget'a ver, asla günlüğe kaydetme ya da kalıcı hale getirme.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

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

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

İlk açmadan önce ısıtmak için bir şey yoktur. Uygulamayı ileriye taşıyorsanız, herhangi bir InitCache() çağrısını ve onu koruyan bayrağı silin — yöntem artık mevcut değil.

Belgeyi Kapat

Kullanıcı görüntüleyiciden ayrıldığında veya yerine bir belge açtığında objViewer.Close(true) çağırın: widget'ı temizler ve sunucuya bir kapatma isteği gönderir. Argümansız objViewer.Close() yalnızca widget'ı temizler. Sunucu yönlendirmeli iş akışlarında, viewer.CloseDocument(token) önbelleğe alınmış oturumu hemen kaldırır, render motorunu serbest bırakır, güvenlik işaretçisini siler ve belirteci iptal eder. Kayma süresi sonunda aynı temizlik gerçekleşir, ancak büyük belgeler için açıkça kapatma önerilir.

Tamamlanmış istek akışı şudur:

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

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

Çalıştır

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

Lisans Olmadan Neler Alırsınız

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

Bu sayfa yardımcı oldu mu?