Chủ đề tùy chỉnh

Tùy chỉnh giao diện viewer sao cho phù hợp với ứng dụng của bạn

Viewer được cung cấp với giao diện trung tính, dựa trên Bootstrap và được phục vụ từ các tài nguyên nhúng (viewer.css, cùng với các stylesheet theo tính năng như searchBar.css và annotationBar.css). Việc tạo chủ đề diễn ra ở ba cấp độ — chọn cấp độ nông nhất mà đáp ứng nhu cầu của bạn.

Cấp độ 1 — Cấu hình giao diện

Nhiều thứ được gọi là "theming" 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 các thẻ <link> thông thường; bất cứ thứ gì bạn tải sau chúng sẽ thắng trong cascade. Định kích thước và khung cho viewer 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 render 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ừ Quick Start).

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

  • Đừ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 — việc này một mình đã khiến viewer trông gốc như trong ứng dụng của bạn.
  • Chỉ bao gồm các gói bạn 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 chiến đấu hơn.

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 toàn, hãy điều khiển widget từ UI của bạn — đây chính là cách mẫu tham chiếu xây dựng thanh công cụ Viewer chính. Thanh công cụ đó là markup của máy chủ cộng với một helper đặc thù cho ứng dụng; nó không phải là một SDK Ribbon được nhúng. Đối tượng docViewer trả về sau khi khởi tạo là bề mặt API của bạn, cùng với các endpoint riêng của bạn:

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('/api/open?fileName=Sample.pdf', { method: 'POST' });
        const token = await resp.text();
        objViewer.View(token);
    });
</script>

Tìm kiếm và Ghi chú là hai phần 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ự tạo 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 và gọi trực tiếp các API widget. Xem complete Viewer package in Quick Start để biết thứ tự tích hợp đầy đủ.

Chế độ tối và RTL

Widget không cung cấp chủ đề 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 { … }) trên nền và viền sẽ đáp ứng hầu hết nhu cầu, vì nội dung trang tự nó được render dưới dạng hình ảnh. Đối với máy chủ RTL, viewer hoạt động tốt trong bố cục RTL — hãy giữ cho thanh công cụ của bạn nhận biết RTL.

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

Đừng fork hoặc chỉnh sửa các stylesheet được nhúng: chúng nằm trong gói và sẽ được thay thế mỗi khi có 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 được giữ lại.

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