حاشیهنویسیها
پشتیبانی از حاشیهنویسی را به نمایشگر اضافه کنید
حاشیهنویسیها در Doconut به دو جهت کار میکنند: کاربران آنها را در ویجت مرورگر میکشند و سرور برای هر صفحه نگه میدارد، یا کد شما آنها را میسازد و در یک نشست باز بارگذاری میکند. به هر حال، این حاشیهنویسیها روی صفحات رندر میشوند و میتوانند در خروجیهای PDF یا PNG سوزانده شوند.
پشتیبانی از حاشیهنویسی توسط قابلیت مجوز Annotation محدود شده است (بهصورت خودکار تحت یک مجوز موقت فعال اعطا میشود).
فعالسازی رابط کاربری حاشیهنویسی
حاشیهنویسی یک ماژول Viewer است، نه یک نوار ابزار مستقل. صفحه باید منابع Viewer، نوار ابزار Viewer، سوار کننده Viewer و یک objViewer مقداردهی اولیهشده را شامل شود؛ سپس نوار Ribbon حاشیهنویسی سوار و به همان نمونه متصل میشود.
فایلهای حاشیهنویسی را همراه با فایلهای Viewer صادر کنید. این فایلها تحت مجوز هستند، بنابراین برچسبهای آنها فقط زمانی ظاهر میشوند که قابلیت مجوز داده شده باشد. در MVC 5، برچسبها را در کنترلر بسازید (نمایها هیچ @inject ندارند):
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 را در مارکآپ نگه دارید:
<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.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 عمومی آن:
| Method | Purpose |
|---|---|
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):
// 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).
خروجی با حاشیهنویسیهای سوزاندهشده
// 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 و پیام خطا را به رنگ قرمز در جایی که تصویر باید باشد، نمایش میدهد.
جریان کار نگهداری
- سند را باز کنید و توکن آن را دریافت کنید.
- XML یا دادههای رمزگذاریشدهٔ ذخیرهشدهٔ قبلی را در آن توکن بارگذاری کنید.
- اجازه دهید ویجت حاشیهنویسیهای جلسه را بخواند و ویرایش کند.
- XML را با
GetAnnotationXML(token)دریافت کنید وقتی برنامهٔ شما تصمیم به حفظ میگیرد. - PDF یا PNG را خروجی بگیرید وقتی یک تحویل مسطح مورد نیاز است.
- جلسهٔ سند را ببندید.
از توکن نمایشگر به عنوان شناسهٔ دائمی حاشیهنویسی استفاده نکنید — این توکن با پایان جلسه از بین میرود و بازیابی استخر برنامه تمام جلسات را بر روی یک سرور خاتمه میدهد. دادههای حاشیهنویسی را نسبت به سند و شناسههای نسخهٔ خود ذخیره کنید.
نکات امنیتی و رندرینگ
- درخواستهای حاشیهنویسی از همان امنیت جلسه و توکن همانند درخواستهای صفحه استفاده میکنند.
- هر URL تصویری که توسط کاربر ارائه میشود را اعتبارسنجی و کنترل کنید.
- بارهای آزاد بزرگ و خروجیهای با وضوح بالا مصرف حافظه را افزایش میدهند؛ اسناد واقعی و مقادیر زوم را آزمایش کنید.
عیبیابی
| علامت | بررسی |
|---|---|
| نوار حاشیهنویسی موجود نیست | قابلیت Annotation و چهار پرچم CSS/اسکریپت حاشیهنویسی |
| ذخیرهسازی خطا گزارش میدهد | انقضای توکن یا جلسه، و BasePath ویجت |
ctlDoc_Created (یا تابع رویداد دیگر) هرگز اجرا نمیشود | نام تابع: شناسهٔ نمایشگر + _ + رویداد، به عنوان یک تابع سراسری |
| حاشیهنویسیهای C# ظاهر نمیشوند | شمارههای صفحه از یک شروع میشوند و دادهها در توکن فعال بارگذاری شدهاند |
| یک حاشیهنویسی تصویر روی صفحه نمایش داده میشود اما در خروجی نیست | میزبان تصویر دارای آدرس خصوصی یا loopback است — به بالا مراجعه کنید |
| سندی که دوباره باز شده حاشیهنویسی ندارد | XML یا دادهها را خارج از جلسه نمایشگر حفظ کنید، سپس آن را در توکن جدید بارگذاری کنید |
آیا این صفحه مفید بود؟