Penampil

Kelas penampil dokumen utama

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, aksesori konteks HTTP, dan satu atau lebih jalur lisensi. Konstruktor itu sudah tidak ada; grafik layanan menyediakan ketergantungan tersebut.

Viewer tidak menyimpan status per-permintaan apa pun 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.

Beban LebihGunakan ketika
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Membuka dari disk dengan deteksi format otomatis dan konfigurasi default format
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Anda membutuhkan opsi rendering per-format (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)Dokumen bukan file di disk (unggahan, basis data, blob). fileInfo harus membawa ekstensi yang benar — itu mengarahkan deteksi format
csharp
// 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 membawa alasan penolakan), atau format membutuhkan kemampuan plugin yang tidak lagi diberikan. Kedaluwarsa kalender tanpa pesan penolakan menurunkan menjadi rendering berwatermark alih-alih melempar pengecualian.
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — konten file rusak atau tidak cocok dengan ekstensi file.

CloseDocument

text
void CloseDocument(string token)

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

GetPageCount

text
int GetPageCount(string token)

Total halaman dari sesi yang terbuka. Melempar InvalidOperationException (Document session not found. Please re-open document.) jika token tidak dikenal atau kedaluwarsa, dan ArgumentException untuk token kosong.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

Ukuran halaman default yang dirender dokumen pada zoom 100% — ruang koordinat untuk anotasi yang dibangun dalam kode. page diterima untuk kompatibilitas; hasilnya adalah default dokumen. Melempar InvalidOperationException (Document session not found. Please re-open document.) jika token tidak dikenal atau kedaluwarsa, dan ArgumentException untuk token kosong.

DapatkanNamaLembarKerja

text
IReadOnlyList<string> GetWorksheetNames(string token)

Mengembalikan nama-nama lembar kerja dari spreadsheet yang terbuka, dalam urutan buku kerja, atau daftar kosong bila dokumen yang 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 ke beberapa halaman. Melempar InvalidOperationException (Document session not found. Please re-open document.) jika token tidak dikenal atau kedaluwarsa, dan ArgumentException untuk token kosong.

Ditambahkan pada 26.9.0.

Flag kemampuan

AnggotaArti
bool IsSearchEnabledLisensi saat ini memberikan Search
bool IsAnnotationEnabledLisensi saat ini memberikan Annotation

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

Opsi Dokumen

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

TipePropertiBawaanDeskripsi
stringPassword""Kata sandi untuk dokumen yang dilindungi (disalin ke dalam konfigurasi format secara otomatis).
intImageResolution0Usang. Disimpan hanya untuk kompatibilitas — setel ImageResolution pada konfigurasi format sebagai gantinya.
stringWatermark""Teks watermark khusus yang digambar pada halaman yang dirender. String format: "^Text~Color~FontSize~FontName~Opacity~Angle", misalnya "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Kadaluarsa sesi bergeser dalam menit.
boolIsSecuredtrueTidak diterapkan saat ini — cadangan. Pengikatan token dikendalikan secara global oleh DoconutOptions.UnsafeMode (lihat Konsep Inti → Sesi & Keamanan).

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

TipePropertiBawaanDeskripsi
boolIsWebFarmfalseUsang — tidak berpengaruh. Publikasikan dokumen dengan DistributedDocumentPublisher.PublishAsync (atau IDistributedPublishQueue.EnqueueAsync) dan setel FileShareConfig.RootPath sebagai gantinya. Perhatikan penulisan huruf — perpustakaan sebelumnya menuliskan ini sebagai IsWebfarm.
stringWebFarmPath""Usang — tidak berpengaruh. Gunakan FileShareConfig.RootPath, seperti dijelaskan dalam Penyebaran Terdistribusi. Sebelumnya ditulis sebagai WebfarmPath.
boolEditModefalseCadangan untuk alur kerja penyuntingan yang didistribusikan secara terpisah; biarkan false untuk penampil standar.

Watermark Kustom

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

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
BidangContohMakna
Awalan ^^Tata letak semua sudut opsional. Tanpa itu, penempatan watermark normal digunakan.
TextConfidentialTeks yang dirender pada setiap halaman. Tidak boleh kosong.
ColorRedWarna bernama yang dipahami oleh lapisan gambar.
FontSize24Ukuran font; input numerik yang tidak valid akan kembali ke default perender.
FontNameVerdanaKeluarga font yang diminta. Pastikan font tersebut terpasang di lingkungan penyebaran.
Opacity80Nilai byte dari 0 hingga 255. Harus dapat diurai dengan sukses.
Angle-45Sudut rotasi dalam derajat; input numerik tidak valid akan kembali ke nilai default.

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

Keputusan Lisensi

Status lisensiNilai khusus disediakanHasil render
Lisensi penampil berbayar yang validTidakHalaman bersih
Lisensi penampil berbayar yang validYaWatermark khusus
Penampil dasar Sementara/Demo yang aktifTidakHalaman penampil dasar bersih
Penampil dasar Sementara/Demo yang aktifYaWatermark khusus ketika jalur penampil dasar bersih diterapkan
Lisensi hilang, ditolak, kedaluwarsa, versi salah, atau domain tidak validBaikWatermark penegakan/evaluasi; nilai khusus tidak menggantikannya
Rendering plugin di bawah aturan evaluasiBaikWatermark evaluasi

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

API Anotasi

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

AnggotaTujuan
AnnotationManager GetAnnotationManager(string token)Manajer yang terikat pada dimensi halaman sesi terbuka
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Manajer dengan dimensi halaman eksplisit
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Manajer independen sesi
void LoadAnnotationData(string token, AnnotationManager manager)Muat anotasi yang dibangun dalam C# ke dalam sesi
void LoadAnnotationData(string token, string annotationData)Muat anotasi dari halaman yang dienkode/amplop Base64 yang dikembalikan oleh AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Muat anotasi dari XML
XmlDocument GetAnnotationXML(string token)Ekspor anotasi sesi sebagai XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF dengan anotasi terintegrasi
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Satu PNG per halaman, anotasi terintegrasi, ditulis ke directoryPath (dibuat jika tidak ada); mengembalikan jumlah gambar yang ditulis
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP PNG per halaman dengan anotasi terintegrasi

Setiap yang ini memerlukan token sesi. Bentuk GetAnnotationManager(pageWidth, pageHeight) bebas sesi dari pustaka sebelumnya tetap ada untuk membangun anotasi di luar sesi, tetapi memuatnya masih memerlukan token.

Metadata DICOM

text
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 menyertakan 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

Emisi 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 dihasilkan hanya ketika lisensi mengaktifkannya, menjaga UI klien konsisten dengan perilaku server.

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

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

ScriptConfig flags: IncludeJQuery (dibutuhkan oleh semua yang lain), IncludeBootstrap, IncludeViewerScripts (inti: docViewer.js + splitter + tautan), IncludeSearchScripts dan IncludeSearchBar (dibatasi pencarian), IncludeAnnotationScripts dan IncludeAnnotationBar (dibatasi anotasi), EmitFeatureFlags (default true: juga menulis skrip inline window.Doconut.features = { search, annotation, editor }; setel ke false di bawah Content-Security-Policy yang memblokir skrip inline).

html
@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 menyampaikan sumber daya browser. Aplikasi yang menyalin docViewer.js, documentLinks.js, dan docViewer.UI.js ke dalam wwwroot harus menghapus salinan tersebut setelah halaman dirender dari tag yang dihasilkan.

Apakah halaman ini membantu?