بدء سريع

اعرض مستندك الأول في دقائق

يأخذك هذا الدليل من تطبيق ASP.NET Core فارغ Program.cs إلى مستند يُعرض في المتصفح: تسجيل الخادم، حزمة المشاهد الكاملة (شريط أدوات المشاهد، تثبيت المشاهد، وأشرطة البحث/التعليق الاختيارية)، مراجع الأصول، تهيئة العميل، فتح المستند، والتنفيذ.

إعداد الخادم

AddDoconut() يسجل الخدمات؛ UseDoconutResources() و UseDoconut() يربطان الطبقة الوسيطة. يجب أن يكون استدعاء الموارد أولاً. UseDoconut() يجيب على كل طلب يصل إليه، لذا قم بتركيبه على فرعه الخاص باستخدام app.Map. استدعاءات الجلسة مطلوبة أيضاً — أمان المستند الافتراضي لـ Doconut يتحقق من كل طلب صفحة مقابل حالة جلسة ASP.NET. حالة الجلسة تحتاج إلى ذاكرة تخزين مؤقت: AddDistributedMemoryCache() يوفر واحدة. تطبيق MVC أو Razor Pages يسجلها بالفعل، لكن تطبيق minimal-API لا يفعل ذلك، وبدونها يتوقف التطبيق عند بدء التشغيل مع Unable to resolve service for type 'IDistributedCache'. هل قمت بتسجيل Doconut بالفعل أثناء التثبيت؟ انتقل إلى القسم التالي.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // حالة الجلسة تحتاج إلى ذاكرة تخزين مؤقت (MVC/Razor Pages تضيف واحدة بالفعل)
builder.Services.AddSession(); // أمان مستند Doconut يعتمد على حالة جلسة ASP.NET

app.UseSession();          // استدعِ UseSession() قبل UseDoconut()
app.UseDoconutResources(); // يجب تسجيله قبل UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

لتصميم مسار على نمط الإنتاج، قم بربط طبقة وسائط المستند بفرع صريح وحافظ على توافق إعدادات المسارات الأربعة:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath هي قيمة تنسيق؛ لا تقوم بربط فرع ASP.NET Core بنفسها. في هذا المثال يقوم المضيف بربط /doconut، لذا يستخدم العميل BasePath: 'doconut'. ResourcesPath يخدم الحزمة المدمجة عند /doconut-res، وبالتالي يكون مسار مورد صورة الودجة هو ResPath: 'doconut-res/images'. اكتب كلاهما بدون شرطة مائلة في البداية: المشاهد يضيف واحدة بنفسه، لذا سيصبح '/doconut' إلى //doconut/DocImage.axd، والذي يقرأه المتصفح كطلب إلى مضيف يُدعى doconut، ويفشل المشاهد مع "لم يتم الوصول إلى معالج المشاهد".

إضافة المشاهد إلى صفحة

المشاهد هو النواة المطلوبة للصفحة. سطح العرض الخاص به يستخدم اثنين من div المتداخلة:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

اعتبر شريط الأدوات، تثبيت الوحدات، وسطح المشاهد كتركيب صفحة واحد. البحث و التعليق يدمجان أشرطةهما المدمجة في التثبيتات الاختيارية، لكن هذه الوحدات لا تكون مستقلة أبداً: فهي دائمًا تُرفق بالمشاهد على نفس الصفحة. استخدم هذا الترتيب:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- أزرار التنقل، التكبير، البحث، والتعليقات التوضيحية للعارض -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

الإشارة إلى موارد المشاهد

في عرض Razor، الخدمة Viewer المُدخلة تُصدر وسوم <link> و <script> الخاصة بالمشاهد بترتيب الاعتماد — الودجة هي مكوّن jQuery، لذا يجب تحميل jQuery قبل سكريبتات المشاهد:

html
@inject Doconut.Viewer Viewer

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

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

للحصول على حزمة المشاهد الكاملة، اطلب موارد المشاهد والوحدة معًا:

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

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

IncludeViewerCss و IncludeViewerScripts هما العلامتان الأساسيتان الإجباريتان. لا تنشر أبدًا مثال شريط البحث أو التعليق بدونهما، أو تثبيت المشاهد، أو مثيل docViewer. ReferenceCss و ReferenceScripts يحذّفان موارد وحدة اختيارية عندما لا تمنح الرخصة الحالية تلك القدرة؛ لا يزال المشاهد الأساسي يبدأ.

تهيئة العارض

الودجت على جانب العميل هو مكوّن إضافي لجQuery. هذه مجموعة الحد الأدنى من خيارات التهيئة الحقيقية (ليس كودًا تجريديًا):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   'doconut',             // لا توجد '/' في البداية
    ResPath:    'doconut-res/images',  // لا توجد '/' في البداية
    onViewerReady: function () {
        // الصفحات مرئية؛ من الآمن إخفاء مؤشر التحميل هنا
    },
    // تمرير أحداث دورة حياة التعليقات التوضيحية إلى الشريط المدمج عندما يكون موجودًا.
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

تنسيق الأحرف للخيارات مختلط حقًا — showThumbs و autoLoad و pageZoom بصيغة camelCase، بينما FitType و BasePath و ResPath بصيغة PascalCase. لا توجد قاعدة ثابتة؛ إذا أخطأت في تنسيق الأحرف سيتم تجاهل الخيار بصمت (يعود الودجت إلى الإعداد الافتراضي بدلاً من إلقاء خطأ).

أربعة تفاصيل أخرى تفشل دون رسالة خطأ:

  • BasePath لا يحتوي على شرطة مائلة في البداية. 'doconut' يطلب /doconut/DocImage.axd؛ '/doconut' ينتج //doconut/DocImage.axd، الذي يقرأه المتصفح كطلب إلى مضيف آخر.
  • ResPath: 'doconut-res/images' — الأيقونات موجودة في مجلد واحد أسفل جذر الموارد. مع 'doconut-res'، كل أيقونة تُعيد خطأ 404: لا توجد رموز شريط أدوات ولا مؤشر تحميل، بينما لا يزال المستند يُعرض. الشرطة المائلة في البداية تُكسر ذلك بنفس طريقة BasePath.
  • النداءات الراجعة هي خيارات. onViewerReady و onError والبقية تُوضع في الكائن الممرّر إلى docViewer(...). الدالة العامة المسماة باسم العارض، مثل ctlDoc_ViewerReady، لا تُستدعى أبدًا.
  • احتفظ بالعارض، ثم استدعِ View بشكل منفصل. docViewer(...) يُعيد الكائن مع Zoom و Next و FitType؛ View(...) يُعيد شيء آخر. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) يعرض المستند، ثم يفشل مع objViewer.Zoom is not a function عند أول نقرة على شريط الأدوات.

تجميع حزمة العارض الكاملة

صفحة عارض كاملة تثبت الأجزاء التالية معًا:

جزء من الحزمةالمتطلباتكيفية الاتصال
موارد العارض، التركيب، و objViewerمطلوبمُعالج المستند الأساسي
شريط أدوات العارضمطلوب لصفحة كاملةعلامات المضيف؛ الأزرار تستدعي نفس objViewer
شريط البحثاختياري، وحدة مرخصةdoconutSearchBar(...).attach(objViewer)
شريط التعليقاتاختياري، وحدة مرخصةdoconutAnnotationBar(...).attach(objViewer)

على الرغم من أن شريط أدوات العارض الرئيسي هو علامات مضيف، فإنه يُثبت جنبًا إلى جنب مع العارض ولا يجب أبدًا توثيقه كعنصر منفصل. هذا يحافظ على تخطيطه، تسمياته، أيقوناته، وقواعد التفويض تحت سيطرة تطبيقك بينما كل زر يُشغّل نفس نسخة العارض:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
    <button type="button" onclick="objViewer.FitType('height')">Fit height</button>
    <button type="button" id="openSearch">Search</button>
    <button type="button" id="openAnnotations">Annotations</button>
</nav>

المساعدات الخاصة بالدوران، المصغرات، الطباعة، وضع ملء الشاشة، التخطيط، وحالة الأزرار يجب أن تكون في سكريبت شريط الأدوات الخاص بك، الذي يستدعي نفس objViewer. حمّله بعد Viewer.ReferenceScripts(...)، واحفظه مع علامات <nav id="toolbar"> الخاصة به.

احتفظ بترتيب التهيئة هذا:

  1. أصدر CSS للعارض والوحدات المرخصة.
  2. اعرض شريط أدوات العارض، تركيبات البحث/التعليقات، وتركيب العارض معًا.
  3. أصدر السكريبتات للعارض والوحدات المرخصة.
  4. حمّل سكريبت مساعد شريط الأدوات الخاص بتطبيق المضيف.
  5. تهيئة docViewer واحتفظ بـ objViewer الناتج.
  6. تهيئة كل شريط بحث أو تعليق مرخص.
  7. استدعِ attach(objViewer) على كل شريط.
  8. افتح المستند واحتفظ برمز الوصول الخاص به لطلبات العارض والوحدات.

في نشر موزّع، قيمة الطلب الإضافية access وإعدادات إعادة المحاولة للعرض غير المتزامن تتبع النقل؛ لا تغير طريقة تجميع العارض أو شريط الأدوات أو الأشرطة.

الحمايات من جانب الخادم مهمة: عندما تكون قدرة اختيارية غير متاحة، لا يُصدر سكريبتها، وبالتالي لا توجد دالة المكوّن الإضافي لجQuery الخاصة بها.

html
<script>
    let token = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    annBar.attach(objViewer);
        </text>
    }

    document.getElementById('openSearch').addEventListener('click', () => {
        if (!searchBar) return;
        searchBar.isOpen() ? searchBar.close() : searchBar.open();
    });

    document.getElementById('openAnnotations').addEventListener('click', () => {
        if (!annBar) return;
        annBar.isOpen() ? annBar.close() : annBar.open();
    });
</script>

كلا المكوّنين المدمجين يولدان DOM خاص بهما للأشرطة. يحتوي البحث على مجموعات العثور، الخيارات، والنتائج. يحتوي التعليق على أدوات التأليف، عناصر التحكم في النمط، إجراءات الحفظ، وإجراءات التصدير/الصورة الاختيارية. تعرض الأشرطة open() و close() و reset() و isOpen()؛ استدعِ دائمًا attach(objViewer) مرة واحدة بعد إنشائها.

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

فتح مستند

جانب الخادم هو نقطة نهاية واحدة: الخدمة Viewer المُحقنة تفتح المستند وتعيد رمز جلسة.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // الرمز غير شفاف — قدّمه إلى widget، ولا تقم بتسجيله أو حفظه.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

العميل يجلب ذلك الرمز ويقدمه إلى الواجهة باستخدام objViewer.View(token):

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

إغلاق المستند

استدعِ objViewer.Close(true) عندما يغادر المستخدم العارض أو يفتح مستندًا بديلاً: يقوم بمسح الواجهة وإرسال طلب إغلاق إلى الخادم. objViewer.Close() بدون أي وسيط يمسح الواجهة فقط. في سير العمل المدفوع من الخادم، viewer.CloseDocument(token) يزيل جلسة التخزين المؤقت فورًا، ويُفرغ محرك العرض، ويحذف العلامة الأمنية الخاصة به، ويلغي الرمز. انتهاء الصلاحية المتدرج يؤدي في النهاية إلى نفس عملية التنظيف، لكن الإغلاق الصريح يُنصح به للمستندات الكبيرة.

تدفق الطلب المكتمل هو:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

عامل الرمز كبيان حامل: لا تُسجّله أبداً، ولا تُخزّنه أبداً، وقدّمه فقط إلى الواجهة. هو يحدد جلسة مستند حية على الخادم ويتوقف عن العمل عندما تنتهي صلاحية تلك الجلسة — أعد فتح المستند للحصول على رمز جديد.

تشغيله

ضع ملف PDF في wwwroot/files/Sample.pdf، شغّل dotnet run، وافتح الصفحة التي تستضيف الواجهة. الصفحة الأولى تُعرض في العارض، مع لوحة مصغرات على اليسار. إذا لم يحدث ذلك، راجع استكشاف الأخطاء وإصلاحها.

ما ستحصل عليه بدون ترخيص

عدم وجود ترخيص لا يسبب خطأ. العارض يعرض بشكل طبيعي، لكن كل صفحة تحمل علامة مائية للتقييم. راجع إعداد الترخيص لمعرفة كيف يجد Doconut ترخيصًا وما يتغير بمجرد حصوله.

هل كانت هذه الصفحة مفيدة؟