ViewerConfig

Opsi widget penampil klien

ViewerConfig (namespace Doconut) menjelaskan tampilan dan perilaku penampil browser. Itu tidak memengaruhi kualitas rendering dokumen; gunakan konfigurasi format untuk itu. Kelas C# dan widget JavaScript yang telah lama ada memiliki nilai default yang berbeda, jadi petakan nilai secara eksplisit.

Dua perubahan sisi klien dalam rilis ini gagal secara diam-diam. Fungsi penangan diteruskan sebagai opsi — widget tidak lagi mengambil callback acara dari id kontainer — dan ResPath harus menunjuk ke awalan sumber daya alih-alih akar aplikasi. Kedua hal tersebut membuat server berfungsi sempurna dan tidak melaporkan apa pun di konsol browser. Jika Anda membawa halaman dari perpustakaan sebelumnya, baca Callback dan Daftar periksa jalur sebelum hal lain.

Properti C#

TipePropertiBawaanDeskripsi
boolShowThumbstrueTampilkan panel thumbnail.
boolAutoLoadfalseMuat secara otomatis setelah inisialisasi. Alur token normal memanggil View(token) secara eksplisit.
boolAutoFocustruePindahkan fokus/gulir browser ke penampil selama inisialisasi.
boolAutoPageFocustruePertahankan thumbnail saat ini terlihat saat halaman berubah.
intPageZoom100Persentase zoom awal.
intZoomStep10Persentase yang ditambah atau dikurangi oleh perintah zoom.
intMaxZoom300Persentase zoom maksimum.
boolShowToolTiptrueTampilkan tooltip posisi halaman saat menggulir.
stringToolTipPageText"Page "Awalan yang digunakan dalam tooltip halaman.
boolCacheEnabledfalsePertahankan jendela bergerak gambar halaman dalam memori browser. Itu tidak menggunakan localStorage.
boolLargeDocfalseTambahkan elemen halaman dalam batch berwaktu untuk dokumen besar.
boolShowHyperlinksfalseRender overlay hyperlink ketika konfigurasi server mengekstraknya.
boolFixedZoomtrueGunakan persentase zoom tetap alih-alih perhitungan ulang responsif.
intFixedZoomPercent100Zoom desktop tetap.
intFixedZoomPercentMobile75Zoom seluler tetap.
stringBasePath"/"Tempat penampil mengirim permintaan halaman. "/" adalah DocImage.axd di akar situs; jika tidak, cabang tempat host memetakan UseDoconut(), tanpa awalan / ("doconut" berarti /doconut/DocImage.axd).
stringResPath"doconut-res/images" (26.9.0; "doconut-res" sebelum)Folder tempat widget memuat gambar sendiri: folder images di bawah ResourcesPath, tanpa awalan /.
stringFitType"width""width", "height", atau kosong untuk tidak ada penyesuaian otomatis. "page" tidak diterima oleh widget saat ini.
boolRetryOn409falseAktifkan polling ketika produksi halaman asinkron/terdistribusi merespons 202 Accepted; 409 juga diterima untuk kompatibilitas dengan server lama. Tidak diperlukan oleh penampil sinkron normal.
csharp
var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // tidak ada '/' di depan: penampil menambahkannya ("/doconut" akan menjadi //doconut, host lain)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

Pemetaan C# ke JavaScript

Jangan mengirim ViewerConfig yang diserialkan langsung ke docViewer(...). Kebanyakan kunci widget menggunakan camelCase, sementara tiga kunci path/fit yang sudah mapan menggunakan PascalCase.

C#JavaScript
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

Pengaturan Bawaan JavaScript

Widget memiliki default lama yang berbeda dari kelas C#. Nilai berikut berasal dari implementasi docViewer.js saat ini.

OpsiDefaultCatatan
leftMinWidth / leftMaxWidth220 / 800Batas lebar panel thumbnail.
showThumbstrueVisibilitas thumbnail awal.
autoFocus / autoPageFocustrue / falseautoPageFocus berbeda dari default C#.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10Geometri thumbnail dalam piksel.
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom berbeda dari C# (300).
showToolTip / toolTipPageTexttrue / "Page "Tooltip posisi halaman.
format / doc / AccessToken"" / 0 / ""Nilai inisialisasi internal; biasanya diisi oleh View(token).
debugModefalseDiagnostik klien tambahan.
FitType""Tidak ada penyesuaian otomatis kecuali disediakan.
BasePath"DocImage.axd"Default klien historis dipertahankan untuk kompatibilitas. Host ASP.NET Core saat ini harus mengaturnya secara eksplisit ke cabang middleware yang dipetakan.
ResPath""Atur secara eksplisit ke jalur gambar tersemat.
cacheEnabled / cacheCount / cacheDelayfalse / 3 / 3Jendela dan penundaan preloading halaman dalam memori.
autoLoadfalseAlur token eksplisit disarankan.
largeDoctrueBerbeda dari default C#.
fixedZoomfalseBerbeda dari default C#.
fixedZoomPercent / fixedZoomPercentMobile100 / 50Nilai seluler berbeda dari C# (75).
showHyperlinkstrueMembutuhkan ekstraksi sisi server untuk menghasilkan overlay.

Setel semua nilai penting perilaku alih-alih bergantung pada salah satu set default:

html
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    autoFocus: true,
    autoPageFocus: true,
    pageZoom: 100,
    zoomStep: 10,
    maxZoom: 300,
    FitType: 'width',
    cacheEnabled: false,
    largeDoc: false,
    showHyperlinks: true,
    fixedZoom: true,
    fixedZoomPercent: 100,
    fixedZoomPercentMobile: 75,
    BasePath: 'doconut',
    ResPath: 'doconut-res/images',
    onViewerReady: function () {},
    onError: function (message) { console.error('DocViewer:', message); }
});
</script>

Panggilan Balik

CallbackArgumenTujuan
onPageLoadingpageNumPermintaan halaman sedang dimulai.
onPageLoadedpageNumGambar halaman selesai dimuat.
onThumbnailClickedpageNumPengguna memilih thumbnail.
onPageClickedpageNumPengguna memilih halaman.
onDoubleClicknonePenampil menerima klik ganda.
onViewerBusynonePenampil masuk ke status sibuk.
onViewerReadynoneInisialisasi selesai.
onViewerErrornonePenampil masuk ke status error.
onErrormessageOperasi mengembalikan pesan error.
onCopydataData salinan teks tersedia.
onAutoLoadStatuspageNumPemuat otomatis melanjutkan ke halaman.
onThumbsShownnonePanel thumbnail menjadi terlihat.
onAnnLoadednoneData anotasi dimuat.
onAnnSavednoneData anotasi disimpan.
onAnnSaveErrornonePenyimpanan anotasi gagal.
onAnnClosednoneUI anotasi ditutup.

Jaga callback tetap cepat; kirim telemetry secara asynchronous dan jangan memblokir rendering halaman.

Semua ini adalah opsi pada objek init. Penampil sebelumnya mencari fungsi global yang namanya diambil dari id kontainer — sebuah halaman dengan <div id="div_ctlDoc"> hanya perlu mendeklarasikan function ctlDoc_OnViewerReady(). Pencarian itu sudah tidak ada. Berikan fungsi secara eksplisit:

javascript
function ctlDoc_OnViewerBusy() { /* tampilkan indikator sibuk Anda */ }
function ctlDoc_OnViewerReady() { /* sembunyikan */ }
function ctlDoc_Copy(text) { /* gunakan teks yang disalin */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* laporkan kemajuan */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... opsi yang ada ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // ditemukan berdasarkan nama
    onViewerReady:    ctlDoc_OnViewerReady,     // ditemukan berdasarkan nama
    onCopy:           ctlDoc_Copy,              // adalah ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // adalah ctlDoc_AutoLoadStatus(page)
});

Pencarian lama dibungkus dalam catch kosong, sehingga tidak ada yang pernah dilaporkan. Pada rilis ini fungsi-fungsi tidak pernah dijalankan: gejala biasanya adalah spinner sibuk yang tidak pernah berhenti, karena penangan yang menyembunyikannya adalah onViewerReady. Dokumen di belakangnya dirender dengan benar.

Dua hook penyimpanan anotasi masih dicari berdasarkan nama: SaveAnnotations() memanggil <elementId>_BeforeAnnSave() dan <elementId>_DeletedAnnotationIds() ketika ada, menggunakan id lengkap elemen (div_ctlDoc_BeforeAnnSave untuk contoh di atas).

Tidak ada callback klik tautan — penanganan hyperlink sudah terintegrasi dan dipandu oleh showHyperlinks.

Grup metode publik

GrupMetode umum
Siklus hidupView(token, accessToken?), Close(server?), Token(), Init(), IsLoaded()
NavigasiGotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages()
Zoom dan sesuaikanZoom(zoomIn), CurrentZoom(), FitType(value), Refit()
OrientasiRotate(page, angle), Flip(page, flipType)
ThumbnailHideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb)
PencarianCanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...)
AnotasiSaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...)
SalinCopy(...), CopyPage(pageNumber), CopyMode(enabled)

File JavaScript juga berisi pembantu internal. Perlakukan hanya metode yang digunakan oleh UI referensi dan didokumentasikan di sini atau dalam panduan fitur sebagai titik integrasi yang stabil.

Coba ulang saat halaman terdistribusi masih merender

retryOn409 mempertahankan nama historisnya. Ini untuk produksi halaman asinkron dan mencoba ulang respons kesiapan 202 Accepted saat ini serta sinyal 409 Conflict yang lebih lama. Ketika diaktifkan, widget melakukan polling dengan default JavaScript ini:

OpsiDefault
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

Biarkan dinonaktifkan untuk penampil satu-node normal. Mengaktifkannya tidak dapat membuat render sinkron yang tidak didukung menjadi asinkron.

Aktifkan ketika halaman disajikan dari penyimpanan bersama dengan FirstPagePriority, di mana halaman selanjutnya secara sah menjawab 202 Accepted sampai mereka ditulis. Klien yang tidak mencoba ulang akan menampilkan ubin rusak untuk halaman yang masih merender — lihat Penyebaran Terdistribusi.

Daftar periksa jalur

  • DoconutOptions.MiddlewarePath harus menggambarkan cabang yang sebenarnya Anda petakan.
  • BasePath harus menargetkan cabang itu, ditulis tanpa / di depan ('doconut', bukan '/doconut': penampil menambahkan garis miring, dan //doconut/... adalah permintaan ke host lain). Pengaturan umum mempertahankan bentuk permintaan historis DocImage.axd pada cabang MapWhen dan oleh karena itu menetapkan BasePath: '/'.
  • DoconutOptions.ResourcesPath adalah rute sumber daya tersemat.
  • ResPath biasanya menargetkan subfolder images-nya, tanpa / di depan — 'doconut-res/images' dengan awalan default. ResPath kosong dulu benar di perpustakaan sebelumnya, di mana sumber daya berasal dari akar aplikasi; itu tidak benar di sini, dan gagal tanpa kesalahan.
  • ExtractHyperlinks harus diaktifkan dalam konfigurasi format server sebelum showHyperlinks dapat menampilkan apa pun.

Apakah halaman ini membantu?