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

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

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

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

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

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

أصدر ملفات التعليقات التوضيحية مع ملفات العارض. هي محكومة بالترخيص، لذا تظهر وسومها فقط عندما تُمنح القدرة. في MVC 5، ابنِ الوسوم في المتحكم (العروض لا تحتوي على @inject):

csharp
public class ViewerController : Controller
{
    public ActionResult Index()
    {
        var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
        ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
        {
            IncludeViewerCss     = true,
            IncludeAnnotationCss = true    // jquery-ui.min.css + annotationBar.css
        });
        ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
        {
            IncludeJQuery            = true,
            IncludeViewerScripts     = true,
            IncludeAnnotationScripts = true,  // jquery-ui, raphael.js, annotation.js
            IncludeAnnotationBar     = true   // الشريط المضمن للتعليقات التوضيحية
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

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

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

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

html
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
    var annBar = null;
    var currentToken = '';

    var objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        ResPath:  'doconut-res/images',
        onAnnLoaded:    function () { if (annBar) annBar.handleAnnLoaded(); },
        onAnnSaved:     function () { if (annBar) annBar.handleAnnSaved(); },
        onAnnSaveError: function () { if (annBar) annBar.handleAnnSaveError(); },
        onAnnClosed:    function () { if (annBar) annBar.handleAnnClosed(); },
        onError:        function (message) { console.error('Viewer error:', message); }
    });

    @if ((bool)ViewBag.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: function () { return { token: currentToken }; },
        onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

بدون القدرة، يترك ReferenceScripts سكريبت الشريط، لذا يحافظ if على جانب الخادم من استدعاء doconutAnnotationBar(...) غير محمي من كسر الصفحة. في Web Forms، اكتب الحماية نفسها كـ <% if (IsAnnotationEnabled) { %> … <% } %>.

حفظ البيانات من الشريط يرسل البيانات إلى DocImage.axd (AnnSave)، التي تخزنها في جلسة المستند لكل صفحة. التحميل (AnnLoad) يحدث تلقائيًا عندما تُعرض صفحة تحتوي على تعليقات توضيحية.

افتح وأغلق الشريط من شريط الأدوات الخاص بك باستخدام annBar.open() وannBar.close(). واجهته العامة:

الطريقةالغرض
attach(objViewer)ربط الشريط بالعارض المبدئ؛ مطلوب مرة واحدة
open() / close()بدء أو إنهاء تحرير التعليقات التوضيحية
reset()إرجاع الشريط إلى حالته المغلقة غير التحريرية
isOpen() / annotating()قراءة حالة الشريط / حالة تحرير التعليقات في العارض
reopenEditable()إعادة تحميل تعليقات الصفحة الحالية ككائنات قابلة للتحرير
updateActionState()تحديث أدوات الحفظ والحذف بعد تغييرات المضيف
headerSlot()الفتحة الاختيارية في الرأس للتحكمات المملوكة للمضيف

onStatus، onToast، onLayout، onEditStart، وonEditEnd هي ردود نداء اختيارية من المضيف. يمكن لكائن endpoints أيضًا توفير exportPdf، exportPng، imageUpload، وimageList؛ الأدوات التي لا تملك نقطة نهاية مُكوَّنة تبقى مخفية.

نوعان من الاستدعاءات، موصولة بطريقتين

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

  • 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
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<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));

    // تحميل إلى الجلسة - يقوم العارض بجلبها، ويقوم المُعالج بدمجها في
    // تصديرات image/PDF.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

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

جميع الأنواع موجودة في 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)بيانات تعليقة مشفرة — الظرف الذي يستهلكه الودجت
GetAnnotationXml()نموذج XML

Viewer يعكس عمليات التحميل والقراءة مقابل جلسة: LoadAnnotationData(token, manager) أو LoadAnnotationData(token, encodedData)، LoadAnnotationXML(token, xml)، وGetAnnotationXML(token).

تصدير مع دمج التعليقات التوضيحية

csharp
// PDF لجميع الصفحات مع التعليقات التوضيحية المدمجة عليها
public async Task<ActionResult> ExportPdf(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", "export.pdf");
}

// أو ملف ZIP لملفات PNG لكل صفحة
public async Task<ActionResult> ExportPngZip(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return 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 و unique‑local. هذا يحمي الخادم من أن يُستَخدم للوصول إلى الأنظمة الداخلية عبر عنوان صورة مُصمم، ولا يوجد مفتاح لإيقاف ذلك.

عنوان URL للصورة النسبي يُحلّ مقابل مضيف الطلب الحالي، لذا على localhost، أو على خادم داخل شبكة، أو على أي موقع يُوصل عبر عنوان خاص، تُظهر الصورة في العارض وتحتوي عملية التصدير على عنصر نائب بدلاً من ذلك. هذا هو الحماية تعمل، وليس فشلًا في العرض. إذا كان يجب أن تحتوي الصادرات على الصورة، قدمها من مضيف بعنوان عام واستخدم عنوان URL مطلق. يُرفض اسم المضيف الذي لا يمكن حله بنفس الطريقة؛ أي فشل آخر في التنزيل يُظهر عنوان URL ورسالة الخطأ باللون الأحمر حيث كانت ستظهر الصورة.

سير عمل الاستمرارية

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

لا تستخدم رمز العارض كمعرّف دائم للتعليقات — فهو ينتهي مع الجلسة، وإعادة تدوير مجموعة التطبيقات تنهي كل الجلسات على خادم واحد. احفظ بيانات التعليقات مقابل مستندك ومعرفات الإصدار الخاصة بك.

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

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

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

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

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