Chủ đề Tùy chỉnh

Tùy chỉnh giao diện người xem để phù hợp với ứng dụng của bạn

Trình xem được cung cấp với giao diện trung tính, dựa trên Bootstrap, được phục vụ từ các tài nguyên nhúng (viewer.css, cộng thêm 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 chrome

Nhiều phần của “theming” thực chất là cấu hình:

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

Cấp độ 2 — Ghi đè CSS

Viewer.ReferenceCss() phát ra các thẻ <link> thuần; bất kỳ thứ gì bạn tải sau chúng sẽ thắng trong cascade. Định kích thước và khung cho trình xem từ stylesheet của bạn:

css
/* Stylesheet của bạn, được tải sau ReferenceCss() */

/* Hai container mà bạn sở hữu */
#divDocViewer { width: 100%; height: calc(100vh - 48px); }

/* Thẻ trang widget */
.docPage { max-width: none; }

Trang chủ kiểm soát hoàn toàn bố cục bên ngoài — widget sẽ hiển thị bên trong bất kỳ khung nào bạn cung cấp #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 hai lần. 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 là tùy chọn; ít gói hơn, ít kiểu dáng cần đấu tranh 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, điều khiển widget từ UI của riêng bạn. Một thanh công cụ như vậy 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à Ribbon SDK được nhúng. Đối tượng docViewer được trả về khi khởi tạo là bề mặt API của bạn, cùng với các endpoint của bạn — ở đây là hành động ViewerApi/Open từ How the Viewer Works:

html
<div id="toolbar">
    <button id="btnOpen">Open</button>
    <button id="btnPrev">‹</button>
    <button id="btnNext">›</button>
    <!-- hệ thống thiết kế của bạn, các biểu tượng của bạn -->
</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: () => { /* kích hoạt các nút của bạn */ },
        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 widget nền. Xem 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 hiển thị dưới dạng hình ảnh. Đối với các máy chủ RTL, trình xem hoạt động tốt trong bố cục RTL — hãy giữ cho thanh công cụ của bạn nhận thức được RTL.

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

Không được 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 thì không.

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