بدء سريع

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

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

يجب أن يستهدف تطبيق المضيف بيئة تشغيل تدعم netstandard2.1 — .NET Core 3.0 أو أحدث.

إعداد الخادم

AddDoconut() يسجل الخدمات؛ UseDoconutResources() و UseDoconut() يربطان الوسيط. يجب أن يكون استدعاء الموارد أولاً. UseDoconut() يجيب على كل طلب يصل إليه، لذا قم بتركيبه كوسيط على فرع خاص به باستخدام app.Map. استدعاءات الجلسة مطلوبة أيضاً — أمان المستند الافتراضي في Doconut يتحقق من كل طلب صفحة مقابل حالة جلسة ASP.NET. حالة الجلسة تحتاج إلى ذاكرة تخزين مؤقت: AddDistributedMemoryCache() توفر واحدة. تطبيق MVC أو Razor Pages يسجلها بالفعل، لكن تطبيق واجهة برمجة تطبيقات بسيطة لا يفعل ذلك، وبدونها يتوقف التطبيق عند بدء التشغيل مع 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());

هذا الإعداد يحافظ على شكل طلب DocImage.axd التاريخي ويثبت وسيط المستند على فرع مطابق. هذا هو الترتيب الذي يجب نسخه عندما تنقل تطبيق .NET Standard موجود إلى الأمام، لأن العميل يواصل استدعاء نفس عنوان URL كما كان دائماً:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // حافظ على تمكين فحص الجلسة الخاص بـ Doconut's
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // حالة الجلسة تحتاج إلى ذاكرة تخزين مؤقت (MVC/Razor Pages يضيف واحدة بالفعل)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// مطلوب لتشفيرات متعددة البايت في بعض صيغ المستندات.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // BEFORE فرع المستند
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() لا يأخذ أي خيارات في هذا الإصدار — كل شيء تم نقله إلى AddDoconut(). MiddlewarePath هي قيمة تنسيق؛ لا تقوم بربط فرع ASP.NET Core بنفسها. مع فرع DocImage.axd أعلاه، يستخدم العميل BasePath: '/'؛ مع app.Map("/doconut", ...) من الإعداد البسيط، يستخدم BasePath: 'doconut'. ResourcesPath يقدم الحزمة المدمجة عند /doconut-res، وبالتالي مسار مورد صورة الواجهة هو ResPath: 'doconut-res/images'.

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

العارض هو النواة المطلوبة للصفحة. سطح العرض الخاص به يستخدم اثنين من 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 يحذّفان موارد وحدة اختيارية عندما
الرخصة الحالية لا تمنح تلك القدرة؛ لا يزال العارض الأساسي يبدأ.

هذه الاستدعاءات تستبدل ملفات السكريبت المنسوخة يدويًا. إذا كان التطبيق لا يزال يحمل ملفه الخاص
docViewer.js، documentLinks.js، أو docViewer.UI.js، احذف تلك الوسوم بمجرد أن
تعمل من الموارد المُصدرة — راجع دليل الترحيل.

تهيئة العارض

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

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // فرع DocImage.axd؛ 'doconut' مع app.Map("/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);
    }
});

أربع تفاصيل تحدد ما إذا كانت هذه الصفحة تعمل على الإطلاق:

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

كل هذه تفشل بصمت — راجع استكشاف الأخطاء وإصلاحها ودليل الترحيل.

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

تجميع حزمة المشاهد الكاملة

صفحة المشاهد الكاملة تثبت الأجزاء التالية معًا:

جزء من الحزمةالمتطلباتكيف يتم الاتصال
موارد المشاهد، التركيب، و 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>

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

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

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

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) =>
{
    // الرمز غير شفاف — سلّمه إلى الودجت، ولا تقم بتسجيله أو حفظه.
    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);
    });

لا يوجد شيء لتسخينه قبل الفتح الأول. إذا كنت تنقل تطبيقًا إلى الأمام، احذف أي استدعاء InitCache() والعلم الذي يحميه — الطريقة لم تعد موجودة.

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

استدعِ 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 ترخيصًا وما يتغيّر بمجرد العثور عليه.

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