Penampil Doconut adalah perpustakaan .NET untuk menampilkan dokumen yang dirancang untuk menempatkan PDF, Office, CAD, gambar, dan keluarga dokumen lain yang didukung di dalam sebuah aplikasi. Integrasi Doconut yang baik lebih menekankan pada pemilihan batas yang bersih antara aplikasi Anda, penampil, dan peramban, bukan sekadar menemukan potongan kode terpendek.

Pratinjau dokumen yang disematkan diatur dalam ruang kerja aplikasi web terstruktur

Pusat dokumentasi Doconut menautkan ke jalur pengaturan yang dipelihara untuk tipe proyek .NET yang didukung. Gunakan panduan yang cocok dengan versi yang terpasang di aplikasi Anda, lalu perlakukan halaman sekeliling, pemeriksaan identitas, dan alur kerja akses sebagai kode aplikasi yang dimiliki tim Anda.

Mulai dengan Batas Integrasi

Ada tiga cara umum untuk menempatkan pratinjau dokumen dalam sebuah produk. Pilihan yang tepat tergantung pada siapa yang mengelola navigasi, autentikasi, dan siklus hidup penampil.

Pola	Cocok Terbaik	Pertukaran Utama
Tampilan aplikasi	Halaman .NET yang menampilkan penampil di samping kontrol produk	Integrasi ketat, tetapi siklus hidup halaman dan penampil terhubung
Iframe milik aplikasi	Portal yang membutuhkan isolasi antara UI host dan rute pratinjau	Batas yang jelas, tetapi komunikasi harus dirancang secara eksplisit
Komponen kerangka kerja di sekitar rute server	Shell React, Angular, atau Vue yang didukung oleh aplikasi .NET	Komposisi front-end yang familiar, dengan lebih banyak status siklus hidup yang harus dikelola

Pola iframe tidak harus menunjuk ke URL dokumen publik. Ia dapat menunjuk ke rute yang diautentikasi dalam aplikasi Anda sendiri. Rute tersebut dapat memverifikasi akses dan merender halaman penampil tanpa mengekspos jalur penyimpanan ke halaman host.

Bangun Permukaan Pratinjau yang Stabil dan Responsif

Jangan membangun ulang markup penampil atau inisialisasi dari potongan blog ilustratif. Doconut menerbitkan berkas, langkah middleware, namespace, dan pengaturan penampil yang sesuai untuk setiap lini .NET yang didukung. Misalnya, panduan resmi .NET 6 atau lebih tinggi menjelaskan middleware server, objek penampil, opsi dokumen, konfigurasi rendering, dan aset klien yang diperlukan.

Gunakan materi berversi tersebut untuk membuat penampil, lalu berikan wilayah hostnya lebar dan tinggi yang stabil dalam tata letak Anda. Sisakan ruang yang cukup sebelum memuat sehingga halaman sekeliling tidak melompat, dan uji toolbar serta halaman pertama pada breakpoint nyata yang didukung produk Anda.

Sebelum berkomitmen pada sebuah komposisi, bandingkan dengan demo langsung Doconut resmi. Demo tersebut mencakup berbagai gaya integrasi .NET dan front‑end, termasuk contoh iframe khusus, dan membantu membedakan jalur yang secara resmi didukung dari potongan kode yang tampak masuk akal.

Simpan Keputusan Akses di Server

Halaman host tidak boleh memutuskan apakah seorang pengguna dapat melihat dokumen. Sebelum merender rute pratinjau, aplikasi harus:

Mengautentikasi permintaan.
Mengotorisasi pengguna untuk dokumen dan tenant yang diminta.
Menyelesaikan dokumen melalui pengenal yang dikontrol server.
Membukanya melalui penampil hanya setelah pemeriksaan tersebut lolos.
Mengembalikan status tidak ditemukan atau terlarang secara generik tanpa membocorkan detail penyimpanan.

Pengidentifikasi opak meningkatkan kebersihan URL, tetapi bukan otorisasi. Terapkan pemeriksaan yang sama pada permintaan halaman, thumbnail, pencarian, anotasi, ekspor, dan cetak yang Anda ekspos.

Tentukan Cara Host dan Penampil Berkomunikasi

Tampilan aplikasi dapat memanggil komponennya secara langsung. Iframe membutuhkan kontrak yang lebih sempit. Definisikan hanya peristiwa yang benar‑benar dibutuhkan host, seperti:

Pratinjau siap
Dokumen gagal dibuka
Halaman saat ini berubah
Sesi kedaluwarsa
Pengguna meminta menutup pratinjau

Jika Anda menggunakan postMessage, validasi baik event.origin maupun bentuk pesan. Jangan menerima asal liar di produksi, dan jangan pernah mengirim kredensial, lokasi penyimpanan, atau konten dokumen mentah melalui pesan.

Perlakukan Pembatasan Browser sebagai Pertahanan Berlapis

Iframe tidak otomatis terisolasi. Atribut sandbox dapat mengurangi kemampuan, tetapi nilai yang terlalu ketat juga dapat memutus skrip penampil, unduhan, atau perilaku same‑origin. Mulailah dari set kemampuan terkecil yang didokumentasikan untuk integrasi Anda dan uji bersama Content Security Policy Anda.

Juga tinjau:

frame-ancestors atau X-Frame-Options untuk rute pratinjau
frame-src untuk halaman host
Perilaku cookie same‑site jika iframe memerlukan sesi
Kebijakan referrer untuk URL yang mengandung pengenal routing
Header cache untuk halaman yang menampilkan materi sensitif

Kontrol ini menjadi milik aplikasi dan infrastruktur di sekelilingnya. Komponen penampil tidak dapat memilih kebijakan yang tepat untuk tenancy dan model ancaman Anda.

Rancang Status Memuat, Kesalahan, dan Kedaluwarsa

Persegi panjang kosong bukanlah pesan kesalahan yang berguna. Berikan halaman host status eksplisit untuk kegagalan otorisasi, input tidak didukung, berkas rusak, batas waktu, dan sesi kedaluwarsa. Jaga agar teksnya dapat ditindaklanjuti tanpa mengungkap jalur internal atau detail pengecualian.

Untuk dokumen panjang, pertahankan kontainer penampil sementara halaman pertama dipersiapkan. Jika pengguna dapat beralih dokumen tanpa meninggalkan halaman, batalkan permintaan usang dan reset judul yang terlihat, jumlah halaman, serta fokus sebelum memuat item berikutnya.

Aksesibilitas dan Perilaku Keyboard

Berikan setiap iframe title yang berguna. Buat pratinjau dapat diakses melalui keyboard, sediakan cara yang terlihat untuk mengembalikan fokus ke halaman host, dan jangan menjebak fokus di dalam overlay khusus. Jika penampil memiliki pintasan keyboard sendiri, dokumentasikan konflik dengan pintasan yang dipakai oleh shell produk Anda.

Fallback yang dapat diakses dapat menawarkan unduhan terkontrol atau representasi alternatif ketika aturan bisnis Anda mengizinkannya. Jangan menambahkan tautan berkas publik hanya sebagai fallback.

Daftar Periksa Verifikasi Praktis

Sebelum rilis, verifikasi jalur permintaan lengkap, bukan hanya pemuatan halaman awal:

Pengguna yang berotorisasi dapat membuka dokumen yang diizinkan.
Pengguna dari tenant lain tidak dapat menggunakan kembali URL pratinjau.
Permintaan langsung ke endpoint terkait penampil menerima pemeriksaan otorisasi yang sama.
Penyegaran, navigasi kembali, dan kedaluwarsa sesi menghasilkan status yang dapat dipahami.
Pratinjau tetap dapat digunakan pada ukuran viewport dan tingkat zoom yang didukung.
Kesalahan konsol peramban dan permintaan jaringan yang gagal terlihat dalam pemantauan.
Log penyimpanan dan aplikasi tidak mencatat rahasia atau URL dokumen lengkap.

Kesimpulan

Integrasi Doconut yang paling dapat dipelihara adalah yang memiliki kontrak kecil dan eksplisit. Biarkan Doconut menangani peran penampilan dokumen sebagaimana dijelaskan dalam dokumentasi berversi, sementara aplikasi Anda mengelola identitas, otorisasi, routing, retensi, kebijakan peramban, dan umpan balik pengguna. Ketika Anda siap mengevaluasi contoh paket secara lokal, gunakan sumber unduhan Doconut resmi alih‑alih menyalin sumber dari artikel yang tidak terkait.