ViewerConfig
Tùy chọn widget trình xem phía máy khách
ViewerConfig (namespace Doconut) mô tả giao diện và hành vi của trình xem trên trình duyệt. Nó không ảnh hưởng đến chất lượng hiển thị tài liệu; hãy sử dụng cấu hình định dạng cho việc đó. Lớp C# và widget JavaScript lâu đời có các mặc định khác nhau, vì vậy hãy ánh xạ các giá trị một cách rõ ràng.
Hai thay đổi phía máy khách trong bản phát hành này thất bại một cách im lặng. Các hàm xử lý được truyền dưới dạng tùy chọn — widget không còn lấy các callback sự kiện từ id của container — và
ResPathphải trỏ tới tiền tố tài nguyên thay vì gốc ứng dụng. Cả hai đều để máy chủ hoạt động bình thường và không báo cáo gì trong console của trình duyệt. Nếu bạn đang chuyển một trang từ thư viện trước, hãy đọc Các hàm gọi lại và Danh sách kiểm tra đường dẫn trước mọi thứ khác.
Thuộc tính C#
| Kiểu | Thuộc tính | Mặc định | Mô tả |
|---|---|---|---|
bool | ShowThumbs | true | Hiển thị bảng điều khiển hình thu nhỏ. |
bool | AutoLoad | false | Tự động tải sau khi khởi tạo. Luồng token bình thường gọi View(token) một cách rõ ràng. |
bool | AutoFocus | true | Di chuyển tiêu điểm/cuộn của trình duyệt tới trình xem trong quá trình khởi tạo. |
bool | AutoPageFocus | true | Giữ hình thu nhỏ hiện tại hiển thị khi các trang thay đổi. |
int | PageZoom | 100 | Phần trăm phóng đại ban đầu. |
int | ZoomStep | 10 | Phần trăm được thêm hoặc bớt bởi các lệnh phóng đại. |
int | MaxZoom | 300 | Phần trăm phóng đại tối đa. |
bool | ShowToolTip | true | Hiển thị tooltip vị trí trang khi cuộn. |
string | ToolTipPageText | "Page " | Tiền tố được sử dụng trong tooltip trang. |
bool | CacheEnabled | false | Giữ một cửa sổ di chuyển của các hình ảnh trang trong bộ nhớ trình duyệt. Nó không sử dụng localStorage. |
bool | LargeDoc | false | Thêm các phần tử trang theo các lô thời gian cho tài liệu lớn. |
bool | ShowHyperlinks | false | Hiển thị lớp phủ siêu liên kết khi cấu hình máy chủ đã trích xuất chúng. |
bool | FixedZoom | true | Sử dụng phần trăm phóng đại cố định thay vì tính toán lại đáp ứng. |
int | FixedZoomPercent | 100 | Phóng đại cố định cho máy tính để bàn. |
int | FixedZoomPercentMobile | 75 | Phóng đại cố định cho thiết bị di động. |
string | BasePath | "/" | Nơi trình xem gửi yêu cầu trang. "/" là DocImage.axd tại gốc site; nếu không, nhánh nơi máy chủ ánh xạ UseDoconut(), không có dấu / đầu ("doconut" có nghĩa là /doconut/DocImage.axd). |
string | ResPath | "doconut-res/images" (26.9.0; "doconut-res" before) | Thư mục mà widget tải các hình ảnh của nó: thư mục images dưới ResourcesPath, không có dấu /. |
string | FitType | "width" | "width", "height", hoặc trống để không tự động vừa. "page" không được widget hiện tại chấp nhận. |
bool | RetryOn409 | false | Bật việc thăm dò khi việc tạo trang bất đồng bộ/phân tán phản hồi 202 Accepted; 409 cũng được chấp nhận để tương thích với máy chủ cũ hơn. Không cần thiết cho trình xem đồng bộ thông thường. |
var config = new ViewerConfig
{
ShowThumbs = true,
AutoLoad = false,
PageZoom = 100,
MaxZoom = 300,
FitType = "width",
BasePath = "doconut", // không có dấu '/' ở đầu: trình xem sẽ thêm nó ("/doconut" sẽ trở thành //doconut, một máy chủ khác)
ResPath = "doconut-res/images",
ShowHyperlinks = true
};Ánh xạ C# sang JavaScript
Không truyền một ViewerConfig đã được tuần tự hoá trực tiếp tới docViewer(...). Hầu hết các khóa widget sử dụng camelCase, trong khi ba khóa đường dẫn/điều chỉnh đã được thiết lập sử dụng 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 |
Mặc định JavaScript
Tiện ích này có các mặc định cũ hơn so với lớp C#. Các giá trị sau đến từ triển khai hiện tại của docViewer.js.
| Tùy chọn | Mặc định | Ghi chú |
|---|---|---|
leftMinWidth / leftMaxWidth | 220 / 800 | Giới hạn chiều rộng khung thu nhỏ. |
showThumbs | true | Khả năng hiển thị thu nhỏ ban đầu. |
autoFocus / autoPageFocus | true / false | autoPageFocus khác với mặc định C#. |
thumbWidth / thumbHeight / thumbPadding | 150 / 200 / 10 | Hình học thu nhỏ tính bằng pixel. |
pageZoom / zoomStep / maxZoom | 100 / 10 / 200 | JavaScript maxZoom khác với C# (300). |
showToolTip / toolTipPageText | true / "Page " | Tooltip vị trí trang. |
format / doc / AccessToken | "" / 0 / "" | Giá trị khởi tạo nội bộ; thường được View(token) điền. |
debugMode | false | Chẩn đoán khách hàng bổ sung. |
FitType | "" | Không tự động vừa vặn trừ khi được cung cấp. |
BasePath | "DocImage.axd" | Mặc định khách hàng lịch sử được giữ lại để tương thích. Các máy chủ ASP.NET Core hiện tại phải đặt nó một cách rõ ràng tới nhánh middleware đã ánh xạ. |
ResPath | "" | Đặt một cách rõ ràng tới đường dẫn hình ảnh nhúng. |
cacheEnabled / cacheCount / cacheDelay | false / 3 / 3 | Cửa sổ và độ trễ tải trước trang trong bộ nhớ. |
autoLoad | false | Khuyến nghị luồng token rõ ràng. |
largeDoc | true | Khác với mặc định C#. |
fixedZoom | false | Khác với mặc định C#. |
fixedZoomPercent / fixedZoomPercentMobile | 100 / 50 | Giá trị di động khác với C# (75). |
showHyperlinks | true | Yêu cầu trích xuất phía máy chủ để tạo lớp phủ. |
Đặt tất cả các giá trị quan trọng về hành vi thay vì dựa vào bất kỳ bộ mặc định nào:
<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>Các hàm gọi lại
| Hàm gọi lại | Đối số | Mục đích |
|---|---|---|
onPageLoading | pageNum | Yêu cầu trang đang bắt đầu. |
onPageLoaded | pageNum | Hình ảnh trang đã tải xong. |
onThumbnailClicked | pageNum | Người dùng đã chọn một ảnh thu nhỏ. |
onPageClicked | pageNum | Người dùng đã chọn một trang. |
onDoubleClick | none | Trình xem nhận được double-click. |
onViewerBusy | none | Trình xem chuyển sang trạng thái bận. |
onViewerReady | none | Khởi tạo hoàn tất. |
onViewerError | none | Trình xem chuyển sang trạng thái lỗi. |
onError | message | Một thao tác trả về thông báo lỗi. |
onCopy | data | Dữ liệu sao chép văn bản có sẵn. |
onAutoLoadStatus | pageNum | Tự động tải tiến tới một trang. |
onThumbsShown | none | Bảng thu nhỏ trở nên hiển thị. |
onAnnLoaded | none | Dữ liệu chú thích đã tải. |
onAnnSaved | none | Dữ liệu chú thích đã lưu. |
onAnnSaveError | none | Lưu chú thích thất bại. |
onAnnClosed | none | Giao diện chú thích đã đóng. |
Giữ các hàm gọi lại nhanh; gửi dữ liệu đo lường một cách bất đồng bộ và không chặn việc render trang.
Mỗi một trong số này là một tùy chọn trên đối tượng init. Trình xem trước đây tìm kiếm các hàm toàn cục mà tên của chúng được suy ra từ id của container — một trang với <div id="div_ctlDoc"> chỉ cần khai báo function ctlDoc_OnViewerReady(). Việc tìm kiếm đó đã biến mất. Truyền hàm một cách rõ ràng:
function ctlDoc_OnViewerBusy() { /* hiển thị chỉ báo bận của bạn */ }
function ctlDoc_OnViewerReady() { /* ẩn nó */ }
function ctlDoc_Copy(text) { /* sử dụng văn bản đã sao chép */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* báo cáo tiến độ */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... các tùy chọn hiện có của bạn ...
onViewerBusy: ctlDoc_OnViewerBusy, // được tìm thấy theo tên
onViewerReady: ctlDoc_OnViewerReady, // được tìm thấy theo tên
onCopy: ctlDoc_Copy, // đã ctlDoc_Copy(text)
onAutoLoadStatus: ctlDoc_AutoLoadStatus // đã ctlDoc_AutoLoadStatus(page)
});Việc tìm kiếm cũ được bao bọc trong một catch trống, vì vậy không có gì được báo cáo. Trong bản phát hành này, các hàm đơn giản không bao giờ chạy: triệu chứng thường gặp là một biểu tượng quay bận không bao giờ dừng, vì trình xử lý ẩn nó đã là onViewerReady. Tài liệu phía sau đang được render đúng cách.
Hai hook lưu chú thích vẫn được tìm kiếm theo tên: SaveAnnotations() gọi <elementId>_BeforeAnnSave() và <elementId>_DeletedAnnotationIds() khi chúng tồn tại, sử dụng id đầy đủ của phần tử div_ctlDoc_BeforeAnnSave cho ví dụ trên.
Không có hàm gọi lại khi nhấp liên kết — việc xử lý siêu liên kết được tích hợp sẵn và được điều khiển bởi showHyperlinks.
Các nhóm phương thức công khai
| Nhóm | Phương thức chung |
|---|---|
| Vòng đời | View(token, accessToken?), Close(server?), Token(), Init(), IsLoaded() |
| Điều hướng | GotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages() |
| Phóng to và vừa | Zoom(zoomIn), CurrentZoom(), FitType(value), Refit() |
| Hướng | Rotate(page, angle), Flip(page, flipType) |
| Hình thu nhỏ | HideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb) |
| Tìm kiếm | CanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...) |
| Chú thích | SaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...) |
| Sao chép | Copy(...), CopyPage(pageNumber), CopyMode(enabled) |
Tệp JavaScript cũng chứa các trợ giúp nội bộ. Chỉ coi các phương thức được sử dụng bởi giao diện tham chiếu và được tài liệu ở đây hoặc trong các hướng dẫn tính năng là các điểm tích hợp ổn định.
Thử lại khi một trang phân tán vẫn đang render
retryOn409 giữ nguyên tên lịch sử của nó. Nó dùng cho việc tạo trang bất đồng bộ và thử lại phản hồi sẵn sàng hiện tại 202 Accepted cũng như tín hiệu cũ hơn 409 Conflict. Khi được bật, widget sẽ thực hiện polling với các mặc định JavaScript sau:
| Tùy chọn | Mặc định |
|---|---|
retryInitialDelayMs | 250 |
retryBackoffFactor | 1.6 |
retryMaxDelayMs | 2500 |
retryMaxAttempts | 150 |
retryMaxTotalMs | 300000 |
Để nó tắt cho trình xem đơn nút bình thường. Bật nó không thể làm cho một quá trình render đồng bộ không được hỗ trợ trở thành bất đồng bộ.
Bật nó khi các trang được phục vụ từ bộ nhớ chia sẻ với FirstPagePriority, nơi các trang sau này hợp pháp trả lời 202 Accepted cho đến khi chúng được ghi. Một client không thử lại sẽ hiển thị các ô bị hỏng cho các trang vẫn đang render — xem Triển khai Phân tán.
Danh sách kiểm tra đường dẫn
DoconutOptions.MiddlewarePathphải mô tả nhánh mà bạn thực sự ánh xạ.BasePathphải nhắm tới nhánh đó, viết mà không có/đầu tiên ('doconut', không phải'/doconut': trình xem sẽ thêm dấu gạch chéo, và//doconut/...là một yêu cầu tới máy chủ khác). Một cấu hình phổ biến giữ nguyên dạng yêu cầu lịch sửDocImage.axdtrên một nhánhMapWhenvà do đó đặtBasePath: '/'.DoconutOptions.ResourcesPathlà tuyến đường tài nguyên nhúng.ResPaththường nhắm tới thư mục conimagescủa nó, mà không có/đầu —'doconut-res/images'với tiền tố mặc định. MộtResPathtrống đã đúng trong thư viện trước, nơi các tài nguyên đến từ gốc ứng dụng; ở đây nó không đúng, và nó sẽ thất bại mà không có lỗi.ExtractHyperlinksphải được bật trong cấu hình định dạng máy chủ trước khishowHyperlinkscó thể hiển thị bất kỳ thứ gì.
Trang này có hữu ích không?