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:

csharp
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).

OverloadGunakan 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
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 (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:

text
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

text
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

AnggotaMengembalikan
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):

TipePropertiDefaultDeskripsi
stringPassword""Kata sandi untuk dokumen yang dilindungi (disalin ke konfigurasi format secara otomatis).
stringWatermark""Teks watermark khusus yang digambar pada halaman yang dirender — lihat di bawah.
intTimeOut60Kedaluwarsa sesi bergulir, dalam menit.
stringBrowserId""Web farm: browser yang menjadi ikatan tiket yang ditandatangani. Atur dengan DoconutFarmBinding.EnsureBrowserId (lihat Sesi & Keamanan).
stringUserId""Web farm: pengguna yang masuk yang menjadi ikatan tiket, dari DoconutFarmBinding.ResolveUserId.
intImageResolution0Usang. Atur ImageResolution pada konfigurasi format sebagai gantinya.
boolIsSecuredtrueDipesan; tidak ditegakkan. Kontrol akses adalah DoconutOptions.UnsafeMode.
boolIsWebFarm / string WebFarmPathfalse / ""Dipertahankan untuk kode yang dimigrasikan dari paket klasik. Mereka tidak mengaktifkan mode farm — AddDoconutDistributed yang melakukannya.
boolEditModefalseDipesan 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
^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
^ di depan^Tata letak semua sudut opsional. Tanpa ini, penempatan normal digunakan.
TextConfidentialTeks yang digambar pada setiap halaman. Tidak boleh kosong.
ColorRedWarna yang dinamai.
FontSize24Ukuran font; masukan numerik tidak valid akan kembali ke nilai default.
FontNameVerdanaKeluarga font. Harus terpasang di server — Windows Server memiliki lebih sedikit font dibandingkan desktop.
Opacity800 hingga 255. Harus dapat diparse.
Angle-45Rotasi 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 lisensiNilai khusus disediakanHasil yang dirender
Lisensi penampil berbayar yang validTidakHalaman bersih
Lisensi penampil berbayar yang validYaWatermark khusus
Lisensi Sementara/Demo yang aktifTidakHalaman bersih
Lisensi Sementara/Demo yang aktifYaWatermark khusus
Lisensi yang hilang, ditolak, kedaluwarsa, versi salah, atau domain tidak validApa sajaWatermark evaluasi; nilai khusus tidak menggantikannya

API Anotasi

Pemuat anotasi sisi server dan ekspor. Panduan lengkap ada di Anotasi.

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

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

text
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

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