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