Hızlı Başlangıç
İlk belgenizi dakikalar içinde render edin
Bu kılavuz, bir ASP.NET Core uygulamasını boş bir Program.cs'den tarayıcıda render edilen bir belgeye götürür: sunucu kaydı, tam Viewer paketi (Viewer araç çubuğu, Viewer bağlaması ve isteğe bağlı Arama/Açıklama şeritleri), varlık referansları, istemci başlatma, belge açma ve yürütme.
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 durumu ile doğrular. Oturum durumu bir önbellek gerektirir: AddDistributedMemoryCache() bir tane sağlar. 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.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // oturum durumu bir önbelleğe ihtiyaç duyar (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());Üretim tarzı bir yol düzeni için, belge ara katmanını açık bir dala eşleyin ve dört yol ayarını hizalı tutun:
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 bir koordinasyon değeridir; tek başına bir ASP.NET Core dalını eşlemez. Bu örnekte host /doconut'i eşler, bu yüzden istemci BasePath: 'doconut''i kullanır. ResourcesPath gömülü paketi /doconut-res'de sunar ve widget'ın görüntü kaynağı yolu bu nedenle ResPath: 'doconut-res/images''dir. İkisini de başında eğik çizgi olmadan yazın: viewer kendisi bir tane ekler, bu yüzden '/doconut', //doconut/DocImage.axd olur, tarayıcı bunu doconut adlı bir hosta istek olarak okur ve viewer "Görüntüleyici işleyicisine ulaşılamadı" hatasıyla başarısız 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ğunu, modül bağlamalarını ve Viewer yüzeyini tek bir sayfa bileşeni olarak ele alın. Arama ve Açıklama, 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. Bu sıralamayı kullanın:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Viewer navigation, zoom, Search ve Annotation düğmeleri -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Viewer varlıklarına referans verin
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 bağlaması ve bir docViewer örneği olmadan bir Arama veya Açıklama Şeridi örneği asla yayınlamayın. ReferenceCss ve ReferenceScripts, mevcut lisans bu yeteneği vermediğinde isteğe bağlı bir modülün kaynaklarını atlar; çekirdek Viewer yine de başlar.
Görüntüleyiciyi Başlat
İstemci tarafı widget'ı bir jQuery eklentisidir. Bu, gerçek başlatma seçeneklerinin minimal bir setidir (sözde kod değildir):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // başında '/' yok
ResPath: 'doconut-res/images', // başında '/' yok
onViewerReady: function () {
// sayfalar görünür; burada bir yükleme göstergesini gizlemek güvenli
},
// Ek açıklama yaşam döngüsü olaylarını, mevcut olduğunda gömülü şeride ilet.
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 harfleri yanlış yaparsanız seçenek sessizce yok sayılır (widget, hata atmak yerine varsayılanına geri döner).
Dört ek detay, hata mesajı olmadan başarısız olur:
BasePathbaşında eğik çizgi yok.'doconut',/doconut/DocImage.axd'ı talep eder;'/doconut',//doconut/DocImage.axdüretir, bu da tarayıcının başka bir ana bilgisayara istek olarak okumasına neden olur.ResPath: 'doconut-res/images'— simgeler kaynak kökünün bir klasör altında bulunur.'doconut-res'ile, her simge 404 döndürür: araç çubuğu glifleri ve yükleme çubuğu yoktur, ancak belge hâlâ renderlanır. Başlangıçtaki eğik çizgi,BasePathgibi aynı şekilde bozar.- Geri çağrılar seçeneklerdir.
onViewerReady,onErrorve diğerleri,docViewer(...)'a geçirilen nesneye konur. Görüntüleyicinin adıyla aynı olan bir global fonksiyon, örneğinctlDoc_ViewerReady, asla çağrılmaz. - Görüntüleyiciyi tutun, ardından
View'ı ayrı ayrı çağırın.docViewer(...),Zoom,NextveFitTypeiçeren nesneyi döndürür;View(...)başka bir şey döndürür.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)belgeyi renderlar, ardından ilk araç çubuğu tıklamasındaobjViewer.Zoom is not a functionile başarısız olur.
Tam Viewer paketini birleştirin
Tam bir görüntüleyici sayfası aşağıdaki parçaları birlikte kurar:
| Paketin parçası | Gereklilik | Nasıl bağlanır |
|---|---|---|
Viewer kaynakları, bağlama ve objViewer | Gerekli | Temel belge renderleyicisi |
| Viewer araç çubuğu | Tam bir sayfa için gerekli | Ana uygulama işaretlemesi; düğmeler aynı objViewer'ı çağırır |
| Arama şeridi | İsteğe bağlı, lisanslı modül | doconutSearchBar(...).attach(objViewer) |
| Açıklama şeridi | İsteğe bağlı, lisanslı modül | doconutAnnotationBar(...).attach(objViewer) |
Ana Viewer araç çubuğu ana uygulama 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:
<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>Döndürme, küçük resim, yazdırma, tam ekran, düzen ve düğme durumu yardımcıları, aynı objViewer'ı çağıran kendi araç çubuğu betiğinizde bulunmalıdır. Viewer.ReferenceScripts(...)'dan sonra yükleyin ve onun <nav id="toolbar"> işaretlemesiyle birlikte tutun.
Bu başlatma sırasını tutun:
- Viewer ve lisanslı modüller için CSS üretin.
- Viewer araç çubuğunu, Arama/Açıklama bağlamalarını ve Viewer bağlamasını birlikte renderlayın.
- Viewer ve lisanslı modüller için betikleri üretin.
- Ana uygulamanın kendi araç çubuğu yardımcı betiğini yükleyin.
docViewer'ı başlatın ve elde edilenobjViewer'ı tutun.- Her lisanslı Arama veya Açıklama Şeridini başlatın.
- Her Şeritte
attach(objViewer)'ı çağırın. - Belgeyi açın ve Viewer ile modül istekleri için token'ını saklayın.
Dağıtılmış bir dağıtımda, ek access istek değeri ve eşzamansız-render yeniden deneme ayarları taşıma katmanına aittir; 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 betiği üretilmez, bu yüzden jQuery eklenti fonksiyonu mevcut olmaz.
<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>Gömülü her iki bileşen de 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; 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 uygulama geri çağrılarını ve Açıklama dışa aktarım/görüntü uç noktalarını atlar. Tam özellik‑spesifik kurulumu görmek için Search ve Annotations sayfalarına bakın, ya da ana uygulamaya ait Viewer araç çubuğunu stilize etmek veya değiştirmek için Custom Themes sayfasına 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 belirteci döndürür.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Token opaktır — widget'a ver, asla log veya persist etme.
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:
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Belgeyi kapatın
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. objViewer.Close() argümansız çağrıldığında yalnızca widget'ı temizler. Sunucu yönlendirmeli 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 belirteci iptal eder. Kayma süresi sonunda aynı temizlik yapılır, ancak büyük belgeler için açıkça kapatma önerilir.
Tamamlanmış istek akışı şu şekildedir:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentBelirteci 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 belirteç almak için belgeyi yeniden açın.
Çalıştırın
wwwroot/files/Sample.pdf adresine bir PDF 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 ne elde edersiniz
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?