Panduan Cepat

Render dokumen pertama Anda dalam hitungan menit

Panduan ini membawa aplikasi ASP.NET Core dari Program.cs yang kosong ke 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.

Aplikasi host harus menargetkan runtime yang mendukung netstandard2.1 — .NET Core 3.0 atau lebih baru.

Pengaturan Server

AddDoconut() mendaftarkan layanan; UseDoconutResources() dan UseDoconut() menghubungkan middleware. Panggilan sumber daya harus datang pertama. UseDoconut() menjawab setiap permintaan yang mencapai itu, jadi pasang pada cabangnya sendiri dengan app.Map. Panggilan sesi juga diperlukan — keamanan dokumen default Doconut memvalidasi setiap permintaan halaman terhadap status sesi ASP.NET. Status sesi membutuhkan 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 Installation? Lewati ke bagian berikutnya.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // status sesi membutuhkan cache (MVC/Razor Pages sudah menambah satu)
builder.Services.AddSession(); // Keamanan dokumen Doconut bergantung pada status sesi ASP.NET

app.UseSession();          // panggil UseSession() sebelum UseDoconut()
app.UseDoconutResources(); // harus didaftarkan sebelum UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

Pengaturan ini mempertahankan bentuk permintaan historis DocImage.axd dan memasang middleware dokumen pada cabang yang cocok. Ini adalah susunan yang harus disalin ketika Anda membawa aplikasi .NET Standard yang ada ke depan, karena klien terus memanggil URL yang sama seperti sebelumnya:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // jaga pemeriksaan sesi Doconut's tetap aktif
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // status sesi membutuhkan cache (MVC/Razor Pages sudah menambah satu)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// Diperlukan untuk enkoding multi-byte dalam beberapa format dokumen.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // SEBELUM cabang dokumen
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() tidak mengambil opsi apa pun dalam rilis ini — semuanya dipindahkan ke AddDoconut(). MiddlewarePath adalah nilai koordinasi; ia tidak memetakan cabang ASP.NET Core secara mandiri. Dengan cabang DocImage.axd di atas, klien menggunakan BasePath: '/'; dengan app.Map("/doconut", ...) dari pengaturan minimal, ia menggunakan BasePath: 'doconut'. ResourcesPath menyajikan bundel tersemat di /doconut-res, dan jalur sumber daya gambar widget oleh karena itu adalah ResPath: 'doconut-res/images'.

Tambahkan viewer ke halaman

Viewer adalah inti yang diperlukan dari halaman. Permukaan rendering-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.

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>

Referensi aset penampil

Dalam tampilan Razor, layanan Viewer yang disuntikkan menghasilkan tag <link> dan <script> penampil dalam urutan ketergantungan — widget adalah plugin jQuery, jadi 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 Search atau Annotation Ribbon tanpa mereka, mount Viewer, dan sebuah instance docViewer. ReferenceCss dan ReferenceScripts menghilangkan sumber daya modul opsional ketika lisensi saat ini tidak memberikan kemampuan tersebut; core Viewer tetap dimulai.

Panggilan ini menggantikan file skrip yang disalin secara manual. Jika aplikasi masih memuat docViewer.js, documentLinks.js, atau docViewer.UI.js miliknya, hapus tag tersebut setelah halaman berfungsi dari sumber daya yang dihasilkan — lihat panduan migrasi.

Inisialisasi penampil

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:   '/',                   // cabang DocImage.axd; 'doconut' dengan app.Map("/doconut", ...)
    ResPath:    'doconut-res/images',
    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);
    }
});

Empat detail menentukan apakah halaman ini berfungsi sama sekali:

  • Callbacks adalah opsi. onViewerReady, onViewerBusy, onCopy, dan onAutoLoadStatus diteruskan dalam objek opsi. Viewer sebelumnya menurunkan nama fungsi global dari id kontainer dan memanggilnya; yang ini tidak. Penangan yang dideklarasikan hanya sebagai fungsi global tidak pernah dijalankan, dan tidak ada yang dilaporkan.
  • ResPath menunjuk ke awalan sumber daya, bukan akar aplikasi. Dengan ResourcesPath default, nilai itu adalah doconut-res/images. Jika Anda mengubah ResourcesPath, gunakan awalan Anda sendiri. Ikon berada satu folder di bawah akar sumber daya: dengan 'doconut-res', setiap ikon mengembalikan 404 sementara dokumen itu sendiri masih ditampilkan.
  • BasePath tidak memiliki garis miring di depan selain nilai site-root '/'. 'doconut' meminta /doconut/DocImage.axd; '/doconut' menghasilkan //doconut/DocImage.axd, yang dibaca browser sebagai permintaan ke host lain.
  • Pertahankan penampil, 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, kemudian gagal dengan objViewer.Zoom is not a function pada klik toolbar pertama.

Semua ini gagal secara diam-diam — lihat Pemecahan Masalah dan panduan migrasi.

Penulisan huruf pada opsi memang campur — showThumbs, autoLoad, dan pageZoom menggunakan camelCase, tetapi FitType, BasePath, dan ResPath menggunakan PascalCase. Tidak ada aturan yang konsisten; jika penulisan huruf salah, opsi akan diabaikan secara diam-diam (widget akan kembali ke nilai default alih-alih melemparkan kesalahan).

Susun paket Viewer lengkap

Sebuah halaman viewer lengkap memasang bagian-bagian berikut bersama-sama:

Bagian paketPersyaratanCara terhubung
Sumber daya Viewer, mount, dan objViewerWajibRenderer dokumen inti
Toolbar ViewerWajib untuk halaman lengkapMarkup host; tombol memanggil yang sama objViewer
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 boleh pernah didokumentasikan sebagai kontrol terisolasi. Hal 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>

Pertahankan urutan inisialisasi ini:

  1. Keluarkan CSS untuk Viewer dan modul berlisensi.
  2. Render toolbar Viewer, mount Pencarian/Anotasi, dan mount Viewer secara bersamaan.
  3. Keluarkan skrip untuk Viewer dan modul berlisensi.
  4. Muat skrip pembantu toolbar milik aplikasi host.
  5. Inisialisasi docViewer dan simpan objViewer yang dihasilkan.
  6. Inisialisasi setiap Ribbon Pencarian atau Anotasi berlisensi.
  7. Panggil attach(objViewer) pada setiap Ribbon.
  8. Buka dokumen dan simpan tokennya untuk permintaan Viewer dan modul.

Pengaman sisi server penting: ketika kemampuan opsional tidak tersedia, skripnya tidak dikeluarkan, 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 yang disematkan 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 tersebut mengekspos 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 startup tetap minimal. Lihat Pencarian dan Anotasi untuk pengaturan lengkap yang spesifik fitur, atau Tema Kustom untuk menata atau mengganti toolbar Viewer milik host.

Membuka dokumen

Sisi server memiliki satu endpoint: layanan Viewer yang disuntikkan membuka dokumen dan mengembalikan token sesi. Membuka bersifat asinkron dalam rilis ini.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Token bersifat tidak transparan — 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 itu 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);
    });

Tidak ada yang perlu dipanaskan sebelum pembukaan pertama. Jika Anda melanjutkan aplikasi, hapus semua pemanggilan InitCache() dan flag yang melindunginya — metode tersebut tidak lagi ada.

Panggil objViewer.Close(true) ketika pengguna meninggalkan viewer atau membuka dokumen pengganti: itu membersihkan widget dan mengirim permintaan tutup ke server. objViewer.Close() tanpa argumen hanya membersihkan widget. Pada alur kerja yang digerakkan server, viewer.CloseDocument(token) segera menghapus sesi yang di-cache, membuang mesin rendering, menghapus penanda keamanan, dan mencabut token. Kedaluwarsa bergulir pada akhirnya melakukan pembersihan yang sama, tetapi penutupan eksplisit disarankan untuk dokumen besar.

Alur permintaan yang selesai 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 tersebut mengidentifikasi sesi dokumen yang aktif di server dan tidak berfungsi lagi 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 akan dirender di viewer, dengan panel thumbnail di sebelah kiri. Jika tidak, lihat Pemecahan Masalah.

Apa yang Anda dapatkan tanpa lisensi

Kehilangan lisensi tidak menyebabkan error. Viewer merender 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?