Panduan Cepat
Render dokumen pertama Anda dalam hitungan menit
Panduan ini membawa aplikasi ASP.NET Core dari Program.cs yang kosong hingga dokumen yang dirender di peramban: pendaftaran server, paket Viewer lengkap (toolbar Viewer, mount Viewer, dan pita Pencarian/Anotasi opsional), referensi aset, inisialisasi klien, pembukaan dokumen, dan eksekusi.
Pengaturan Server
AddDoconut() mendaftarkan layanan; UseDoconutResources() dan UseDoconut() menghubungkan middleware. Panggilan resources harus datang pertama. UseDoconut() menjawab setiap permintaan yang mencapainya, jadi pasang di cabang terpisah dengan app.Map. Panggilan sesi juga diperlukan — keamanan dokumen default Doconut memvalidasi setiap permintaan halaman terhadap status sesi ASP.NET. Status sesi memerlukan cache: AddDistributedMemoryCache() menyediakan satu. Aplikasi MVC atau Razor Pages sudah mendaftarkannya, tetapi aplikasi minimal-API tidak, dan tanpa itu aplikasi berhenti saat startup dengan Unable to resolve service for type 'IDistributedCache'. Sudah mendaftarkan Doconut selama Instalasi? Lewati ke bagian berikutnya.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state membutuhkan cache (MVC/Razor Pages sudah menambah satu)
builder.Services.AddSession(); // Keamanan dokumen Doconut bergantung pada session state ASP.NET
app.UseSession(); // panggil UseSession() sebelum UseDoconut()
app.UseDoconutResources(); // harus didaftarkan sebelum UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());Untuk tata letak jalur bergaya produksi, petakan middleware dokumen ke cabang eksplisit dan pertahankan empat pengaturan jalur tetap selaras:
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 adalah nilai koordinasi; ia tidak memetakan cabang ASP.NET Core secara mandiri. Dalam contoh ini host memetakan /doconut, sehingga klien menggunakan BasePath: 'doconut'. ResourcesPath menyajikan bundel tersemat di /doconut-res, dan jalur sumber daya gambar widget oleh karena itu ResPath: 'doconut-res/images'. Tulis keduanya tanpa garis miring di depan: penampil menambahkan satu secara otomatis, sehingga '/doconut' akan menjadi //doconut/DocImage.axd, yang dibaca peramban sebagai permintaan ke host bernama doconut, dan penampil gagal dengan "The viewer handler could not be reached".
Tambahkan penampil ke halaman
Viewer adalah inti yang diperlukan dari halaman. Permukaan render-nya menggunakan dua div bersarang:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Anggap toolbar, mount modul, dan permukaan Viewer sebagai satu komposisi halaman. Pencarian dan Anotasi menyuntikkan pita tersemat mereka ke dalam mount opsional, tetapi modul-modul tersebut tidak pernah berdiri sendiri: mereka selalu menempel pada Viewer di halaman yang sama. Gunakan urutan ini:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Tombol navigasi Viewer, zoom, Pencarian, dan Anotasi -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>Referensikan aset penampil
Dalam tampilan Razor, layanan Viewer yang disuntikkan menghasilkan tag <link> dan <script> penampil dalam urutan ketergantungan — widget adalah plugin jQuery, sehingga jQuery harus dimuat sebelum skrip penampil:
@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
}))Untuk paket Viewer lengkap, minta sumber daya Viewer dan modul secara bersamaan:
@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 dan IncludeViewerScripts adalah flag inti wajib. Jangan pernah memublikasikan contoh Pencarian atau Pita Anotasi tanpa mereka, mount Viewer, dan sebuah instance docViewer. ReferenceCss dan ReferenceScripts menghilangkan sumber daya modul opsional ketika lisensi saat ini tidak memberikan kemampuan tersebut; Viewer inti tetap berjalan.
Inisialisasi Viewer
Widget sisi klien adalah plugin jQuery. Ini adalah sekumpulan opsi inisialisasi nyata yang minimal (bukan pseudocode):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // tidak ada '/' di depan
ResPath: 'doconut-res/images', // tidak ada '/' di depan
onViewerReady: function () {
// halaman terlihat; aman untuk menyembunyikan spinner pemuatan di sini
},
// Teruskan peristiwa siklus hidup anotasi ke ribbon tersemat ketika ada.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});Penulisan huruf pada opsi memang campur — showThumbs, autoLoad, dan pageZoom menggunakan camelCase, tetapi FitType, BasePath, dan ResPath menggunakan PascalCase. Tidak ada aturan konsisten; jika penulisan huruf salah, opsi akan diabaikan secara diam-diam (widget akan kembali ke nilai default alih-alih melempar kesalahan).
Empat detail lagi gagal tanpa pesan error:
BasePathtidak memiliki garis miring di depan.'doconut'meminta/doconut/DocImage.axd;'/doconut'menghasilkan//doconut/DocImage.axd, yang dibaca browser sebagai permintaan ke host lain.ResPath: 'doconut-res/images'— ikon berada satu folder di bawah akar sumber daya. Dengan'doconut-res', setiap ikon mengembalikan 404: tidak ada glyph toolbar dan tidak ada spinner pemuatan, sementara dokumen itu sendiri tetap ditampilkan. Garis miring di depan memecahkannya dengan cara yang sama sepertiBasePath.- Callback adalah opsi.
onViewerReady,onErrordan sisanya dimasukkan ke dalam objek yang diteruskan kedocViewer(...). Fungsi global yang dinamai sesuai viewer, sepertictlDoc_ViewerReady, tidak pernah dipanggil. - Pertahankan viewer, lalu panggil
Viewsecara terpisah.docViewer(...)mengembalikan objek denganZoom,Next, danFitType;View(...)mengembalikan sesuatu yang lain.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)menampilkan dokumen, lalu gagal denganobjViewer.Zoom is not a functionpada klik toolbar pertama.
Susun paket Viewer lengkap
Sebuah halaman viewer lengkap memasang bagian-bagian berikut secara bersamaan:
| Bagian paket | Kebutuhan | Cara terhubung |
|---|---|---|
Sumber daya Viewer, mount, dan objViewer | Wajib | Renderer dokumen inti |
| Toolbar Viewer | Wajib untuk halaman lengkap | Markup host; tombol memanggil objViewer yang sama |
| Pita Pencarian | Opsional, modul berlisensi | doconutSearchBar(...).attach(objViewer) |
| Pita Anotasi | Opsional, modul berlisensi | doconutAnnotationBar(...).attach(objViewer) |
Meskipun toolbar Viewer utama adalah markup host, ia dipasang bersamaan dengan Viewer dan tidak pernah boleh didokumentasikan sebagai kontrol terisolasi. Ini menjaga tata letak, label, ikon, dan aturan otorisasi di bawah kontrol aplikasi Anda sementara setiap tombol mengendalikan instance Viewer yang sama:
<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>Rotasi, thumbnail, cetak, layar penuh, tata letak, dan pembantu status tombol harus berada dalam skrip toolbar Anda sendiri, yang memanggil objViewer yang sama. Muat setelah Viewer.ReferenceScripts(...), dan simpan bersama markup <nav id="toolbar"> miliknya.
Pertahankan urutan inisialisasi ini:
- Emit CSS untuk Viewer dan modul berlisensi.
- Render toolbar Viewer, mount Pencarian/Anotasi, dan mount Viewer secara bersamaan.
- Emit skrip untuk Viewer dan modul berlisensi.
- Muat skrip pembantu toolbar milik aplikasi host.
- Inisialisasi
docViewerdan pertahankanobjVieweryang dihasilkan. - Inisialisasi setiap Ribbon Pencarian atau Anotasi yang berlisensi.
- Panggil
attach(objViewer)pada setiap Ribbon. - Buka dokumen dan simpan tokennya untuk permintaan Viewer dan modul.
Dalam penyebaran terdistribusi, nilai permintaan tambahan access dan pengaturan ulang coba render-asinkron termasuk dalam transport; mereka tidak mengubah cara Viewer, toolbar, atau Ribbon dirakit.
Penjaga sisi server penting: ketika kemampuan opsional tidak tersedia, skripnya tidak di‑emit, sehingga fungsi plug‑in jQuery‑nya tidak ada.
<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>Kedua komponen tersemat menghasilkan DOM Ribbon masing‑masing. Pencarian berisi grup Temukan, Opsi, dan Hasil. Anotasi berisi alat penulisan, kontrol gaya, aksi simpan, dan aksi ekspor/gambar opsional. Bar menampilkan open(), close(), reset(), dan isOpen(); selalu panggil attach(objViewer) sekali setelah membuatnya.
Contoh di atas menghilangkan callback host opsional dan endpoint ekspor/gambar Anotasi untuk menjaga inisialisasi minimal. Lihat Pencarian dan Anotasi untuk pengaturan lengkap fitur‑spesifik, atau Tema Kustom untuk menata atau mengganti toolbar Viewer milik host.
Buka dokumen
Sisi server memiliki satu endpoint: layanan Viewer yang disuntikkan membuka dokumen dan mengembalikan token sesi.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// Token bersifat opak — serahkan ke widget, jangan pernah mencatat atau menyimpannya.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});Klien mengambil token tersebut dan memberikannya ke widget dengan objViewer.View(token):
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});Tutup dokumen
Panggil objViewer.Close(true) ketika pengguna meninggalkan penampil atau membuka dokumen pengganti: itu membersihkan widget dan mengirim permintaan tutup ke server. objViewer.Close() tanpa argumen hanya membersihkan widget. Pada alur kerja yang dipandu server, viewer.CloseDocument(token) segera menghapus sesi yang di‑cache, membuang mesin rendering, menghapus penanda keamanannya, dan mencabut token. Kedaluwarsa bergulir pada akhirnya melakukan pembersihan yang sama, tetapi penutupan eksplisit disarankan untuk dokumen besar.
Alur permintaan yang lengkap adalah:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentPerlakukan token seperti kredensial bearer: jangan pernah mencatatnya, jangan pernah menyimpannya, berikan hanya ke widget. Token ini mengidentifikasi sesi dokumen yang aktif di server dan berhenti berfungsi ketika sesi tersebut kedaluwarsa — buka kembali dokumen untuk mendapatkan yang baru.
Jalankan
Letakkan PDF di wwwroot/files/Sample.pdf, jalankan dotnet run, dan buka halaman yang menampung widget. Halaman pertama ditampilkan di penampil, dengan panel thumbnail di sebelah kiri. Jika tidak, lihat Pemecahan Masalah.
Apa yang Anda dapatkan tanpa lisensi
Lisensi yang hilang tidak menyebabkan error. Penampil menampilkan secara normal, tetapi setiap halaman menampilkan watermark evaluasi. Lihat Pengaturan Lisensi untuk cara Doconut menemukan lisensi dan apa yang berubah setelahnya.
Apakah halaman ini membantu?