البدء السريع
عرض مستندك الأول في MVC 5 أو Web Forms
هذا الدليل يأخذ تطبيق ASP.NET على .NET Framework 4.7.2 من حزمة مثبتة إلى مستند يُعرض في المتصفح: Global.asax، نقطة نهاية مفتوحة، أصول المشاهد، الودجت، والرمز المميز الذي يربطهم. يفترض أن تسجيلات Web.config من التثبيت موجودة — بدون معالج DocImage.axd ووحدة الموارد، لا يمكن لأي شيء أدناه الوصول إلى الخادم.
إنشاء Doconut في Global.asax
مثال كامل لـ Application_Start لتطبيق MVC 5:
// Global.asax.cs - إنشاء مرة واحدة لكل عملية عامل، تحرير عند الإغلاق.
protected void Application_Start()
{
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.UnsafeMode = false; // يتم تقديم الصفحة فقط للجلسة التي فتحت المستند
});
// MVC فقط: احتفظ بنقطتي النهاية Doconut خارج التوجيه.
RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}
protected void Application_End()
{
Doconut.DoconutHost.Shutdown();
}Encoding.RegisterProviderيجعل صفحات الكود القديمة التي تستخدمها بعض تنسيقات المستندات متاحة للمعالجة. استدعِه مرة واحدة، قبل فتح أول مستند.UnsafeMode = falseهو الإعداد الافتراضي، مكتوب لتجنب تغييره عن طريق الخطأ:DocImage.axdيخدم صفحة فقط لجلسة ASP.NET التي فتحت المستند.- النداءين
IgnoreRouteيبقيان توجيه MVC بعيدًا عنDocImage.axdو/doconut-res/*، التي يخدمها المعالج والوحدة. تطبيق Web Forms لا يحتوي على مسارات MVC ولا يحتاج إلى هذا السطر. DoconutHost.Shutdownيوقف عمل Doconut الخلفي ويحرر خدماته عندما يتم إعادة تدوير مجموعة التطبيقات. من الآمن استدعاؤه حتى إذا لم يتم تشغيلInitializeأبداً.
فتح مستند
فتح مستند يُعيد رمزًا مميزًا غير شفاف. يرسل الودجت هذا الرمز مع كل طلب صفحة.
في MVC 5، تقوم إجراء وحدة التحكم بحل خدمة Viewer من DoconutHost.Services — لا يدعم MVC 5 حقن الباني لهذه الخدمة:
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
// الرمز المميز غير شفاف - قدّمه إلى المشاهد، ولا تسجّله أو تحتفظ به أبداً.
string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
return Json(new { token });
}يجب فتح المستند داخل طلب يحتوي على حالة جلسة، لأن فتحه هو ما يمنح جلسة ASP.NET الحالية الوصول إلى صفحاته. وحدات تحكم MVC وصفحات Web Forms لديها حالة جلسة بشكل افتراضي. الـ IHttpHandler المخصص لا يمتلك ذلك، إلا إذا كان ينفذ System.Web.SessionState.IRequiresSessionState. افتح مستندًا من معالج بدون ذلك، سيظهر المشاهد الرسالة "أنت غير مخول لعرض هذه الصفحة." على كل صفحة.
في Web Forms، يمكن للصفحة نفسها فتح المستند في الكود الخلفي. OpenDocument هو الشكل المتزامن لـ OpenDocumentAsync، مخصص للكود الخلفي الذي لا يستخدم الصفحات غير المتزامنة:
// Default.aspx.cs
protected string Token;
protected void Page_Load(object sender, EventArgs e)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}عامل الرمز المميز كبيان اعتماد حامِل: لا تقم بتسجيله أو تخزينه؛ سلّمه فقط للودجت. يتوقف عن العمل عندما تنتهي جلسة المستند — افتح المستند مرة أخرى للحصول على رمز جديد.
الإشارة إلى أصول العارض
Viewer.ReferenceCss و Viewer.ReferenceScripts ينتجان العلامات <link> و <script> للأصول المدمجة، بترتيب الاعتماد، مشيرين إلى /doconut-res/. الودجت هو مكوّن jQuery، لذا يأتي jQuery أولاً.
MVC 5. لا تحتوي العروض على @inject، لذا يتم إنتاج العلامات في المتحكم وتمريرها عبر ViewBag:
public ActionResult Index()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
});
ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
});
return View();
}@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)احتفظ بهذا العمل في المتحكم. يقوم MVC 5 بتجميع العروض عندما تُقدَّم لأول مرة، وبدون حزمة مترجم إضافية فإن هذا المترجم لا يفهم سوى C# 5 — لا ?.، لا $"..."، لا nameof. العرض الذي يستخدمها يُجمّع بنجاح في Visual Studio، ثم يُعيد 500 فارغًا في المتصفح.
Web Forms. اكشف عن نفس السلاسل من الكود الخلفي واكتبها باستخدام <%= %>:
<head>
<%= ViewerCss %>
</head>
<body>
...
<%= ViewerScripts %>
</body>IncludeViewerCss و IncludeViewerScripts هما النواة الإلزامية. لإضافة أشرطة البحث والتعليق، قم أيضًا بتعيين IncludeSearchCss، IncludeAnnotationCss، IncludeSearchScripts، IncludeSearchBar، IncludeAnnotationScripts و IncludeAnnotationBar. كلا الطريقتين تترك ملفات الشريط عندما لا تمنح الرخصة هذه القدرة؛ يظل العارض نفسه يبدأ.
إضافة العارض إلى صفحة
سطح العرض هو اثنان من div متداخلة:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>امنح الـ div الخارجي ارتفاعًا حقيقيًا — يملأ العارض حاويته ويقيسه عند البدء. لا يرسم العارض شريط أدواته الخاص: GotoPage، Next، Zoom، FitType والبقية هي طرق يربطها صفحتك بأزرارها الخاصة، موضوعة بجانب العارض:
<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.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>
</nav>تهيئة العارض وعرض المستند
بعد سكريبتات العارض، أنشئ الودجت، ثم أعطه الرمز المميز:
var objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: '/', // '/' يعني DocImage.axd في جذر الموقع
ResPath: 'doconut-res/images', // لا يوجد '/' في البداية
onViewerReady: function () {
// الصفحات مرئية; إخفاء مؤشر التحميل هنا
},
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});
fetch('/Document/Open', { method: 'POST' })
.then(function (resp) { return resp.json(); })
.then(function (data) { objViewer.View(data.token); });في Web Forms، حيث فتحت الصفحة المستند نفسها، تصبح السطور الثلاث الأخيرة objViewer.View('<%= Token %>');.
أربعة تفاصيل هنا تفشل دون رسالة خطأ:
BasePath: '/'يشير إلىDocImage.axdفي جذر الموقع. لتطبيق في دليل افتراضي، استخدم اسمه بدون شرطات مائلة ('myapp'يطلب/myapp/DocImage.axd). الشرط المائل الأولي ('/myapp') ينتج//myapp/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عند أول نقرة على شريط الأدوات.
أسماء الخيارات تمزج بين camelCase (showThumbs، autoLoad، pageZoom) و PascalCase (FitType، BasePath، ResPath). يتم تجاهل الخيار المكتوب بشكل خاطئ، ويستخدم الودجت القيمة الافتراضية.
البديل ذو السطر الواحد
لصفحة تحتاج فقط إلى عرض مستند، دون شريط أدوات خاص بك، Viewer.RenderViewer يكتب برنامج التهيئة الكامل — docViewer(...) مع BasePath: '/' و ResPath: 'doconut-res/images'، ثم .View(token). وهو موجود فقط في هذه الحزمة:
// Default.aspx.cs
protected string ViewerInit;
protected void Page_Load(object sender, EventArgs e)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>مرّر ViewerConfig كوسيط ثالث لتغيير التكبير، أو الملاءمة، أو لوحة المصغرات. لأن البرنامج النصي المُولد لا يحتفظ بأي إشارة إلى العارض، استخدم التهيئة المكتوبة يدوياً أعلاه عندما تحتاج صفحتك إلى شريط أدوات خاص بها.
إغلاق المستند
استدعِ objViewer.Close(true) عندما يغادر المستخدم العارض أو يفتح بديلاً: فهو يمسح الودجت ويرسل طلب إغلاق إلى DocImage.axd. objViewer.Close() بدون أي وسيط يمسح الودجت فقط. على الخادم، viewer.CloseDocument(token) يزيل جلسة المستند فوراً، يحرّر موارد العرض الخاصة به، ويسحب وصول الجلسة إلى صفحاته. انتهاء الصلاحية المتدرج يحقق نفس النتيجة في النهاية، لكن إغلاق المستندات الكبيرة صراحةً يحرّر الذاكرة أسرع.
تشغيله
ضع ملف PDF في ~/files/Sample.pdf، شغّل الموقع في IIS Express (F5 في Visual Studio)، وافتح الصفحة التي تستضيف الودجت. تُظهر الصفحة الأولى، مع المصغرات على اليسار. إذا لم يحدث ذلك، راجع استكشاف الأخطاء وإصلاحها.
ما ستحصل عليه بدون ترخيص
غياب الترخيص لا يسبب خطأ. العارض يعرض بشكل طبيعي، لكن كل صفحة تحمل علامة مائية للتقييم. راجع إعداد الترخيص لمعرفة أين يبحث Doconut عن ترخيصك.
هل كانت هذه الصفحة مفيدة؟