بحث

يوفر عارض Doconut بحثًا عاديًا باستخدام النص المستخرج من عارض التنسيق أو إعادة توجيه PDF المعتمد على النص. يتطلب ذلك قدرة الترخيص Search.

تمكين واجهة البحث

البحث هو وحدة في العارض، وليس شريط أدوات مستقل. يجب أن تتضمن الصفحة الكاملة موارد العارض، شريط أدوات العارض، تثبيت العارض، وobjViewer المُهيأ؛ ثم يتم تثبيت شريط البحث وإرفاقه بنفس المثيل.

البحث والتعليقات التوضيحية هي ميزات مرخصة مدمجة، وليست حزم AddPlugin<T>(). اطلب موارد البحث من Viewer؛ يتم إصدار العلامات الخاصة بها فقط عندما يمنح الترخيص إمكانية البحث. لا تحتوي عروض MVC 5 على @inject، لذا قم بإنشاء العلامات في المتحكم ومررها عبر ViewBag، جنبًا إلى جنب مع علم الترخيص الذي تحتاجه الصفحة:

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss = true,
    IncludeSearchCss = true
});
ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery        = true,
    IncludeViewerScripts = true,
    IncludeSearchScripts = true,
    IncludeSearchBar     = true
});
ViewBag.IsSearchEnabled = viewer.IsSearchEnabled;

اكتبها في العرض باستخدام @Html.Raw(ViewBag.ViewerCss) و @Html.Raw(ViewBag.ViewerScripts). في Web Forms، عرّض القيم نفسها من الكود الخلفي واكتبها باستخدام <%= %>.

الشريط المدمج يستدعي نفس طرق JavaScript المتاحة لواجهة مستخدم مخصصة.

احتفظ بتكوين العارض الكامل مرئيًا في العلامات، قم بتهيئة docViewer أولاً، ثم أرفق الشريط المرخص:

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- عناصر تحكم العارض، بما في ذلك الزر الذي يفتح البحث -->
</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: '/',
        ResPath: 'doconut-res/images'
    });

    @if ((bool)ViewBag.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>

شرط if على جانب الخادم مهم: بدون قدرة البحث، تقوم ReferenceScripts بحذف سكريبت الشريط، لذا فإن استدعاء doconutSearchBar(...) غير محمي سيسبب استثناء ويتوقف تشغيل صفحة العارض. في Web Forms، اكتب الحماية نفسها كـ <% if (IsSearchEnabled) { %> … <% } %>.

المكوّن يحقن مجموعات البحث (Find) والخيارات (Options) والنتائج (Results) ويتعامل مع البحث، والمسح، وعدد المطابقات، والتنقل بين المطابقة السابقة/التالية. شريط أدوات العارض المملوك للمضيف يحتاج فقط إلى تبديله:

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

واجهة برمجة التطبيقات العامة لها صغيرة عن قصد:

استدعاء onToggle(isOpen) الاختياري يسمح للمضيف بمزامنة زر البحث الخاص به، وonLayout يسمح له بإعادة ضبط حجم/ملاءمة العارض عندما يتغير ارتفاع الشريط. للحصول على تسلسل بدء تشغيل العارض المشترك مع البحث والتعليقات التوضيحية، راجع البدء السريع.

البحث من جافاسكريبت

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

المعامل الثاني هو مطابقة كلمة كاملة/دقيقة. عدد التطابقات يصل في الدالة الراجعة: Search نفسها تتصل بالخادم ولا تُعيد شيئًا مفيدًا، لذا فإن var n = objViewer.Search(keyword, false) يقرأ دائمًا undefined — وتُظهر صفحة مُنشأة بهذه الطريقة "nothing found" بينما يبرز العارض التطابقات. بعد الدالة الراجعة:

DocImage.axd يجيب على search=<term> وexact=true|false بـ XML. استخدم واجهة برمجة التطبيقات للودجت بدلاً من تحليل تلك الاستجابة الداخلية بنفسك.

التحقق من قدرة البحث

تقرير استجابة التهيئة:

X-Doconut-Can-Search: 1

بعد التهيئة، objViewer.CanSearch() يُظهر نفس الحكم الخاص بالتنسيق/الجلسة. تُعيد false عندما يرسل الخادم 0؛ قبل الاستجابة، أو مع خادم أقدم يُهمل الرأس، يكون الافتراضي true.

ثلاث بوابات مستقلة لا يجب الخلط بينها:

يمكن أن يكون التنسيق قابلًا للبحث تقنيًا بينما الرخصة الحالية تمنع العملية.

تمكين الاستخراج حسب التنسيق

var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true   // اختياري: يسمح للمستخدم بسحب منطقة ونسخ نصها
});

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 → تحويل إلى PDF نصي → قابل للبحث
var token = await viewer.OpenDocumentAsync(path, new HtmlConfig { DefaultRender = false });

بالنسبة للعارضين الأصليين، CanSearch() يصف قدرة العارض؛ لكنه لا يضمن أن المستند المحدد يحتوي على نص قابل للاستخدام. يمكن لملف PDF تكون صفحاته صورًا ممسوحة ضوئيًا فقط أن ينتج صفر نتائج أصلية.

سلوك البحث العادي

يحاول الخادم مصادر البحث بهذا الترتيب:

1. نتائج ISearchableViewer الأصلية.
2. فهرس بحث .srh مُسبق الإنشاء.
3. خطأ/نتيجة فارغة عندما لا يوجد مصدر بحث.

CanSearch() يمكن أن يكون true لعارض قابل للبحث حتى عندما لا يحتوي مستند معين على طبقة نصية وبالتالي لا يُعيد أي تطابقات.

الترخيص وسلوك واجهة المستخدم

ترخيص مؤقت/تجريبي نشط يمنح البحث خلال فترة نشاطه. ترخيص مفقود وملف TRIAL القديم لا يمنح أي قدرة بحث. بدون البحث:

• ReferenceCss وReferenceScripts يحذفان حزم البحث.
• DocImage.axd يرفض طلبات البحث بدلاً من إرجاع النتائج.

تحكم في إظهار واجهة المستخدم المخصصة عبر IDoconutLicenseService.IsCapabilityGranted(LicenseCapability.Search) واستخدم CanSearch() للحكم المستقل على التنسيق/الجلسة.

استكشاف الأخطاء وإصلاحها