جستجو

Doconut Viewer جستجوی عادی را با استفاده از متنی که توسط نمایشگر فرمت استخراج می‌شود یا یک بازگردانی PDF مبتنی بر متن فراهم می‌کند. این قابلیت به مجوز Search نیاز دارد.

فعال‌سازی رابط کاربری جستجو

Search یک ماژول Viewer است، نه یک نوار ابزار مستقل. صفحه کامل باید شامل منابع Viewer، نوار ابزار Viewer، سوار کردن Viewer، و objViewer اولیه باشد؛ سپس Ribbon جستجو سوار و به همان نمونه الصاق می‌شود.

Search و annotation ویژگی‌های دارای مجوز داخلی هستند، نه بسته‌های AddPlugin<T>(). منابع جستجو را از Viewer تزریق‌شده درخواست کنید؛ برچسب‌های آن‌ها فقط زمانی صادر می‌شوند که مجوز Search را اعطا کند.

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true,
    IncludeSearchCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery = true,
    IncludeViewerScripts = true,
    IncludeSearchScripts = true,
    IncludeSearchBar = true
}))

نوار Ribbon جاسازی‌شده همان متدهای JavaScript در دسترس برای یک رابط کاربری سفارشی را فراخوانی می‌کند.

ساختار کامل Viewer را در نشانه‌گذاری (markup) قابل مشاهده نگه دارید، ابتدا docViewer را مقداردهی اولیه کنید و سپس Ribbon دارای مجوز را الصاق کنید:

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer controls, including the button that opens Search -->
</nav>
<div id="searchBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
    let searchBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/doconut',
        ResPath: '/doconut-res/images'
    });

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onStatus: (message) => console.log(message),
        onToast: (message, type) => console.log(type, message),
        onLayout: () => requestAnimationFrame(() => objViewer.Refit())
    });
    searchBar.attach(objViewer);
        </text>
    }
</script>

این مؤلفه گروه‌های Find، Options و Results را تزریق می‌کند و جستجو، پاک‌سازی، شمارش نتایج و ناوبری به‌سابقه/بعدی را مدیریت می‌کند. نوار ابزار Viewer متعلق به میزبان فقط کافی است آن را فعال/غیرفعال کند:

searchBar.isOpen() ? searchBar.close() : searchBar.open();

API عمومی آن به‌صورت عمدی کوچک است:

Callback اختیاری onToggle(isOpen) به میزبان امکان همگام‌سازی دکمه جستجوی خود را می‌دهد و onLayout اجازه می‌دهد هنگام تغییر ارتفاع Ribbon، Viewer را دوباره اندازه‌گیری/تنظیم کند. برای توالی راه‌اندازی ترکیبی Viewer، Search و Annotation، به شروع سریع مراجعه کنید.

جستجو از JavaScript

objViewer.Search(keyword, false, function (resultCount) {
    console.log('Matches:', resultCount);
});

آرگومان دوم مطابقت کامل/کلمه‌به‌کلمه است. پس از فراخوانی callback:

مسیر میانی (middleware) از search=<term> و exact=true|false استفاده می‌کند و XML برمی‌گرداند. به‌جای تجزیهٔ دستی این پاسخ داخلی، از API ویجت استفاده کنید.

بررسی قابلیت جستجو

X-Doconut-Can-Search: 1

پس از مقداردهی اولیه، objViewer.CanSearch() همان verdict فرمت/جلسه را نشان می‌دهد. وقتی سرور 0 ارسال کند false برمی‌گرداند؛ پیش از دریافت پاسخ یا در سرورهای قدیمی که سرآیند را حذف می‌کنند، به‌صورت پیش‌فرض true است.

سه دروازهٔ مستقل نباید با هم اشتباه گرفته شوند:

یک فرمت می‌تواند از نظر فنی قابلیت جستجو داشته باشد در حالی که مجوز فعلی عملیات را منع می‌کند.

فعال‌سازی استخراج بر حسب فرمت

var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true   // optional: lets the user drag a region and copy its text
});

AllowSearch و AllowCopy در PdfConfig، WordConfig، ExcelConfig و PptConfig وجود دارند. ویژگی‌های Office به PdfConfig تو در تو خود واگذار می‌شوند. هر دو به‌صورت پیش‌فرض false هستند.

آداپتورهای جستجوی بومی معمولی برای PDF، Word، Excel، PowerPoint، TXT، Visio، ایمیل، EPUB و MHT وجود دارند. XPS به‌صورت پیش‌فرض از مسیر PDF خود استفاده می‌کند. HTML و Microsoft Project از یک بازگردانی PDF مبتنی بر متن بهره می‌برند:

// DefaultRender = false → converted to a text-based PDF → searchable
var token = await viewer.OpenDocumentAsync(path, new HtmlConfig { DefaultRender = false });

برای رندررهای بومی، CanSearch() قابلیت Viewer را توصیف می‌کند؛ اما تضمین نمی‌کند که سند خاصی متن قابل استفاده داشته باشد. یک PDF که صفحاتش فقط تصاویر اسکن‌شده هستند می‌تواند همچنان صفر نتیجه بومی تولید کند.

رفتار عادی جستجو

سرور منابع جستجو را به ترتیب زیر امتحان می‌کند:

1. نتایج بومی ISearchableViewer.
2. یک ایندکس جستجوی پیش‌ساخته .srh.
3. یک خطا/نتیجه خالی وقتی منبع جستجویی وجود ندارد.

CanSearch() می‌تواند برای یک Viewer قابل جستجو true باشد حتی وقتی سند اسکن‌شده خاصی لایهٔ متنی ندارد و بنابراین هیچ تطابقی برنمی‌گرداند.

مجوزدهی و رفتار UI

یک مجوز موقت/دموی فعال، جستجو را در دوره فعال خود اعطا می‌کند. عدم وجود مجوز و فایل قدیمی TRIAL هیچ قابلیت جستجویی را فراهم نمی‌کند. بدون جستجو:

• ReferenceCss و ReferenceScripts بسته‌های جستجو را حذف می‌کنند.
• میدل‌ویر جستجو را رد می‌کند به‌جای برگرداندن نتایج دارای مجوز.

قابلیت نمایش UI سفارشی را از IDoconutLicenseService.IsCapabilityGranted(LicenseCapability.Search) کنترل کنید و برای verdict جداگانهٔ فرمت/جلسه از CanSearch() استفاده کنید.

عیب‌یابی