التعليقات التوضيحية
إضافة دعم التعليقات التوضيحية إلى العارض
تعمل التعليقات التوضيحية في Doconut في اتجاهين: يرسمها المستخدمون في ودجت المتصفح ويقوم الخادم بحفظها لكل صفحة، أو يبنيها الكود الخاص بك برمجيًا ويحمّلها في جلسة مفتوحة. في كلتا الحالتين تُعرض على الصفحات ويمكن دمجها في تصديرات PDF/PNG.
يتم التحكم في دعم التعليقات التوضيحية عبر قدرة الترخيص Annotation (يُمنح تلقائيًا بموجب ترخيص مؤقت نشط).
تمكين واجهة المستخدم للتعليقات التوضيحية
التعليق هو وحدة Viewer، وليس شريط أدوات مستقل. يجب أن تشمل الصفحة الكاملة موارد Viewer، شريط أدوات Viewer، تثبيت Viewer، و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 // الشريط المدمج للتعليقات التوضيحية
}))احفظ تركيبة Viewer الكاملة مرئية في العلامات:
<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 مع دورة حياة العارض.
افتحه وأغلقه من أي شريط أدوات Viewer مملوك للمضيف:
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؛ تظل عناصر التحكم التي لا تملك نقطة نهاية مُكوَّنة مخفية.
للتسلسل الزمني لبدء تشغيل Viewer وSearch وAnnotation المدمجة، راجع البدء السريع.
تضيف حزمة التعليقات التوضيحية أدوات التأليف في المتصفح، لكن البيانات لا تزال تابعة لجلسة المستند على جانب الخادم المحددة بالرمز. إعادة فتح المصدر يخلق جلسة جديدة؛ احفظ ملف 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 و
// renderer يحرقها في تصديرات image/PDF.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});أنواع التعليقات التوضيحية
جميع الأنواع موجودة في Doconut.Annotations وتورث من BaseAnnotation (رقم الصفحة + حدود Rectangle):
| النوع | الملاحظات |
|---|---|
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
| العضو | الغرض |
|---|---|
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 من PNGs لكل صفحة
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 | الخادم | عنصر نائب أحمر "صورة محجوبة" |
عند قيام الخادم بجلب صورة لتضمينها، يرفض العناوين التي تشير إلى الشبكات الخاصة: حلقة الإرجاع (localhost, 127.0.0.1)، 0.0.0.0، المحلي للربط (169.254.x.x)، النطاقات الخاصة 10.x، 172.16–31.x، و192.168.x، NAT من فئة الناقل (100.64.0.0/10)، وعناوين IPv6 المحلي للربط والمحلية الفريدة. هذا يحمي الخادم من الاستخدام للوصول إلى الأنظمة الداخلية عبر عنوان صورة مُصمم، ولا يوجد مفتاح لإيقاف ذلك.
عنوان URL للصورة النسبي يُحلّ ضد مضيف الطلب الحالي، لذا على localhost، على خادم داخلية، أو على أي موقع يُوصل عبر عنوان خاص، تُظهر الصورة في العارض وتحتوي التصديرة على عنصر نائب بدلاً من ذلك. هذا هو عمل الحماية، وليس فشلًا في العرض. إذا كان يجب أن تحتوي الصادرات على الصورة، قدّمها من مضيف بعنوان عام واستخدم عنوان URL مطلق. اسم المضيف الذي لا يمكن حله يُرفض بنفس الطريقة؛ أي فشل آخر في التنزيل يعرض عنوان URL ورسالة الخطأ باللون الأحمر حيث كانت ستظهر الصورة.
سير عمل الاستمرارية
- افتح المستند واحصل على رمزه.
- حمّل XML أو البيانات المشفرة المخزنة مسبقًا في ذلك الرمز.
- اسمح للأداة بقراءة وتحرير تعليقات الجلسة.
- استرجع XML باستخدام
GetAnnotationXML(token)عندما يقرر تطبيقك حفظ البيانات. - صدّر PDF/PNG عندما يكون التسليم المسطح مطلوبًا.
- أغلق جلسة المستند.
لا تستخدم رمز العارض غير الشفاف كمعرّف دائم للتعليقات. اربط بيانات التعليقات المحفوظة بمعرفات المستند والإصدار الخاصة بك.
ملاحظات الأمان والعرض
- طلبات التعليقات تستخدم نفس أمان الجلسة/الرمز كما في طلبات الصفحات.
- تحقق وتحكم في أي عنوان URL للصورة مقدم من المستخدم لتجنب تزوير طلبات الخادم.
- التصديرات تطبق نفس قرار الترخيص/العلامة المائية المخصصة كما في عرض الصفحة على الشاشة.
- حمولات الرسم الحر الكبيرة والتصديرات عالية الدقة تزيد من استهلاك الذاكرة؛ اختبر المستندات الواقعية وقيم التكبير.
استكشاف الأخطاء وإصلاحها
| العَرَض | التحقق |
|---|---|
| شريط التعليقات مفقود | قدرة Annotation وعلامات CSS/السكريبت الأربعة للتعليقات |
| دالة رد النداء للحفظ تُبلغ عن خطأ | انتهاء صلاحية الرمز/الجلسة والوسط البرمجي BasePath |
ctlDoc_Created (أو دالة حدث أخرى) لا تُنفّذ أبدًا | اسم الدالة: معرف العارض + _ + الحدث، كدالة عامة |
| تعليقات C# لا تظهر | ترقيم الصفحات يبدأ من واحد والبيانات تم تحميلها في الرمز النشط |
| تعليق الصورة يظهر على الشاشة لكنه غير موجود في التصدير | مضيف الصورة لديه عنوان خاص أو حلقة إرجاع — انظر أعلاه |
| المستند المفتوح مرة أخرى لا يحتوي على تعليقات | احفظ XML/البيانات خارج جلسة العارض، ثم حمّلها في الرمز الجديد |
هل كانت هذه الصفحة مفيدة؟