تم‌های سفارشی

نمایشگر با ظاهری خنثی و مبتنی بر Bootstrap که از منابع توکار (viewer.css، به‌علاوهٔ stylesheetهای ویژگی‑محور مانند searchBar.css و annotationBar.css) سرو می‌شود، ارائه می‌شود. تم‌گذاری در سه سطح انجام می‌شود — کم‌عمق‌ترین سطحی را که به هدف می‌رسید انتخاب کنید.

سطح ۱ — پیکربندی chrome

بسیاری از «تم‌گذاری» در واقع پیکربندی است:

• ViewerConfig.ShowThumbs = false — بدون پنل تصویر بندانگشتی.
• ViewerConfig.FitType = "height" | "width" — نحوه پر شدن صفحات در نمای پنجره.
• ViewerConfig.ShowThumbs = false همراه با بسته‌های انتخابی CssConfig/ScriptConfig — فقط chrome مورد استفادهٔ میزبان خود را نگه دارید.

سطح ۲ — بازنویسی CSS

Viewer.ReferenceCss() تگ‌های سادهٔ <link> تولید می‌کند؛ هر چیزی که بعد از آن‌ها بارگذاری کنید، بر سلسله‌مراتبی (cascade) غلبه می‌کند. اندازه و قاب نمایشگر را از طریق stylesheet خود تنظیم کنید:

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

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

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

صفحهٔ میزبان به‌طور کامل چیدمان بیرونی را کنترل می‌کند — ویجت داخل هر جعبه‌ای که به #divDocViewer / #div_ctlDoc اختصاص دهید رندر می‌شود (جفت کانتینر استاندارد از Quick Start).

دو قانون عملی:

• Bootstrap را دوبار بارگذاری نکنید. اگر برنامهٔ شما قبلاً Bootstrap را می‌فرستد، IncludeBootstrapCss/IncludeBootstrap را نادیده بگیرید و بگذارید ویجت از Bootstrap شما ارث‌بری کند — این به تنهایی باعث می‌شود نمایشگر به‌صورت بومی در برنامهٔ شما ظاهر شود.
• فقط بسته‌هایی را که استفاده می‌کنید وارد کنید. هر پرچم CssConfig/ScriptConfig به‌صورت انتخابی فعال است؛ بسته‌های کمتر، سبک‌های کمتری برای مقابله.

سطح ۳ — ساخت نوار ابزار خودتان

برای تجربه‌ای کاملاً برندشده، ویجت را از رابط کاربری خودتان کنترل کنید — این دقیقاً همان روشی است که نمونهٔ مرجع نوار ابزار اصلی Viewer خود را می‌سازد. آن نوار ابزار شامل مارکاپ میزبان به‌همراه یک کمکی مخصوص برنامه است؛ این یک Ribbon SDK توکار نیست. نمونهٔ docViewer که پس از مقداردهی اولیه برگردانده می‌شود، سطح API شماست، به‌همراه نقطه‌های انتهایی (endpoints) خودتان:

<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>

جستجو و حاشیه‌نویسی متفاوت هستند: مؤلفه‌های Ribbon اختیاری آن‌ها در SDK توکار هستند (IncludeSearchBar، IncludeAnnotationBar) و DOM خود را تولید می‌کنند. می‌توانید آن‌ها را همراه با نوار ابزار سفارشی Viewer خود استفاده کنید یا آن‌ها را نادیده بگیرید و به‌صورت مستقیم APIهای زیرساختی ویجت را فراخوانی کنید. برای ترتیب کامل یکپارچه‌سازی، به بستهٔ کامل Viewer در Quick Start مراجعه کنید.

حالت تاریک و RTL

ویجت تم تاریک ارائه نمی‌دهد؛ یک بازنویسی سطح ۲ که کلاس حالت‑تاریک شما را هدف قرار می‌دهد (مثلاً .dark #divDocViewer { … }) برای پس‌زمینه‌ها و حاشیه‌ها اکثر نیازها را پوشش می‌دهد، زیرا محتوای صفحه به‌صورت تصویر رندر می‌شود. برای میزبان‌های RTL، نمایشگر به‌خوبی داخل یک چیدمان RTL کار می‌کند — نوار ابزار خود را آگاه از RTL نگه دارید.

کارهایی که نباید انجام داد

فورک یا ویرایش stylesheetهای توکار را انجام ندهید: آن‌ها داخل بسته می‌آند و در هر به‌روزرسانی جایگزین می‌شوند. بازنویسی‌ها در stylesheet خودتان پس از ارتقاها باقی می‌مانند؛ اما ویرایش‌های viewer.css این‌گونه نیست.