Penampil

Viewer (namespace Doconut) adalah titik masuk publik untuk membuka dokumen dari halaman Razor, kontroler MVC, komponen Blazor, atau API minimal. Itu sealed, terdaftar sebagai layanan transient oleh AddDoconut(), dan diresolusikan melalui injeksi konstruktor — jangan pernah membuatnya secara langsung.

Perpustakaan .NET Standard sebelumnya mengekspos konstruktor publik yang menerima cache memori, akses konteks HTTP, dan satu atau lebih jalur lisensi. Konstruktor itu sudah tidak ada; grafik layanan menyediakan ketergantungan tersebut.

Viewer tidak menyimpan status per-permintaan dan dengan sengaja tidak mengimplementasikan IDisposable: sesi dokumen hidup secara independen dalam cache sesi, sehingga membuang layanan tidak pernah dapat menutup dokumen yang terbuka (lihat Konsep Inti → Cara Kerja Penampil).

OpenDocumentAsync

Membuka sebuah dokumen dan mengembalikan token sesi yang digunakan widget klien untuk semua permintaan berikutnya. Setiap pembukaan bersifat asynchronous — tidak ada OpenDocument sinkron.

// Buka sederhana
string token = await viewer.OpenDocumentAsync(path);

// Dengan konfigurasi dan opsi per-format
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Dari unggahan
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Pengecualian yang harus ditangani:

• LicenseException — lisensi yang ditemukan ditolak (pesan menyertakan alasan penolakan), atau format membutuhkan kemampuan plugin yang tidak lagi diberikan. Kedaluwarsa kalender tanpa pesan penolakan beralih ke rendering berwatermark alih-alih melempar pengecualian.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — konten file rusak atau tidak cocok dengan ekstensi nya.

CloseDocument

void CloseDocument(string token)

Menghapus sesi dari cache (membuang mesin dokumen secara langsung), menghapus penanda keamanan, dan mencabut pemberian akses. Opsional — kedaluwarsa bergulir melakukan pembersihan yang sama — tetapi disarankan untuk dokumen besar.

GetPageCount

int GetPageCount(string token)

Total halaman dari sesi yang terbuka. Melempar pengecualian jika token tidak dikenal atau kedaluwarsa.

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Mengembalikan nama-nama lembar kerja dari spreadsheet yang terbuka, dalam urutan buku kerja, atau daftar kosong ketika dokumen terbuka bukan spreadsheet.

Hanya lembar kerja yang dirender yang terdaftar: lembar kerja tersembunyi dan kosong dikecualikan, dan ketika ExcelConfig.SheetNames membatasi rendering, hanya lembar kerja tersebut yang muncul. Sebuah lembar kerja tidak selalu satu halaman — yang sangat besar dirender melintasi beberapa halaman. Melempar pengecualian jika token tidak dikenal atau kedaluwarsa.

Ditambahkan pada 26.9.0.

Flag kemampuan

Gunakan ini dalam tampilan Razor untuk merender Ribbon berlisensi hanya ketika server benar‑benar menyediakannya — lihat Panduan Cepat.

DocOptions

Opsi per‑buka, independen format (namespace Doconut):

Kelas ini juga mengekspos properti khusus yang sengaja berada di luar alur tampilan satu‑host normal:

Watermark khusus

DocOptions.Watermark menggunakan enam bidang yang dipisahkan tilde. ^ opsional di awal meminta tata letak semua sudut:

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

Parser mengharapkan tepat enam bidang setelah ^ opsional. Definisi yang tidak valid akan digantikan oleh fallback Invalid Watermark yang terlihat dari SDK alih‑alih menghilang secara diam‑diam.

Keputusan lisensi

Keputusan yang sama diterapkan pada gambar halaman yang disajikan dan ekspor anotasi. Output GIF animasi ditandai frame per frame. Oleh karena itu, watermark khusus adalah fitur aplikasi berlisensi, bukan cara untuk mengganti atau menekan watermark penilaian.

API Anotasi

Pemuat anotasi sisi server dan ekspor. Panduan lengkapnya ada di Panduan → Anotasi; antarmukanya adalah:

Masing‑masing dari ini memerlukan token sesi. Bentuk GetAnnotationManager(pageWidth, pageHeight) yang bebas sesi pada pustaka sebelumnya tetap ada untuk membuat anotasi di luar sesi, tetapi memuatnya tetap memerlukan token.

Metadata DICOM

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

Metode ini ada untuk penyelarasan API, tetapi paket ini tidak dapat menyediakan tag DICOM teknis: pembaca metadata hanya tersedia dalam build .NET 8. Ia mengembalikan null untuk sesi DICOM dan non‑DICOM; pada sesi DICOM juga menulis peringatan satu kali yang menjelaskan keterbatasan platform. Rendering halaman, frame, dan animasi tetap didukung.

Pembantu Sumber Daya — ReferenceCss / ReferenceScripts

Keluarkan tag <link>/<script> untuk sumber daya tersemat yang disajikan oleh UseDoconutResources(), dalam urutan ketergantungan yang benar. Paket untuk fitur yang dibatasi lisensi seperti pencarian dan anotasi dikeluarkan hanya ketika lisensi mengaktifkannya, menjaga UI klien konsisten dengan perilaku server.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + penampil + pencarian + anotasi
string ReferenceScripts(ScriptConfig? config = null)

CssConfig bendera: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (dibatasi pencarian), IncludeAnnotationCss (dibatasi anotasi).

ScriptConfig bendera: IncludeJQuery (dibutuhkan oleh semua yang lain), IncludeBootstrap, IncludeViewerScripts (inti: docViewer.js + splitter + tautan), IncludeSearchScripts dan IncludeSearchBar (dibatasi pencarian), IncludeAnnotationScripts dan IncludeAnnotationBar (dibatasi anotasi).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

Pembantu ini adalah cara yang didukung untuk menyajikan sumber daya peramban. Aplikasi yang menyalin docViewer.js, documentLinks.js, dan docViewer.UI.js ke dalam wwwroot sebaiknya menghapus salinan tersebut setelah halaman dirender dari tag yang dikeluarkan.