التعليقات التوضيحية

إضافة دعم التعليقات التوضيحية إلى العارض

تعمل التعليقات التوضيحية في Doconut في اتجاهين: يرسمها المستخدمون في أداة المتصفح ويقوم الخادم بحفظها لكل صفحة، أو يقوم الكود الخاص بك بإنشائها برمجياً وتحميلها إلى جلسة مفتوحة. في كلتا الحالتين تُعرض على الصفحات ويمكن دمجها في تصديرات PDF/PNG.

يتم التحكم في دعم التعليقات التوضيحية عبر قدرة الترخيص Annotation (تُمنح تلقائياً بموجب ترخيص مؤقت نشط).

تمكين واجهة المستخدم للتعليقات التوضيحية

التعليق هو وحدة في العارض، وليس شريط أدوات مستقل. يجب أن تتضمن الصفحة الكاملة موارد العارض، شريط أدوات العارض، تثبيت العارض، وobjViewer المُهيأ؛ ثم يتم تثبيت شريط التعليقات التوضيحية وربطه بنفس المثيل.

أصدر حزم التعليقات التوضيحية جنباً إلى جنب مع حزم العارض — فهي محكومة بالترخيص، لذا تظهر العلامات فقط عندما تكون القدرة متاحة:

html
@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  // شريط التعليقات التوضيحية المدمج
}))

احتفظ بتركيب العارض الكامل مرئياً في العلامات:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- عناصر التحكم في Viewer، بما في ذلك الزر الذي يفتح Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

تُنشئ حزمة التعليقات التوضيحية شريط الـ Ribbon داخل annBarMount؛ لا تحتاج إلى نسخ أزراره أو علامات الحوار. قم بتهيئة docViewer أولاً، ثم أنشئ الـ Ribbon فقط عندما يؤكد الخادم أن التعليقات التوضيحية مرخصة:

html
<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        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 مع دورة حياة العارض.

افتحه وأغلقه من أي شريط أدوات عارض مملوك للمضيف:

javascript
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):

csharp
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 و
    // المُعالج يحرقها في تصديرات الصورة/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).

تصدير مع دمج التعليقات

csharp
// 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");
});

تستخدم عمليات التصدير نفس أداة الحرق كما في العرض على الشاشة، لذا ما يراه المستخدمون هو ما يحتويه الملف — باستثناء تعليقات الصور، الموصوفة أدناه.

تعليقات الصور على مضيف داخلية تصدر كـ "Image blocked"

العارض و عملية التصدير يجلبان صورة ImageAnnotation's من أماكن مختلفة:

السطحمن يقوم بتنزيل الصورةعلى مضيف داخلية أو تطوير
العارض في المتصفحمتصفح المستخدمتظهر الصورة
ExportAnnotationsToPdfAsync / …PngZipAsyncالخادمعنصر نائب أحمر "Image blocked"

عندما يجلب الخادم صورةً ليدمجها، يرفض العناوين التي تعيد إلى الشبكات الخاصة: حلقة الإرجاع (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 ورسالة الخطأ باللون الأحمر حيث كانت ستظهر الصورة.

سير عمل الحفظ

  1. افتح المستند واحصل على رمزه.
  2. حمّل XML أو البيانات المشفّرة المخزّنة مسبقًا في ذلك الرمز.
  3. اسمح للأداة بقراءة وتحرير تعليقات الجلسة.
  4. استرجع XML باستخدام GetAnnotationXML(token) عندما يقرر تطبيقك حفظ البيانات.
  5. صدّر PDF/PNG عندما تكون نسخة مسطحة مطلوبة.
  6. أغلق جلسة المستند.

لا تستخدم رمز العارض غير الشفاف كمعرّف دائم للتعليقات. اربط بيانات التعليقات المحفوظة بمعرفات المستند والإصدار الخاصة بك.

ملاحظات الأمان والعرض

  • طلبات التعليقات تستخدم نفس أمان الجلسة/الرمز مثل طلبات الصفحات.
  • تحقق وتحكم في أي عنوان URL للصورة مقدم من المستخدم لتجنب تزوير الطلبات من جانب الخادم.
  • تطبق الصادرات نفس قرار الترخيص/العلامة المائية المخصّصة كما في عرض الصفحة على الشاشة.
  • الأحمال الكبيرة الحرة والصادرات عالية الدقة تزيد من استهلاك الذاكرة؛ اختبر المستندات الواقعية وقيم التكبير.

استكشاف الأخطاء وإصلاحها

العَرَضالفحص
شريط التعليقات مفقودقدرة Annotation وعلامات CSS/السكريبت الأربعة للتعليقات
دالة رد النداء للحفظ تُبلغ عن خطأانتهاء صلاحية الرمز/الجلسة والوسطية BasePath
ctlDoc_Created (أو دالة حدث أخرى) لا تُنفّذ أبداًاسم الدالة: معرف العارض + _ + الحدث، كدالة عامة
تعليقات C# لا تظهرترقيم الصفحات يبدأ من واحد والبيانات تم تحميلها إلى الرمز النشط
تعليق الصورة يظهر على الشاشة لكنه غير موجود في التصديرمضيف الصورة لديه عنوان خاص أو حلقة إرجاع — انظر أعلاه
المستند المفتوح مرة أخرى لا يحتوي على تعليقاتاحفظ XML/البيانات خارج جلسة العارض، ثم حمّلها إلى الرمز الجديد

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