Penampil
Kelas penampil dokumen utama
Viewer (namespace Doconut) adalah titik masuk publik untuk membuka dokumen dari kontroler MVC, halaman Web Forms, dan handler. Ini adalah layanan transient yang disusun oleh DoconutHost.Initialize; selesaikan di tempat Anda menggunakannya:
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() juga berfungsi setelah DoconutHost.Initialize dijalankan — ia menyelesaikan layanan yang sama — yang menjaga kode yang dimigrasikan dari paket klasik tetap dapat dikompilasi. Sebelum Initialize, ia melempar InvalidOperationException.
Viewer tidak menyimpan status dokumen per-permintaan dan dengan sengaja tidak mengimplementasikan IDisposable: sesi dokumen hidup secara independen darinya, sehingga membuang (disposing) sebuah Viewer tidak pernah dapat menutup dokumen yang terbuka (lihat Bagaimana Penampil Bekerja).
OpenDocumentAsync
Membuka sebuah dokumen dan mengembalikan token sesi yang digunakan widget untuk setiap permintaan selanjutnya. Ketika UnsafeMode berada dalam keadaan false (default), token diberikan ke sesi ASP.NET dari permintaan saat ini — panggil dari permintaan yang memiliki status sesi (lihat Sesi & Keamanan).
| 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 (sebuah unggahan, basis data, blob). fileInfo harus membawa ekstensi yang tepat — ia memilih formatnya |
// 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 (HttpPostedFileBase di MVC; HttpPostedFile di Web Forms)
using (var ms = new MemoryStream())
{
await file.InputStream.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}Pengecualian yang harus ditangani:
LicenseException— sebuah lisensi ditemukan tetapi ditolak (pesan membawa alasannya), atau format membutuhkan kemampuan plugin yang tidak diberikan oleh lisensi.FormatNotSupportedException— tidak ada penampil yang menangani ekstensi file.InvalidDataException— konten rusak atau tidak cocok dengan ekstensi nya.
OpenDocument (sinkron)
Untuk kode-behind Web Forms dan kode lain yang tidak menggunakan halaman asinkron:
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)Setiapnya mengembalikan token dan juga menyimpannya di viewer.Token. fileName harus membawa ekstensi yang tepat. Pembungkus ini aman dipanggil dari halaman Web Forms: jalur pembukaan tidak pernah melanjutkan pada konteks permintaan ASP.NET, sehingga menunggu tidak dapat menyebabkan deadlock. Hal yang sama tidak berlaku untuk setiap API Doconut asinkron — lihat bagian Web Forms dari Plugin Konverter.
TutupDokumen
void CloseDocument(string token)Menghapus sesi (melepaskan mesin dokumen secara langsung), menghapus hak token dari sesi ASP.NET permintaan saat ini, dan mencabut token. Opsional — kedaluwarsa bergulir melakukan pembersihan yang sama — tetapi disarankan untuk dokumen besar.
Kueri Sesi
| Anggota | Mengembalikan |
|---|---|
int GetPageCount(string token) | Total halaman dokumen yang terbuka |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | Ukuran halaman yang dirender secara default pada zoom 100 % — ruang koordinat untuk anotasi yang dibangun dalam kode |
IReadOnlyList<string> GetWorksheetNames(string token) | Lembar kerja yang dirender pada spreadsheet, dalam urutan buku kerja; kosong untuk dokumen lain |
Setiap pemanggilan melempar InvalidOperationException (Document session not found. Please re-open document.) jika token tidak dikenal atau kedaluwarsa, dan ArgumentException untuk token kosong.
Opsi Dokumen
Opsi per‑buka, independen format (namespace Doconut):
| Tipe | Properti | Default | Deskripsi |
|---|---|---|---|
string | Password | "" | Kata sandi untuk dokumen yang dilindungi (disalin ke konfigurasi format secara otomatis). |
string | Watermark | "" | Teks watermark khusus yang digambar pada halaman yang dirender — lihat di bawah. |
int | TimeOut | 60 | Kedaluwarsa sesi bergulir, dalam menit. |
string | BrowserId | "" | Web farm: browser yang menjadi ikatan tiket yang ditandatangani. Atur dengan DoconutFarmBinding.EnsureBrowserId (lihat Sesi & Keamanan). |
string | UserId | "" | Web farm: pengguna yang masuk yang menjadi ikatan tiket, dari DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | Usang. Atur ImageResolution pada konfigurasi format sebagai gantinya. |
bool | IsSecured | true | Dipesan; tidak ditegakkan. Kontrol akses adalah DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | Dipertahankan untuk kode yang dimigrasikan dari paket klasik. Mereka tidak mengaktifkan mode farm — AddDoconutDistributed yang melakukannya. |
bool | EditMode | false | Dipesan untuk editor yang didistribusikan secara terpisah; biarkan false. |
Watermark Kustom
DocOptions.Watermark menerima 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 |
|---|---|---|
^ di depan | ^ | Tata letak semua sudut opsional. Tanpa ini, penempatan normal digunakan. |
| Text | Confidential | Teks yang digambar pada setiap halaman. Tidak boleh kosong. |
| Color | Red | Warna yang dinamai. |
| FontSize | 24 | Ukuran font; masukan numerik tidak valid akan kembali ke nilai default. |
| FontName | Verdana | Keluarga font. Harus terpasang di server — Windows Server memiliki lebih sedikit font dibandingkan desktop. |
| Opacity | 80 | 0 hingga 255. Harus dapat diparse. |
| Angle | -45 | Rotasi dalam derajat; masukan numerik tidak valid akan kembali ke nilai default. |
Parser mengharapkan tepat enam bidang setelah ^ opsional. Definisi yang tidak valid digantikan dengan teks Invalid Watermark yang terlihat 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 |
| Lisensi Sementara/Demo yang aktif | Tidak | Halaman bersih |
| Lisensi Sementara/Demo yang aktif | Ya | Watermark khusus |
| Lisensi yang hilang, ditolak, kedaluwarsa, versi salah, atau domain tidak valid | Apa saja | Watermark evaluasi; nilai khusus tidak menggantikannya |
API Anotasi
Pemuat anotasi sisi server dan ekspor. Panduan lengkap ada di Anotasi.
| 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 amplop terenkode 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 tertanam |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | Satu PNG per halaman, anotasi tertanam, ditulis ke directoryPath (dibuat jika tidak ada); mengembalikan jumlah gambar yang ditulis |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP berisi PNG per halaman dengan anotasi tertanam |
Metadata DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Pada paket ini selalu mengembalikan null, dan permintaan metadata widget menjawab 501 Not Implemented: membaca tag DICOM tidak tersedia pada .NET Framework. rendering DICOM — halaman, bingkai, dan animasi — berfungsi. Lihat Plugin DICOM.
Pembantu Sumber Daya — ReferenceCss / ReferenceScripts
Keluarkan tag <link> dan <script> untuk sumber daya yang disajikan modul sumber daya di bawah DoconutOptions.ResourcesPath, dalam urutan ketergantungan. Berkas untuk fitur yang dibatasi lisensi (Search, Annotation) dikeluarkan hanya ketika lisensi memberikannya.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // status lisensi, untuk melindungi kode init ribbon
bool IsAnnotationEnabled { get; }CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (dibatasi pencarian), IncludeAnnotationCss (dibatasi anotasi).
ScriptConfig flags: IncludeJQuery (dibutuhkan oleh semua yang lain), IncludeBootstrap, IncludeViewerScripts (skrip penampil inti), 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).
Keduanya mengembalikan HTML: tulis mereka dengan @Html.Raw(...) di MVC 5 (hasilkan di controller — tampilan tidak memiliki @inject) atau <%= %> di Web Forms. Panduan Cepat menunjukkan keduanya.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)Mengembalikan blok <script> yang menginisialisasi widget pada elemen dengan id elementId dan menampilkan dokumen: docViewer({...}) dibangun dari ViewerConfig (default: BasePath: '/', ResPath: 'doconut-res/images'), kemudian .View(token). Tulis setelah skrip penampil. Skrip yang dihasilkan tidak menyimpan referensi ke objek penampil, sehingga halaman dengan toolbar sendiri harus menginisialisasi widget secara manual. Lihat KonfigurasiPenampil.
Web farm
string? AccessToken menyimpan tiket yang ditandatangani yang dikeluarkan oleh pembukaan terakhir ketika mode terdistribusi aktif dan UnsafeMode adalah false; ia adalah null pada satu server. Kirimkan ke widget dengan token: objViewer.View(token, accessToken).
Apakah halaman ini membantu?