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

پشتیبانی از حاشیه‌نویسی را به نمایشگر اضافه کنید

حاشیه‌نویسی‌ها در 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: '/',
        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 عبارت است از:

MethodPurpose
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({...})، مانند هر فراخوانی نمایشگر.
  • 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 دریافت می‌کند و
    // رندر کننده آن‌ها را در خروجی‌های 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 نسبی نسبت به میزبان درخواست هنگام افزودن حاشیه‌نویسی حل می‌شود؛ سرور تصویر را فقط در زمان سوزاندن دریافت می‌کند — نکتهٔ خروجی زیر را ببینید

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

خروجی‌ها از همان سوزاننده‌ای که برای رندر روی‑صفحه استفاده می‌شود بهره می‌برند، بنابراین آنچه کاربران می‌بینند همان چیزی است که فایل شامل آن است — به‌جز حاشیه‌نویسی‌های تصویری که در ادامه توضیح داده می‌شوند.

حاشیه‌نویسی‌های تصویر در یک میزبان اینترانت که به‌عنوان "Image blocked" صادر می‌شود

نمایشگر و خروجی تصویر یک ImageAnnotation را از مکان‌های متفاوت دریافت می‌کنند:

سطحچه کسی تصویر را دانلود می‌کنددر یک میزبان اینترانت یا توسعه
نمایشگر در مرورگرمرورگر کاربرتصویر ظاهر می‌شود
ExportAnnotationsToPdfAsync / …PngZipAsyncسروریک جایگزین قرمز "Image blocked"

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

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