הערות
הוספת תמיכת הערות לצופה
ההערות ב‑Doconut פועלות בשני כיוונים: משתמשים מציירים אותן בווידג'ט של הדפדפן והשרת שומר אותן לכל עמוד, או שהקוד שלך בונה אותן וטוען אותן למפגש פתוח. בכל מקרה הן מוצגות בעמודים וניתן לשלב אותן בייצוא של PDF או PNG.
תמיכת ההערות מוגבלת על ידי יכולת הרישיון Annotation (ניתנת אוטומטית תחת רישיון Temporary פעיל).
הפעלת ממשק המשתמש של ההערות
הערה היא מודול של Viewer, ולא סרגל כלים עצמאי. העמוד חייב לכלול את משאבי ה‑Viewer, סרגל הכלים של ה‑Viewer, את הרכיב המותקן של ה‑Viewer, ו‑objViewer מאותחל; לאחר מכן רצועת ההערות מותקנת ומחוברת לאותו מופע.
הפץ את קבצי ההערות יחד עם קבצי ה‑viewer. הם מוגבלים ברישיון, ולכן התגים שלהם מופיעים רק כאשר היכולת ניתנת. ב‑MVC 5, בנה את התגים בבקר (ל‑views אין @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 בסימון ה‑markup:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- בקרות הצופה, כולל הכפתור הפותח את Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>קבצי ההערות מייצרים את הרצועה בתוך annBarMount; אינך מעתיק את הכפתורים או הדיאלוגים שלה. אתחל את docViewer תחילה, ולאחר מכן צור את הרצועה רק כאשר השרת מאשר שההערה מורשית:
@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 משאיר את הסקריפט של הרצועה, ולכן if בצד השרת מונע קריאה בלתי מוגנת של doconutAnnotationBar(...) משבשת את העמוד. ב‑Web Forms, כתוב את אותו מגן כ‑<% if (IsAnnotationEnabled) { %> … <% } %>.
שמירה מהרצועה מפרסמת את הנתונים ל‑DocImage.axd (AnnSave), אשר שומרת אותם במפגש המסמך לכל עמוד. טעינה (AnnLoad) מתרחשת אוטומטית כאשר עמוד עם הערות מוצג.
פתח וסגור את הרצועה מסרגל הכלים שלך באמצעות annBar.open() ו‑annBar.close(). ה‑API הציבורי שלו:
| שיטה | מטרה |
|---|---|
attach(objViewer) | חיבור הרצועה לצופה המאותחל; נדרש פעם אחת |
open() / close() | כניסה או יציאה ממצב עריכת ההערות |
reset() | החזרת הרצועה למצב סגור, ללא עריכה |
isOpen() / annotating() | קריאת מצב הרצועה / מצב עריכת ההערות של הצופה |
reopenEditable() | טעינת ההערות של העמוד הנוכחי כאובייקטים ניתנים לעריכה |
updateActionState() | ריענון פקדי השמירה והמחיקה לאחר שינויי המארח |
headerSlot() | משבצת הכותרת האופציונלית לבקרות שבבעלות המארח |
onStatus, onToast, onLayout, onEditStart, ו‑onEditEnd הם קריאות חוזרות (callbacks) אופציונליות של המארח. האובייקט 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 יחסית נפתרת ביחס למארח הבקשה הנוכחית כאשר ההערה מתווספת — ראה את ההערה לייצוא למטה |
ממשק AnnotationManager API
| Member | Purpose |
|---|---|
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 של PNGs לכל עמוד
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");
}הייצוא משתמש באותו מנשר כמו רינדור על המסך, ובאותה רישיון והחלטת סימן מים מותאם אישית.
חיבורים של תמונות במארח אינטרנט פנימי מייצאים כ-"תמונה חסומה"
הצופה והייצוא משיגים את תמונת הImageAnnotation ממקומות שונים:
| מַשטָח | מי מוריד את התמונה | במארח אינטרנט פנימי או פיתוח |
|---|---|---|
| הצופה בדפדפן | דפדפן המשתמש | התמונה מופיעה |
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# אינם מופיעים | מספרי העמודים מתחילים מ‑1, והנתונים נטענו לתוך האסימון הפעיל |
| חיבור תמונה מוצג על המסך אך לא בייצוא | למארח התמונה יש כתובת פרטית או לופבק — ראה למעלה |
| מסמך שנפתח מחדש אינו מכיל חיבורים | שמור XML או נתונים מחוץ להפעלת הצופה, ואז טען אותם לתוך האסימון החדש |
האם דף זה היה מועיל?