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.

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

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

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

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

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

Untuk paket Viewer lengkap, minta sumber daya Viewer dan modul secara bersamaan:

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

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

  • BasePath tidak 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 seperti BasePath.
  • Callback adalah opsi. onViewerReady, onError dan sisanya dimasukkan ke dalam objek yang diteruskan ke docViewer(...). Fungsi global yang dinamai sesuai viewer, seperti ctlDoc_ViewerReady, tidak pernah dipanggil.
  • Pertahankan viewer, lalu panggil View secara terpisah. docViewer(...) mengembalikan objek dengan Zoom, Next, dan FitType; View(...) mengembalikan sesuatu yang lain. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) menampilkan dokumen, lalu gagal dengan objViewer.Zoom is not a function pada klik toolbar pertama.

Susun paket Viewer lengkap

Sebuah halaman viewer lengkap memasang bagian-bagian berikut secara bersamaan:

Bagian paketKebutuhanCara terhubung
Sumber daya Viewer, mount, dan objViewerWajibRenderer dokumen inti
Toolbar ViewerWajib untuk halaman lengkapMarkup host; tombol memanggil objViewer yang sama
Pita PencarianOpsional, modul berlisensidoconutSearchBar(...).attach(objViewer)
Pita AnotasiOpsional, modul berlisensidoconutAnnotationBar(...).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:

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>

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:

  1. Emit CSS untuk Viewer dan modul berlisensi.
  2. Render toolbar Viewer, mount Pencarian/Anotasi, dan mount Viewer secara bersamaan.
  3. Emit skrip untuk Viewer dan modul berlisensi.
  4. Muat skrip pembantu toolbar milik aplikasi host.
  5. Inisialisasi docViewer dan pertahankan objViewer yang dihasilkan.
  6. Inisialisasi setiap Ribbon Pencarian atau Anotasi yang berlisensi.
  7. Panggil attach(objViewer) pada setiap Ribbon.
  8. 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.

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>

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.

csharp
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):

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

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

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