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

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

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

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

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

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

فایل‌های حاشیه‌نویسی را همراه با فایل‌های Viewer صادر کنید. این فایل‌ها تحت مجوز هستند، بنابراین برچسب‌های آن‌ها فقط زمانی ظاهر می‌شوند که قابلیت مجوز داده شده باشد. در 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();
    }
}

ترکیب کامل Viewer را در مارک‌آپ نگه دارید:

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
@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 اسکریپت نوار Ribbon را حذف می‌کند، بنابراین if سمت سرور یک فراخوانی نا‌محافظت‌شده doconutAnnotationBar(...) را از خراب شدن صفحه جلوگیری می‌کند. در Web Forms، همان محافظ را به‌صورت <% if (IsAnnotationEnabled) { %> … <% } %> بنویسید.

ذخیره‌سازی از نوار Ribbon داده‌ها را به DocImage.axd (AnnSave) ارسال می‌کند، که آن‌ها را در نشست سند برای هر صفحه ذخیره می‌کند. بارگذاری (AnnLoad) به‌صورت خودکار زمانی رخ می‌دهد که صفحه‌ای با حاشیه‌نویسی‌ها رندر شود.

نوار Ribbon را از نوار ابزار خود با annBar.open() و annBar.close() باز و بسته کنید. API عمومی آن:

MethodPurpose
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 نسبی نسبت به میزبان درخواست فعلی هنگام افزودن حاشیه‌نویسی حل می‌شود — نکتهٔ خروجی در زیر را ببینید

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

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

خروجی‌ها از همان سوزاننده‌ای که برای رندر روی‑صفحه استفاده می‌شود، و همان تصمیم‌گیری دربارهٔ مجوز و واترمارک سفارشی استفاده می‌کنند.

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

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