حاشیه‌نویسی‌ها

افزودن پشتیبانی از حاشیه‌نویسی به Viewer

حاشیه‌نویسی‌ها در Doconut در دو جهت کار می‌کنند: کاربران آن‌ها را در ویجت مرورگر می‌کشند و سرور آن‌ها را به ازای هر صفحه ذخیره می‌کند، یا کد شما به‌صورت برنامه‌نویسی آن‌ها را می‌سازد و در یک جلسه باز بارگذاری می‌کند. به هر حال، آن‌ها در صفحات رندر می‌شوند و می‌توانند در خروجی‌های PDF/PNG تعبیه شوند.

پشتیبانی از حاشیه‌نویسی توسط قابلیت مجوز Annotation محدود شده است (به‌صورت خودکار تحت یک مجوز موقت فعال اعطا می‌شود).

فعال‌سازی رابط کاربری حاشیه‌نویسی

حاشیه‌نویسی یک ماژول Viewer است، نه یک نوار ابزار مستقل. صفحه کامل باید شامل منابع Viewer، نوار ابزار Viewer، نصب Viewer و objViewer مقداردهی اولیه شده باشد؛ سپس نوار Ribbon حاشیه‌نویسی نصب و به همان نمونه متصل می‌شود.

بسته‌های حاشیه‌نویسی را همراه با بسته‌های Viewer صادر کنید — آن‌ها تحت مجوز هستند، بنابراین برچسب‌ها فقط زمانی ظاهر می‌شوند که قابلیت موجود باشد:

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  // نوار حاشیه‌نویسی تعبیه‌شده
}))

ترکیب کامل Viewer را در نشانه‌گذاری (markup) قابل مشاهده نگه دارید:

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>

بسته حاشیه‌نویسی DOM نوار Ribbon را داخل annBarMount تولید می‌کند؛ نیازی به کپی کردن دکمه‌ها یا نشانه‌گذاری دیالوگ آن ندارید. ابتدا docViewer را مقداردهی اولیه کنید، سپس نوار Ribbon را فقط زمانی ایجاد کنید که سرور تأیید کند حاشیه‌نویسی مجوز دارد:

html
<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 همگام نگه می‌دارند.

از هر نوار ابزار Viewer متعلق به میزبان آن را باز و بسته کنید:

javascript
annBar.open();
annBar.close();

API عمومی نوار Ribbon به شرح زیر است:

متدهدف
attach(objViewer)نوار Ribbon را به Viewer مقداردهی اولیه شده متصل می‌کند؛ یک بار لازم است
open() / close()ورود یا خروج از حالت ویرایش حاشیه‌نویسی
reset()نوار Ribbon را به حالت بسته و غیر ویرایشی باز می‌گرداند
isOpen() / annotating()وضعیت نوار Ribbon / وضعیت ویرایش حاشیه‌نویسی Viewer را بخوانید
reopenEditable()حاشیه‌نویسی‌های صفحه فعلی را به‌عنوان اشیای قابل ویرایش بازخوانی کنید
updateActionState()دسترسی کنترل‌های ذخیره/حذف را پس از تغییرات میزبان تازه‌سازی کنید
headerSlot()اسلات افزونه سرصفحه اختیاری برای کنترل‌های متعلق به میزبان را دریافت کنید

onStatus، onToast، onLayout، onEditStart و onEditEnd فراخوانی‌های اختیاری میزبان هستند. شیء endpoints می‌تواند علاوه بر این exportPdf، exportPng، imageUpload و imageList را فراهم کند؛ کنترل‌هایی که نقطه انتهایی پیکربندی نشده دارند مخفی می‌مانند.

برای توالی راه‌اندازی ترکیبی Viewer، Search و Annotation، به شروع سریع مراجعه کنید.

بسته حاشیه‌نویسی ابزارهای نویسندگی مرورگر را اضافه می‌کند، اما داده‌ها همچنان به جلسه سند سمت سرور که با توکن شناسایی می‌شود تعلق دارند. باز کردن مجدد منبع یک جلسه جدید ایجاد می‌کند؛ اگر حاشیه‌نویسی‌ها باید پس از پایان عمر جلسه حفظ شوند، XML یا پاکت حاشیه‌نویسی رمزگذاری‌شده را در برنامه خود نگهداری کنید.

دو نوع فراخوانی، به دو روش وصل شده

کد حاشیه‌نویسی از دو سبک فراخوانی استفاده می‌کند، و هر کدام هنگام وصل شدن به روش دیگر به‌صورت ساکت شکست می‌خورند:

  • onAnnLoaded، onAnnSaved، onAnnSaveError، onAnnClosed گزینه‌های docViewer({...}) هستند، مانند هر فراخوانی viewer.
  • Created، Changed، Deleted، و Properties توابع سراسری یافت‌شده بر اساس نام هستند: شناسهٔ viewer به‌عنوان پیشوند به رویداد اضافه می‌شود. برای viewer در #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 دریافت می‌کند و
    // renderer آن‌ها را در خروجی‌های تصویر/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 نسبی نسبت به میزبان درخواست هنگام افزودن حاشیه‌نویسی حل می‌شود؛ سرور تصویر را فقط در زمان سوزاندن دریافت می‌کند — نکتهٔ صادرات زیر را ببینید

API مدیر حاشیه‌نویسی

عضوهدف
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");
});

حاشیه‌نویسی‌های تصویر در یک میزبان اینترانت هنگام خروجی به عنوان «تصویر مسدود شد»

نمایشگر و خروجی تصویر یک 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)، و آدرس‌های link‑local و unique‑local IPv6. این کار سرور را از استفاده برای دسترسی به سیستم‌های داخلی از طریق یک URL تصویر دست‌ساخته محافظت می‌کند و هیچ تنظیمی برای غیرفعال‌سازی آن وجود ندارد.

یک 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/داده‌ها را خارج از جلسه نمایشگر ذخیره کنید، سپس آن را در توکن جدید بارگذاری کنید

آیا این صفحه مفید بود؟