ViewerConfig – Doconut เอกสาร

ViewerConfig (namespace Doconut) อธิบายลักษณะและพฤติกรรมของตัวดูในเบราว์เซอร์. มันไม่ส่งผลต่อคุณภาพการแสดงผลของเอกสาร; ใช้การกำหนดค่ารูปแบบสำหรับเรื่องนั้น. คลาส C# และวิดเจ็ต JavaScript ที่มีมานานมีค่าเริ่มต้นที่แตกต่างกัน, ดังนั้นให้แมปค่าอย่างชัดเจน.

การเปลี่ยนแปลงสองอย่างฝั่งไคลเอนต์ในรุ่นนี้ล้มเหลวโดยเงียบ ฟังก์ชันจัดการจะถูกส่งเป็นตัวเลือก — วิดเจ็ตไม่ดึงชื่อฟังก์ชันระดับโลกจาก id ของคอนเทนเนอร์อีกต่อไป — และ ResPath ต้องชี้ไปที่คำนำหน้าทรัพยากรแทนรากของแอปพลิเคชัน. ทั้งสองทำให้เซิร์ฟเวอร์ทำงานได้อย่างสมบูรณ์และไม่แสดงอะไรในคอนโซลของเบราว์เซอร์. หากคุณกำลังย้ายหน้าไปจากไลบรารีก่อนหน้า, โปรดอ่าน Callbacks และ Path checklist ก่อนทำอย่างอื่น.

คุณสมบัติ C#

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`bool`	`ShowThumbs`	`true`	แสดงแผงรูปย่อ.
`bool`	`AutoLoad`	`false`	โหลดโดยอัตโนมัติหลังการเริ่มต้น. การไหลของโทเค็นปกติจะเรียก `View(token)` อย่างชัดเจน.
`bool`	`AutoFocus`	`true`	ย้ายโฟกัส/การเลื่อนของเบราว์เซอร์ไปยังตัวดูในระหว่างการเริ่มต้น.
`bool`	`AutoPageFocus`	`true`	ทำให้รูปย่อปัจจุบันมองเห็นได้ขณะเปลี่ยนหน้า.
`int`	`PageZoom`	`100`	เปอร์เซ็นต์การซูมเริ่มต้น.
`int`	`ZoomStep`	`10`	เปอร์เซ็นต์ที่เพิ่มหรือหักโดยคำสั่งซูม.
`int`	`MaxZoom`	`300`	เปอร์เซ็นต์การซูมสูงสุด.
`bool`	`ShowToolTip`	`true`	แสดงทูลทิปตำแหน่งหน้าในขณะเลื่อน.
`string`	`ToolTipPageText`	`"Page "`	`"Page "` คำนำหน้าที่ใช้ในทูลทิปของหน้า.
`bool`	`CacheEnabled`	`false`	เก็บหน้าต่างเคลื่อนที่ของรูปภาพหน้าในหน่วยความจำของเบราว์เซอร์. ไม่ใช้ `localStorage`.
`bool`	`LargeDoc`	`false`	เพิ่มองค์ประกอบหน้าตามชุดที่กำหนดเวลา สำหรับเอกสารขนาดใหญ่.
`bool`	`ShowHyperlinks`	`false`	แสดงซ้อนลิงก์เมื่อการกำหนดค่าของเซิร์ฟเวอร์ดึงออกมา.
`bool`	`FixedZoom`	`true`	ใช้เปอร์เซ็นต์การซูมคงที่แทนการคำนวณใหม่แบบตอบสนอง.
`int`	`FixedZoomPercent`	`100`	การซูมบนเดสก์ท็อปคงที่.
`int`	`FixedZoomPercentMobile`	`75`	การซูมบนมือถือคงที่.
`string`	`BasePath`	`"/"`	ตำแหน่งที่ตัวดูส่งคำขอหน้า. `"/"` คือ `DocImage.axd` ที่รากของไซต์; มิฉะนั้นเป็นสาขาที่โฮสต์แมพ `UseDoconut()`, โดยไม่มี `/` นำหน้า (`"doconut"` หมายถึง `/doconut/DocImage.axd`).
`string`	`ResPath`	`"doconut-res/images"` (26.9.0; `"doconut-res"` before)	โฟลเดอร์ที่วิดเจ็ตโหลดรูปภาพของตนเองจาก: โฟลเดอร์ `images` ภายใต้ `ResourcesPath`, โดยไม่มี `/` นำหน้า.
`string`	`FitType`	`"width"`	`"width"`, `"height"` หรือว่างสำหรับไม่มีการปรับอัตโนมัติ. `"page"` ไม่ได้รับการยอมรับโดยวิดเจ็ตปัจจุบัน.
`bool`	`RetryOn409`	`false`	เปิดใช้งานการโพลเมื่อการผลิตหน้าที่แบบอะซิงโครนัส/กระจายตอบกลับ `202 Accepted`; `409` ก็ได้รับการยอมรับเพื่อความเข้ากันได้กับเซิร์ฟเวอร์รุ่นเก่า. ไม่จำเป็นสำหรับตัวดูแบบซิงโครนัสปกติ.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // ไม่มี '/' นำหน้า: ตัวดูจะเพิ่มมัน ("/doconut" จะกลายเป็น //doconut, โฮสต์อื่น)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

การแมป C# ไปยัง JavaScript

อย่าส่ง ViewerConfig ที่ถูกซีเรียลไลซ์โดยตรงไปยัง docViewer(...). คีย์ส่วนใหญ่ของวิดเจ็ตใช้รูปแบบ camelCase, ในขณะที่คีย์เส้นทาง/การปรับขนาดที่กำหนดไว้สามตัวใช้รูปแบบ PascalCase.

C#	JavaScript
`ShowThumbs`	`showThumbs`
`AutoLoad`	`autoLoad`
`AutoFocus`	`autoFocus`
`AutoPageFocus`	`autoPageFocus`
`PageZoom`	`pageZoom`
`ZoomStep`	`zoomStep`
`MaxZoom`	`maxZoom`
`ShowToolTip`	`showToolTip`
`ToolTipPageText`	`toolTipPageText`
`CacheEnabled`	`cacheEnabled`
`LargeDoc`	`largeDoc`
`ShowHyperlinks`	`showHyperlinks`
`FixedZoom`	`fixedZoom`
`FixedZoomPercent`	`fixedZoomPercent`
`FixedZoomPercentMobile`	`fixedZoomPercentMobile`
`BasePath`	`BasePath`
`ResPath`	`ResPath`
`FitType`	`FitType`
`RetryOn409`	`retryOn409`

ค่าเริ่มต้นของ JavaScript

วิดเจ็ตมีค่าเริ่มต้นเก่าที่แตกต่างจากคลาส C#. ค่าต่อไปนี้มาจากการทำงานปัจจุบันของ docViewer.js.

ตัวเลือก	ค่าเริ่มต้น	หมายเหตุ
`leftMinWidth` / `leftMaxWidth`	`220` / `800`	ขอบเขตความกว้างของแผงภาพย่อ
`showThumbs`	`true`	การแสดงภาพย่อเริ่มต้น
`autoFocus` / `autoPageFocus`	`true` / `false`	`autoPageFocus` แตกต่างจากค่าเริ่มต้นของ C#
`thumbWidth` / `thumbHeight` / `thumbPadding`	`150` / `200` / `10`	รูปทรงของภาพย่อเป็นพิกเซล
`pageZoom` / `zoomStep` / `maxZoom`	`100` / `10` / `200`	ค่า `maxZoom` ของ JavaScript แตกต่างจาก C# (`300`)
`showToolTip` / `toolTipPageText`	`true` / `"Page "`	ทูลทิปตำแหน่งหน้า
`format` / `doc` / `AccessToken`	`""` / `0` / `""`	ค่าการเริ่มต้นภายใน; ปกติจะถูกกำหนดโดย `View(token)`
`debugMode`	`false`	การวินิจฉัยเพิ่มเติมของไคลเอนต์
`FitType`	`""`	ไม่มีการปรับอัตโนมัติหากไม่ได้ระบุ
`BasePath`	`"DocImage.axd"`	ค่าเริ่มต้นของไคลเอนต์แบบเก่าสำหรับความเข้ากันได้. โฮสต์ ASP.NET Core ปัจจุบันต้องตั้งค่าอย่างชัดเจนไปยังสาขา middleware ที่แมป
`ResPath`	`""`	ตั้งค่าอย่างชัดเจนไปยังเส้นทางของภาพที่ฝังอยู่
`cacheEnabled` / `cacheCount` / `cacheDelay`	`false` / `3` / `3`	หน้าต่างและการหน่วงเวลาการโหลดล่วงหน้าของหน้าในหน่วยความจำ
`autoLoad`	`false`	แนะนำให้ใช้การไหลของโทเคนอย่างชัดเจน
`largeDoc`	`true`	แตกต่างจากค่าเริ่มต้นของ C#
`fixedZoom`	`false`	แตกต่างจากค่าเริ่มต้นของ C#
`fixedZoomPercent` / `fixedZoomPercentMobile`	`100` / `50`	ค่าบนอุปกรณ์เคลื่อนที่แตกต่างจาก C# (`75`)
`showHyperlinks`	`true`	ต้องการการสกัดข้อมูลจากฝั่งเซิร์ฟเวอร์เพื่อสร้างโอเวอร์เลย์

ตั้งค่าทุกค่าที่สำคัญต่อพฤติกรรมแทนการพึ่งพาชุดค่าเริ่มต้นใดชุดหนึ่ง:

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>

คอลแบ็ก

คอลแบ็ก	อาร์กิวเมนต์	จุดประสงค์
`onPageLoading`	`pageNum`	กำลังเริ่มการร้องขอหน้า
`onPageLoaded`	`pageNum`	ภาพหน้าสำเร็จการโหลด
`onThumbnailClicked`	`pageNum`	ผู้ใช้เลือกภาพย่อ
`onPageClicked`	`pageNum`	ผู้ใช้เลือกหน้า
`onDoubleClick`	none	Viewer ได้รับการคลิกสองครั้ง
`onViewerBusy`	none	Viewer เข้าสู่สถานะทำงาน
`onViewerReady`	none	การเริ่มต้นเสร็จสมบูรณ์
`onViewerError`	none	Viewer เข้าสู่สถานะข้อผิดพลาด
`onError`	`message`	การดำเนินการส่งคืนข้อความข้อผิดพลาด
`onCopy`	`data`	ข้อมูลการคัดลอกข้อความพร้อมใช้งาน
`onAutoLoadStatus`	`pageNum`	การโหลดอัตโนมัติก้าวหน้าไปยังหน้าที่
`onThumbsShown`	none	แผงภาพย่อปรากฏ
`onAnnLoaded`	none	ข้อมูลคำอธิบายโหลดแล้ว
`onAnnSaved`	none	ข้อมูลคำอธิบายบันทึกแล้ว
`onAnnSaveError`	none	การบันทึกคำอธิบายล้มเหลว
`onAnnClosed`	none	ส่วนต่อประสานคำอธิบายปิดลง

ทำให้คอลแบ็กทำงานเร็ว; ส่ง telemetry อย่างอะซิงโครนัสและอย่าบล็อกการเรนเดอร์หน้า.

ทุกอันเหล่านี้เป็นตัวเลือกในอ็อบเจกต์การเริ่มต้น. ตัวดูเดิมค้นหาฟังก์ชันระดับโลกที่ชื่อมาจาก id ของคอนเทนเนอร์ — หน้า <div id="div_ctlDoc"> เพียงแค่ต้องประกาศ function ctlDoc_OnViewerReady(). การค้นหานั้นหายไปแล้ว. ส่งฟังก์ชันโดยตรง:

javascript

objctlDoc = $('#div_ctlDoc').docViewer({
    // ... ตัวเลือกที่คุณมีอยู่แล้ว ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // ถูกค้นหาด้วยชื่อ
    onViewerReady:    ctlDoc_OnViewerReady,     // ถูกค้นหาด้วยชื่อ
    onCopy:           ctlDoc_Copy,              // คือ ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // คือ ctlDoc_AutoLoadStatus(page)
});

การค้นหาแบบเก่าอยู่ใน catch ว่างเปล่า, ดังนั้นไม่มีอะไรถูกรายงานเลย. ในรุ่นนี้ฟังก์ชันจะไม่ทำงานเลย: อาการทั่วไปคือสปินเนอร์ทำงานอยู่ที่ไม่หยุด, เนื่องจากตัวจัดการที่ซ่อนมันคือ onViewerReady. เอกสารที่อยู่ด้านหลังกำลังเรนเดอร์อย่างถูกต้อง.

ไม่มีคอลแบ็กสำหรับการคลิกลิงก์ — การจัดการไฮเปอร์ลิงก์ถูกสร้างไว้ในตัวและควบคุมโดย showHyperlinks.

กลุ่มเมธอดสาธารณะ

กลุ่ม	เมธอดทั่วไป
วงจรชีวิต	`View(token, accessToken?)`, `Close(server?)`, `Token()`, `Init()`, `IsLoaded()`
การนำทาง	`GotoPage(page)`, `ShowPage(page, focus?)`, `Next(next)`, `CurrentPage()`, `TotalPages()`
ซูมและปรับให้พอดี	`Zoom(zoomIn)`, `CurrentZoom()`, `FitType(value)`, `Refit()`
การจัดแนว	`Rotate(page, angle)`, `Flip(page, flipType)`
ภาพย่อ	`HideThumbs(hide)`, `ThumbSize(size)`, `ReloadThumbs(width)`, `ScrollToThumb(thumb)`
การค้นหา	`CanSearch()`, `Search(...)`, `SearchMatchCount()`, `SearchSummary(...)`, `GotoSearchMatch(...)`
คำอธิบาย	`SaveAnnotations()`, `GetAnnotations()`, `PushAnnotations(...)`, `CloseAnnotations(...)`, `ShowAnnotations(...)`
คัดลอก	`Copy(...)`, `CopyPage(pageNumber)`, `CopyMode(enabled)`

ไฟล์ JavaScript ยังมีตัวช่วยภายในด้วย ให้ถือว่าเฉพาะเมธอดที่ใช้โดย UI อ้างอิงและที่ได้อธิบายไว้ที่นี่หรือในคู่มือฟีเจอร์เป็นจุดเชื่อมต่อที่เสถียร

ลองใหม่ขณะที่หน้าที่กระจายยังคงเรนเดอร์อยู่

retryOn409 ยังคงชื่อเดิมตามประวัติ มันใช้สำหรับการผลิตหน้าแบบอะซิงโครนัสและลองใหม่การตอบสนอง readiness 202 Accepted ปัจจุบันรวมถึงสัญญาณ 409 Conflict เก่า เมื่อเปิดใช้งาน วิดเจ็ตจะโพลด้วยค่าเริ่มต้น JavaScript เหล่านี้:

ตัวเลือก	ค่าเริ่มต้น
`retryInitialDelayMs`	`250`
`retryBackoffFactor`	`1.6`
`retryMaxDelayMs`	`2500`
`retryMaxAttempts`	`60`
`retryMaxTotalMs`	`120000`

ปล่อยให้ปิดอยู่สำหรับผู้ชมแบบโหนดเดียวปกติ การเปิดใช้งานไม่สามารถทำให้การเรนเดอร์แบบซิงโครนัสที่ไม่รองรับกลายเป็นแบบอะซิงโครนัสได้

เปิดใช้งานเมื่อหน้าถูกเสิร์ฟจากที่เก็บข้อมูลร่วมด้วย FirstPagePriority ซึ่งหน้าต่อมาจะตอบ 202 Accepted อย่างถูกต้องจนกว่าจะถูกเขียนลง ลูกค้าที่ไม่ลองใหม่จะแสดงไทล์ที่เสียหายสำหรับหน้าที่ยังกำลังเรนเดอร์ — ดู การปรับใช้แบบกระจาย.

รายการตรวจสอบเส้นทาง

DoconutOptions.MiddlewarePath ต้องอธิบายสาขาที่คุณแมปจริง
BasePath ต้องชี้ไปยังสาขานั้น เขียนโดยไม่มี / นำหน้า ('doconut' ไม่ใช่ '/doconut': ตัวชมรมเพิ่มสแลชและ //doconut/... จะเป็นการร้องขอไปยังโฮสต์อื่น) แอปอ้างอิงเก็บรูปแบบการร้องขอ DocImage.axd แบบเก่าไว้บนสาขา MapWhen จึงตั้งค่า BasePath: '/'.
DoconutOptions.ResourcesPath คือเส้นทางทรัพยากรที่ฝังไว้
ResPath ปกติจะชี้ไปยังโฟลเดอร์ย่อย images ของมัน โดยไม่มี / นำหน้า — 'doconut-res/images' พร้อมคำนำหน้าเริ่มต้น ResPath ที่ว่างเปล่าเคยถูกต้องในไลบรารีก่อนหน้า ที่ซึ่งทรัพยากรมาจากรูทของแอปพลิเคชัน; แต่ที่นี่ไม่ถูกต้องและจะล้มเหลวโดยไม่มีข้อผิดพลาด
ExtractHyperlinks ต้องเปิดใช้งานในการกำหนดค่ารูปแบบเซิร์ฟเวอร์ก่อนที่ showHyperlinks จะสามารถแสดงอะไรได้