التعليقات التوضيحية
إضافة دعم التعليقات التوضيحية إلى العارض
تعمل التعليقات التوضيحية في Doconut في اتجاهين: يرسمها المستخدمون في ودجت المتصفح ويقوم الخادم بحفظها لكل صفحة، أو يقوم الكود الخاص بك بإنشائها برمجياً وتحميلها إلى جلسة مفتوحة. في كلتا الحالتين تُعرض على الصفحات ويمكن دمجها في تصديرات PDF/PNG.
يتم التحكم في دعم التعليقات التوضيحية عبر قدرة الترخيص Annotation (تُمنح تلقائياً بموجب ترخيص مؤقت نشط).
تمكين واجهة المستخدم للتعليقات التوضيحية
التعليق هو وحدة في العارض، وليس شريط أدوات مستقل. يجب أن تشمل الصفحة الكاملة موارد العارض، شريط أدوات العارض، تثبيت العارض، وobjViewer المهيأ؛ ثم يتم تثبيت شريط التعليق وربطه بنفس المثيل.
أصدر حزم التعليقات التوضيحية جنباً إلى جنب مع حزم العارض — فهي محكومة بالترخيص، لذا تظهر العلامات فقط عندما تكون القدرة متاحة:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // الشريط المدمج للتعليقات التوضيحية
}))احتفظ بتركيب العارض الكامل مرئياً في العلامات:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- عناصر تحكم العارض، بما في ذلك الزر الذي يفتح Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>تُنشئ حزمة التعليقات التوضيحية شريط الـ Ribbon داخل annBarMount؛ لا تحتاج إلى نسخ أزراره أو علامات الحوار. قم بتهيئة docViewer أولاً، ثم أنشئ الـ Ribbon فقط عندما يؤكد الخادم أن التعليق مرخص:
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: (message) => console.error('Viewer error:', message)
});
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token: currentToken }),
onStatus: (message) => console.log(message),
onToast: (message, type) => console.log(type, message),
onLayout: () => requestAnimationFrame(() => objViewer.Refit())
});
annBar.attach(objViewer);
</text>
}
</script>بدون هذه القدرة، يترك ReferenceScripts سكريبت الـ Ribbon، لذا يحافظ if على جانب الخادم من استدعاء غير محمي لـ doconutAnnotationBar(...) لتجنب كسر الصفحة.
يقوم الحفظ من الـ Ribbon بإرسال البيانات عبر الوسيط (AnnSave)، الذي يخزنها في جلسة المستند لكل صفحة. يحدث التحميل (AnnLoad) تلقائياً عندما يتم عرض صفحة تحتوي على تعليقات توضيحية. تحافظ الاستدعاءات الأربعة لـ onAnn* على تزامن الـ Ribbon مع دورة حياة العارض.
افتحه وأغلقه من أي شريط أدوات عارض مملوك للمضيف:
annBar.open();
annBar.close();واجهة برمجة التطبيقات العامة للـ Ribbon هي:
| الطريقة | الغرض |
|---|---|
attach(objViewer) | ربط الـ Ribbon بالعارض المهيأ؛ مطلوب مرة واحدة |
open() / close() | بدء أو إنهاء تحرير التعليقات التوضيحية |
reset() | إرجاع الـ Ribbon إلى حالته المغلقة غير القابلة للتحرير |
isOpen() / annotating() | قراءة حالة الـ Ribbon / حالة تحرير التعليقات في العارض |
reopenEditable() | إعادة تحميل تعليقات الصفحة الحالية ككائنات قابلة للتحرير |
updateActionState() | تحديث توفر عناصر التحكم بالحفظ/الحذف بعد تغييرات المضيف |
headerSlot() | الحصول على فتحة توسيع الرأس الاختيارية لعناصر التحكم المملوكة للمضيف |
onStatus، onToast، onLayout، onEditStart، وonEditEnd هي استدعاءات اختيارية من المضيف. يمكن لكائن endpoints أن يوفر إضافياً exportPdf، exportPng، imageUpload، وimageList؛ تظل عناصر التحكم التي لا تملك نقطة نهاية مكوّنة مخفية.
لسلسلة بدء تشغيل العارض المشترك مع البحث والتعليقات التوضيحية، راجع البدء السريع.
تضيف حزمة التعليقات التوضيحية أدوات التأليف في المتصفح، لكن البيانات لا تزال تابعة لجلسة المستند على جانب الخادم المحددة بالرمز. إعادة فتح المصدر ينشئ جلسة جديدة؛ احفظ ملف XML أو الغلاف المشفر للتعليقات في تطبيقك إذا كان يجب أن تبقى التعليقات موجودة بعد انتهاء مدة الجلسة.
نوعان من رد النداء، موصلان بطريقتين
يستخدم رمز التعليقات التوضيحية نمطين من رد النداء، وكل منهما يفشل بصمت عندما يُوصل بالطريقة الأخرى:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedهي خيارات لـdocViewer({...})، مثل كل رد نداء للعارض.Created,Changed,Deleted, وPropertiesهي دوال عالمية تُعثر عليها بالاسم: معرف العارض يُسبق الحدث. بالنسبة للعارض في#div_ctlDocالمعرف هوctlDoc، لذا الدوال هيctlDoc_Created,ctlDoc_Changed,ctlDoc_Deleted, وctlDoc_Properties. الدالة التي تم تهجئتها خطأً أو إعادة تسميتها ببساطة لا تُستدعى أبداً.
SaveAnnotations() لا تُعيد ما إذا تم الحفظ: النتيجة تصل عبر onAnnSaved أو onAnnSaveError. الشيفرة التي تقرأ قيمة إرجاعها لا تُزيل علم "التغييرات غير المحفوظة" أبداً.
إنشاء التعليقات التوضيحية في C#
احصل على مدير مرتبط بالجلسة المفتوحة، أضف التعليقات التوضيحية، وحمّلها (باستخدام using Doconut.Annotations; للأنواع وusing System.Drawing; لـ Rectangle/Color):
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
// مقيد بأبعاد صفحة الجلسة المفتوحة
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// ختم واحد لكل صفحة
for (int page = 1; page <= pageCount; page++)
{
manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
$"PAGE {page}", 28, 4, Color.Maroon)
{
Opacity = 60,
Rotate = -8
});
}
manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
"Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));
// تحميل إلى الجلسة — الودجت يجلبها عبر AnnLoad و
// المُعالج يحرقها في تصديرات image/PDF.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});أنواع التعليقات التوضيحية
جميع الأنواع موجودة في Doconut.Annotations وتورّث من BaseAnnotation (رقم الصفحة + حدود Rectangle):
| Type | Notes |
|---|---|
StampAnnotation | ختم نصي بحجم الخط، حد، لون؛ يدعم Opacity، Rotate |
NoteAnnotation | ملاحظة لاصقة بنص، لون خلفية، حجم خط، TitleColor |
RectangleAnnotation | ألوان حد + تعبئة، Title/ShowTitle |
CircleAnnotation | حد + تعبئة، ShowBorder |
EllipseAnnotation | حد + تعبئة، ShowBorder |
TriangleAnnotation | لون الحد، BackColor، ShowBorder |
LineAnnotation | خط مستقيم بعرض ولون |
ArrowAnnotation | خط مع رأس سهم؛ يمكن ضبط Direction (نوع ArrowDirection، نقاط البوصلة، الافتراضي E) |
FreehandAnnotation | ضربة حرة من نقاط FreehandData المشفرة |
ImageAnnotation | صورة من عنوان URL. عنوان URL نسبي يُحلّ ضد مضيف الطلب عندما تُضاف التعليقة؛ الخادم يجلب الصورة فقط عند وقت الحرق — انظر ملاحظة التصدير أدناه |
واجهة برمجة تطبيقات AnnotationManager
| Member | Purpose |
|---|---|
Add(BaseAnnotation) | وضع تعليق في الطابور |
GetAnnotations() / GetAnnotations(int page) | فحص ما يحتفظ به المدير |
ClearAnnotations() / ClearAnnotations(int page) | إزالة الكل / لكل صفحة |
GetAnnotationData() / GetAnnotationData(int page) | سلسلة بيانات التعليق المشفرة — غلاف Base64 (ما يستهلكه الودجت) |
GetAnnotationXml() | نموذج XML |
Viewer يطابق عمليات التحميل/القراءة مقابل جلسة: LoadAnnotationData(token, manager) أو LoadAnnotationData(token, encodedData) (غلاف Base64 من GetAnnotationData())، LoadAnnotationXML(token, xml)، GetAnnotationXML(token).
تصدير مع دمج التعليقات التوضيحية
// PDF لجميع الصفحات مع التعليقات التوضيحية المرسومة عليها
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
return Results.File(pdf, "application/pdf", "export.pdf");
});
// أو ملف ZIP لملفات PNG لكل صفحة
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
return Results.File(zip, "application/zip", "annotations-png.zip");
});تستخدم عمليات التصدير نفس أداة الحرق كما في العرض على الشاشة، لذا ما يراه المستخدمون هو ما يحتويه الملف — باستثناء تعليقات الصور، الموضحة أدناه.
تعليقات الصور على مضيف داخلية تُصدّر كـ "تم حظر الصورة"
العارض والتصدير يجلبان صورة ImageAnnotation من أماكن مختلفة:
| السطح | من يقوم بتنزيل الصورة | على مضيف داخلية أو تطوير |
|---|---|---|
| العارض في المتصفح | متصفح المستخدم | تظهر الصورة |
ExportAnnotationsToPdfAsync / …PngZipAsync | الخادم | عنصر نائب أحمر "تم حظر الصورة" |
عند قيام الخادم بجلب صورة لإدماجها، يرفض العناوين التي تعيد إلى الشبكات الخاصة: loopback (localhost, 127.0.0.1)، 0.0.0.0، link‑local (169.254.x.x)، النطاقات الخاصة 10.x، 172.16–31.x، و192.168.x، carrier‑grade NAT (100.64.0.0/10)، وعناوين IPv6 link‑local والعناوين الفريدة المحلية. يحمي هذا الخادم من استخدامه للوصول إلى الأنظمة الداخلية عبر عنوان صورة مُصمم، ولا يوجد مفتاح لإيقاف ذلك.
عنوان URL للصورة النسبي يُحلّ ضد مضيف الطلب الحالي، لذا على localhost، أو على خادم داخلية، أو على أي موقع يُوصل عبر عنوان خاص، تُظهر الصورة في العارض وتحتوي التصديرة على عنصر نائب بدلاً من ذلك. هذا هو عمل الحماية، وليس فشلًا في العرض. إذا كان يجب أن تحتوي الصادرات على الصورة، قدمها من مضيف بعنوان عام واستخدم عنوان URL مطلق. يُرفض اسم المضيف الذي لا يمكن حله بنفس الطريقة؛ أي فشل آخر في التنزيل يُظهر عنوان URL ورسالة الخطأ باللون الأحمر حيث ستكون الصورة.
سير عمل الحفظ
- افتح المستند واحصل على رمزه.
- حمّل XML أو البيانات المشفّرة المخزنة مسبقًا إلى ذلك الرمز.
- اسمح للودجت بقراءة وتحرير تعليقات الجلسة.
- استرجع XML باستخدام
GetAnnotationXML(token)عندما يقرر تطبيقك حفظ البيانات. - صدّر PDF/PNG عندما يكون التسليم المسطح مطلوبًا.
- أغلق جلسة المستند.
لا تستخدم رمز العارض غير الشفاف كمعرّف دائم للتعليقات. اربط بيانات التعليقات المحفوظة بمستندك ومعرّفات الإصدار الخاصة بك.
ملاحظات الأمان والعرض
- طلبات التعليقات تستخدم نفس أمان الجلسة/الرمز مثل طلبات الصفحات.
- تحقق من صحة أي عنوان URL للصورة مقدم من المستخدم وتحكم فيه لتجنب تزوير الطلبات من جانب الخادم.
- تطبق الصادرات نفس قرار الترخيص/العلامة المائية المخصصة كما في عرض الصفحات على الشاشة.
- الأحمال الكبيرة اليدوية والصادرات عالية الدقة تزيد من استهلاك الذاكرة؛ اختبر المستندات الواقعية وقيم التكبير.
استكشاف الأخطاء وإصلاحها
| العَرَض | الفحص |
|---|---|
| شريط التعليقات مفقود | قدرة Annotation وأربع علامات CSS/سكريبت للتعليقات |
| استدعاء الحفظ يُبلغ عن خطأ | انتهاء صلاحية الرمز/الجلسة والوسطية BasePath |
ctlDoc_Created (أو دالة حدث أخرى) لا تُنفّذ أبدًا | اسم الدالة: معرف العارض + _ + الحدث، كدالة عامة |
| تعليقات C# لا تظهر | ترقيم الصفحات يبدأ من الواحد والبيانات تم تحميلها إلى الرمز النشط |
| يظهر تعليق الصورة على الشاشة لكنه غير موجود في التصدير | مضيف الصورة لديه عنوان خاص أو loopback — انظر أعلاه |
| المستند المعاد فتحه لا يحتوي على تعليقات | احفظ XML/البيانات خارج جلسة العارض، ثم حمّلها إلى الرمز الجديد |
هل كانت هذه الصفحة مفيدة؟