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.
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 menghentikan dokumen yang terbuka (lihat Core Concepts → How the Viewer Works).
OpenDocumentAsync
Membuka dokumen dan mengembalikan token sesi yang digunakan widget klien untuk semua permintaan selanjutnya.
| Overload | Gunakan 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 memerlukan 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 |
// 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 beralih ke rendering berwatermark alih-alih melempar pengecualian.FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— konten file rusak atau tidak cocok dengan ekstensi.
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 InvalidOperationException (Document session not found. Please re-open document.) jika token tidak dikenal atau kedaluwarsa, dan ArgumentException untuk token kosong.
GetPageDimensions
(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.
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 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.
Bendera kemampuan
| Anggota | Makna |
|---|---|
bool IsSearchEnabled | Lisensi saat ini memberikan Search |
bool IsAnnotationEnabled | Lisensi saat ini memberikan Annotation |
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):
| Tipe | Properti | Bawaan | Deskripsi |
|---|---|---|---|
string | Password | "" | Kata sandi untuk dokumen yang dilindungi (disalin ke konfigurasi format secara otomatis). |
int | ImageResolution | 0 | Usang. Disimpan hanya untuk kompatibilitas — set ImageResolution pada konfigurasi format sebagai gantinya. |
string | Watermark | "" | 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". |
int | TimeOut | 60 | Kadaluarsa sesi bergulir dalam menit. |
bool | IsSecured | true | Tidak sedang ditegakkan — 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:
| Tipe | Properti | Bawaan | Deskripsi |
|---|---|---|---|
bool | IsWebFarm | false | Usang — tidak berpengaruh. Publikasikan dokumen dengan DistributedDocumentPublisher.PublishAsync (atau IDistributedPublishQueue.EnqueueAsync) dan set FileShareConfig.RootPath sebagai gantinya. |
string | WebFarmPath | "" | Usang — tidak berpengaruh. Gunakan FileShareConfig.RootPath sebagai gantinya. |
bool | EditMode | false | Cadangan untuk alur kerja Editor yang didistribusikan secara terpisah; biarkan false untuk penampil standar. |
Watermark khusus
DocOptions.Watermark menggunakan enam bidang yang dipisahkan tilde. ^ opsional di awal meminta tata letak semua sudut:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Bidang | Contoh | Makna |
|---|---|---|
Awalan ^ | ^ | Tata letak semua sudut opsional. Tanpa itu, penempatan watermark normal digunakan. |
| Teks | Confidential | Teks yang dirender pada setiap halaman. Tidak boleh kosong. |
| Warna | Red | Warna bernama yang dipahami oleh lapisan gambar. |
| UkuranFont | 24 | Ukuran font; input numerik tidak valid akan kembali ke default perender. |
| NamaFont | Verdana | Keluarga font yang diminta. Pastikan font tersebut terpasang di lingkungan penyebaran. |
| Opasitas | 80 | Nilai byte dari 0 hingga 255. Harus dapat diurai dengan sukses. |
| Sudut | -45 | Sudut rotasi dalam derajat; input numerik tidak valid akan kembali ke default. |
Parser mengharapkan tepat enam bidang setelah ^ opsional. Definisi tidak valid akan diganti oleh fallback Invalid Watermark yang terlihat dari SDK alih‑alih menghilang secara diam‑diam.
Keputusan lisensi
| Status lisensi | Nilai khusus disediakan | Hasil yang dirender |
|---|---|---|
| Lisensi penampil berbayar yang valid | Tidak | Halaman bersih |
| Lisensi penampil berbayar yang valid | Ya | Watermark khusus |
| Penampil dasar Sementara/Demo yang aktif | Tidak | Halaman penampil dasar bersih |
| Penampil dasar Sementara/Demo yang aktif | Ya | Watermark khusus ketika jalur penampil dasar bersih diterapkan |
| Lisensi yang hilang, ditolak, kedaluwarsa, versi salah, atau domain tidak valid | Salah satu | Watermark penegakan/evaluasi; nilai khusus tidak menggantikannya |
| Rendering plugin di bawah aturan evaluasi | Salah satu | Watermark evaluasi |
Keputusan yang sama diterapkan pada gambar halaman yang disajikan dan ekspor anotasi. Output GIF animasi dicap frame per frame. Oleh karena itu, watermark khusus adalah fitur aplikasi berlisensi, bukan cara untuk mengganti atau menekan watermark evaluasi.
API Anotasi
Memuat anotasi sisi server dan mengekspor. Panduan lengkap ada di Panduan → Anotasi; antarmukanya adalah:
| Anggota | Tujuan |
|---|---|
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/ampul 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 tersemat |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Satu PNG per halaman, anotasi tersemat, 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 tersemat |
Metadata DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Metode ini ada untuk penyelarasan API, tetapi penampil DICOM .NET 6 tidak dapat menyediakan tag teknis. Metode ini mengembalikan null untuk sesi DICOM dan non-DICOM; pada sesi DICOM juga menulis peringatan satu kali yang menjelaskan batasan platform. Rendering halaman, bingkai, 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), EmitFeatureFlags (default true: juga menulis skrip inline window.Doconut.features = { search, annotation, editor }; atur ke false di bawah Content-Security-Policy yang memblokir skrip inline).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))Apakah halaman ini membantu?