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

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

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

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، به Quick Start مراجعه کنید.

بسته حاشیه‌نویسی ابزارهای نویسندگی مرورگر را اضافه می‌کند، اما داده‌ها همچنان متعلق به نشست سند سمت سرور هستند که با توکن شناسایی می‌شود. بازگشایی منبع یک نشست جدید ایجاد می‌کند؛ اگر حاشیه‌نویسی‌ها باید پس از پایان عمر نشست باقی بمانند، 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 دریافت می‌کند و
    // 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 relative نسبت به میزبان درخواست هنگام افزودن حاشیه‌نویسی حل می‌شود؛ سرور تصویر را فقط در زمان سوزاندن دریافت می‌کند — نکتهٔ خروجی زیر را ببینید

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's تصویر را از مکان‌های متفاوت دریافت می‌کنند:

سطحچه کسی تصویر را دانلود می‌کنددر یک میزبان اینترانت یا توسعه
نمایشگر در مرورگرمرورگر کاربرتصویر ظاهر می‌شود
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 تصویر دست‌ساز محافظت می‌کند و هیچ تنظیمی برای غیرفعال‌سازی آن وجود ندارد.

یک URL تصویر نسبی نسبت به میزبان درخواست فعلی حل می‌شود، بنابراین در localhost، در یک سرور اینترانت، یا در هر سایتی که از طریق یک آدرس خصوصی دسترسی داشته باشد، تصویر در نمایشگر نشان داده می‌شود و خروجی به‌جای آن جایگزین را شامل می‌شود. این رفتار حفاظتی است، نه یک خطای رندرینگ. اگر خروجی‌ها باید تصویر را شامل شوند، آن را از یک میزبان با آدرس عمومی سرو کنید و از یک URL مطلق استفاده کنید. یک نام میزبان که قابل حل نیست به همان روش رد می‌شود؛ هر گونه شکست دیگر در دانلود، URL و پیام خطا را به‌صورت قرمز در جایی که تصویر قرار می‌گیرد، نمایش می‌دهد.

جریان کار حفظ‌سازی

  1. سند را باز کنید و توکن آن را دریافت کنید.
  2. XML یا داده‌های رمزگذاری‌شدهٔ قبلاً ذخیره‌شده را به آن توکن بارگذاری کنید.
  3. اجازه دهید ویجت حاشیه‌نویسی‌های جلسه را بخواند و ویرایش کند.
  4. XML را با GetAnnotationXML(token) دریافت کنید زمانی که برنامهٔ شما تصمیم به حفظ می‌گیرد.
  5. PDF/PNG را خروجی بگیرید وقتی یک تحویل صاف‌شده لازم است.
  6. جلسهٔ سند را ببندید.

از توکن نمایشگر مبهم به‌عنوان شناسهٔ دائمی حاشیه‌نویسی استفاده نکنید. داده‌های حاشیه‌نویسی حفظ‌شده را با شناسه‌های سند و نسخهٔ خودتان مرتبط کنید.

نکات امنیتی و رندرینگ

  • درخواست‌های حاشیه‌نویسی از همان امنیت جلسه/توکن همانند درخواست‌های صفحه استفاده می‌کنند.
  • هر URL تصویری که توسط کاربر ارائه می‌شود را اعتبارسنجی و کنترل کنید تا از جعل درخواست سمت سرور جلوگیری شود.
  • خروجی‌ها همان تصمیم مجوز/آب‌نشان سفارشی را که در رندر صفحه روی صفحه نمایش اعمال می‌شود، به کار می‌برند.
  • بارهای بزرگ دست‌نویس و خروجی‌های با وضوح بالا مصرف حافظه را افزایش می‌دهند؛ اسناد واقعی و مقادیر زوم را تست کنید.

عیب‌یابی

علائمبررسی
نوار حاشیه‌نویسی موجود نیستAnnotation قابلیت و چهار پرچم CSS/اسکریپت حاشیه‌نویسی
بازگشت‌خوان ذخیره‌سازی خطا گزارش می‌دهدانقضای توکن/جلسه و میان‌افزار BasePath
ctlDoc_Created (یا تابع رویداد دیگر) هرگز اجرا نمی‌شودنام تابع: شناسهٔ نمایشگر + _ + رویداد، به‌عنوان تابع سراسری
حاشیه‌نویسی‌های C# ظاهر نمی‌شوندشماره‌گذاری صفحات از یک شروع می‌شود و داده‌ها به توکن فعال بارگذاری شده‌اند
حاشیه‌نویسی تصویر روی صفحه نمایش می‌شود اما در خروجی نیستمیزبان تصویر دارای آدرس خصوصی یا لوپ‌بک است — به بالا مراجعه کنید
سند بازگشایی شده حاشیه‌نویسی نداردXML/داده‌ها را خارج از جلسه نمایشگر حفظ کنید، سپس آن را به توکن جدید بارگذاری کنید

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