البدء السريع
اعرض مستندك الأول في دقائق
هذا الدليل يأخذ تطبيق 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 مسبقاً أثناء التثبيت؟ انتقل إلى القسم التالي.
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());لتصميم مسار على نمط الإنتاج، قم بربط طبقة وساطة المستند بفرع صريح واحتفظ بأربعة إعدادات المسار متناسقة:
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 المتداخلة:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>عامل شريط الأدوات، تثبيت الوحدات، وسطح المشاهد كتركيب صفحة واحد. البحث والتعليق يدمجان أشرطةهما المدمجة في التثبيتات الاختيارية، لكن هذه الوحدات لا تكون مستقلة أبداً: فهي دائماً تُرفق بالمشاهد على نفس الصفحة. استخدم هذا الترتيب:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- أزرار Viewer للتنقل، التكبير، البحث، والتعليق التوضيحي -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>الإشارة إلى موارد المشاهد
في عرض Razor، الخدمة المُحقنة Viewer تُصدر وسوم <link> و <script> الخاصة بالمشاهد بترتيب الاعتماد — الودجت هو مكوّن jQuery، لذا يجب تحميل jQuery قبل سكريبتات المشاهد:
@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.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 يحذفان موارد وحدة اختيارية عندما لا تمنح الرخصة الحالية تلك القدرة؛ يظل المشاهد الأساسي يبدأ.
تهيئة العارض
القطعة الجانبية للعميل هي مكوّن إضافي لجـ jQuery. هذه مجموعة حدّية من خيارات التهيئة الحقيقية (ليس كودًا تجريبيًا):
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) |
على الرغم من أن شريط أدوات العارض الرئيسي هو علامة مضيف، فإنه يُثبت جنبًا إلى جنب مع العارض ولا يجب أبدًا توثيقه كعنصر منفصل. هذا يحافظ على تخطيطه، تسمياته، أيقوناته، وقواعد التفويض تحت سيطرة تطبيقك بينما كل زر يُشغّل نفس نسخة العارض:
<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">.
احفظ ترتيب التهيئة هذا:
- إصدار CSS للعارض والوحدات المرخصة.
- عرض شريط أدوات العارض، تركيبات البحث/التعليقات، وتركيب العارض معًا.
- إصدار السكريبتات للعارض والوحدات المرخصة.
- تحميل سكريبت المساعد الخاص بشريط أدوات تطبيق المضيف.
- تهيئة
docViewerوالاحتفاظ بـobjViewerالناتج. - تهيئة كل شريط بحث أو تعليقات مرخص.
- استدعاء
attach(objViewer)على كل شريط. - فتح المستند والاحتفاظ برمز الوصول الخاص به لطلبات العارض والوحدات.
في نشر موزّع، قيمة طلب access الإضافية وإعدادات إعادة المحاولة للعرض غير المتزامن تنتمي إلى النقل؛ فهي لا تغيّر طريقة تجميع العارض أو شريط الأدوات أو الأشرطة.
الحمايات على جانب الخادم مهمة: عندما تكون قدرة اختيارية غير متوفرة، لا يتم إصدار سكريبتها، وبالتالي لا توجد دالة المكوّن الإضافي لجـ jQuery الخاصة بها.
<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 المُحقنة تفتح المستند وتعيد رمز جلسة.
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):
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) يزيل فورًا الجلسة المخزنة مؤقتًا، ويُفرغ محرك العرض، ويحذف علامة الأمان الخاصة به، ويلغي الرمز. انتهاء الصلاحية المتدرج يقوم في النهاية بنفس عملية التنظيف، لكن يُنصح بالإغلاق الصريح للمستندات الكبيرة.
تدفق الطلب المكتمل هو:
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 الترخيص وما يتغيّر بمجرد حدوث ذلك.
هل كانت هذه الصفحة مفيدة؟