Giao Diện Tùy Chỉnh

Trang trí trình xem để phù hợp với ứng dụng của bạn

Trình xem đi kèm với giao diện trung tính, dựa trên Bootstrap, được cung cấp từ các tài nguyên nhúng (viewer.css, cùng với các stylesheet riêng cho từng tính năng như searchBar.css và annotationBar.css). Việc tạo giao diện diễn ra ở ba cấp độ — chọn cấp độ nông nhất để đạt được mục tiêu.

Cấp độ 1 — Cấu hình khung

Nhiều thứ được gọi là “tạo giao diện” thực chất chỉ là cấu hình:

  • ViewerConfig.ShowThumbs = false — không hiển thị bảng thu nhỏ.
  • ViewerConfig.FitType = "height" | "width" — cách các trang lấp đầy vùng hiển thị.
  • ViewerConfig.ShowThumbs = false kết hợp với các gói CssConfig/ScriptConfig chọn lọc — chỉ giữ lại khung mà máy chủ của bạn sử dụng.

Cấp độ 2 — Ghi đè CSS

Viewer.ReferenceCss() tạo ra các thẻ <link> đơn giản; bất kỳ thứ gì bạn tải sau chúng sẽ thắng trong chuỗi cascade. Điều chỉnh kích thước và khung cho trình xem bằng stylesheet của bạn:

css
/* Your stylesheet, loaded after ReferenceCss() */

/* The two containers you own */
#divDocViewer { width: 100%; height: calc(100vh - 48px); }

/* Widget page cards */
.docPage { max-width: none; }

Trang chủ kiểm soát hoàn toàn bố cục bên ngoài — widget sẽ được hiển thị bên trong bất kỳ khung nào bạn cung cấp cho #divDocViewer / #div_ctlDoc (cặp container tiêu chuẩn từ Bắt Đầu Nhanh).

Hai quy tắc thực tiễn:

  • Không tải Bootstrap đôi. Nếu ứng dụng của bạn đã có Bootstrap, bỏ qua IncludeBootstrapCss/IncludeBootstrap và để widget kế thừa của bạn — điều này một mình đã làm cho trình xem trông gốc trong ứng dụng của bạn.
  • Chỉ bao gồm các gói bạn sử dụng. Mỗi cờ CssConfig/ScriptConfig đều là tùy chọn; ít gói hơn, ít kiểu dáng cần đấu tranh.

Cấp độ 3 — Xây dựng thanh công cụ của riêng bạn

Để có trải nghiệm thương hiệu hoàn chỉnh, điều khiển widget từ giao diện người dùng của bạn — đây chính là cách mẫu tham chiếu xây dựng thanh công cụ chính của Viewer. Thanh công cụ đó là markup của máy chủ cộng với một trợ giúp riêng cho ứng dụng; nó không phải là Ribbon SDK được nhúng. Đối tượng docViewer trả về sau khi khởi tạo là giao diện API của bạn, cùng với các endpoint riêng — ở đây là hành động ViewerApi/Open từ Cách Thức Hoạt Động của Viewer:

html
<div id="toolbar">
    <button id="btnOpen">Open</button>
    <button id="btnPrev">‹</button>
    <button id="btnNext">›</button>
    <!-- your design system, your icons -->
</div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
    const objViewer = $('#div_ctlDoc').docViewer({
        showThumbs: true,
        autoLoad:   false,
        BasePath:   '/',
        ResPath:    'doconut-res/images',
        onViewerReady: () => { /* enable your buttons */ },
        onError: (msg) => console.error('DocViewer:', msg)
    });

    document.getElementById('btnOpen').addEventListener('click', async () => {
        const resp  = await fetch('/ViewerApi/Open?fileName=Sample.pdf', { method: 'POST' });
        const token = await resp.text();
        objViewer.View(token);
    });
</script>

Tìm kiếm và Ghi chú là khác nhau: các thành phần Ribbon tùy chọn của chúng được nhúng trong SDK (IncludeSearchBar, IncludeAnnotationBar) và tạo ra DOM riêng. Bạn có thể sử dụng chúng cùng với thanh công cụ Viewer tùy chỉnh của mình hoặc bỏ qua chúng và tự gọi các API của widget nền. Xem Bắt Đầu Nhanh để biết thứ tự tích hợp đầy đủ.

Chế độ tối và RTL

Widget không đi kèm giao diện tối; một ghi đè Cấp độ 2 nhắm vào lớp chế độ tối của bạn (ví dụ .dark #divDocViewer { … }) cho nền và viền sẽ đáp ứng hầu hết nhu cầu, vì nội dung trang được hiển thị dưới dạng hình ảnh. Đối với máy chủ RTL, trình xem hoạt động tốt trong bố cục RTL — hãy đảm bảo thanh công cụ của bạn nhận biết RTL.

Những việc không nên làm

Không fork hoặc chỉnh sửa các stylesheet nhúng: chúng được cung cấp trong gói và sẽ được thay thế trong mỗi bản cập nhật. Các ghi đè trong stylesheet của bạn sẽ tồn tại qua các nâng cấp; việc chỉnh sửa viewer.css sẽ không giữ lại.

Trang này có hữu ích không?