הערות
הוספת תמיכת הערות לצופה
הערות ב‑Doconut פועלות בשני כיוונים: משתמשים מציירים אותן בווידג'ט הדפדפן והשרת שומר אותן לכל עמוד, או שהקוד שלכם בונה אותן תכנותית וטוען אותן למפגש פתוח. בכל מקרה הן מוצגות בעמודים וניתן לשלבן בייצוא PDF/PNG.
תמיכת ההערות מוגבלת על‑ידי יכולת הרישיון Annotation (ניתנת אוטומטית תחת רישיון Temporary פעיל).
הפעלת ממשק המשתמש של ההערות
הערה היא מודול של Viewer, ולא סרגל כלים עצמאי. העמוד המלא חייב לכלול את משאבי ה‑Viewer, סרגל הכלים של Viewer, הרכבה של Viewer, וה‑objViewer שהותחל; לאחר מכן רצועת ההערות (Annotation Ribbon) מותקנת ומחוברת לאותו מופע.
הפיצו את חבילות ההערות יחד עם חבילות הצופה — הן מוגבלות ברישיון, ולכן התגים מופיעים רק כאשר היכולת זמינה:
@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 המלאה גלויה במרקאפ:
<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 של הרצועה בתוך annBarMount; אין צורך להעתיק את הכפתורים או את מרקאפ הדיאלוג שלה. אתחלו את docViewer תחילה, ואז צרו את הרצועה רק כאשר השרת מאשר שההערה מורשית:
<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 משמיט את הסקריפט של הרצועה, ולכן ה‑if בצד השרת משאיר קריאה בלתי מוגנת של doconutAnnotationBar(...) מפני שבור את העמוד.
שמירה מהרצועה מפרסמת נתונים דרך המידלוור (AnnSave), אשר שומר אותם במפגש המסמך לכל עמוד. טעינה (AnnLoad) מתבצעת אוטומטית כאשר עמוד עם הערות מוצג. ארבעת הקריאות חזרה onAnn* משמרות את סנכרון הרצועה עם מחזור החיים של הצופה.
פתחו וסגרו אותה מכל סרגל כלים של Viewer שבבעלות המארח:
annBar.open();
annBar.close();API הציבורי של הרצועה הוא:
| מתודה | מטרה |
|---|---|
attach(objViewer) | מחבר את הרצועה לצופה שהותחל; נדרש פעם אחת |
open() / close() | כניסה או יציאה ממצב עריכת הערות |
reset() | מחזיר את הרצועה למצב סגור, ללא עריכה |
isOpen() / annotating() | קרא את מצב הרצועה / מצב עריכת ההערות של הצופה |
reopenEditable() | טען מחדש את ההערות של העמוד הנוכחי כאובייקטים ניתנים לעריכה |
updateActionState() | רענן את זמינות בקרות השמירה/מחיקה לאחר שינויי המארח |
headerSlot() | קבל את משבצת ההרחבה האופציונלית בכותרת לבקרות שבבעלות המארח |
onStatus, onToast, onLayout, onEditStart ו‑onEditEnd הם קריאות חזרה אופציונליות של המארח. האובייקט endpoints יכול בנוסף לספק את exportPdf, exportPng, imageUpload ו‑imageList; בקרות ללא נקודת קצה מוגדרת נשארות מוסתרות.
עבור רצף האתחול המשולב של Viewer, Search והערות, ראו התחלה מהירה.
חבילת ההערות מוסיפה את כלי הכתיבה בדפדפן, אך הנתונים עדיין שייכים למפגש המסמך בצד השרת שמזוהה על‑ידי האסימון. פתיחה מחדש של המקור יוצרת מפגש חדש; שמרו את ה‑XML או את מעטפת ההערות המקודדת באפליקציה שלכם אם יש צורך שההערות ישרדו מעבר לחיי המפגש.
שני סוגי callback, מחוברים בשתי דרכים
קוד ההערות משתמש בשני סגנונות של callback, וכל אחד נכשל בשקט כאשר מחובר בצורה ההפוכה:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedהן אפשרויות שלdocViewer({...}), כמו כל callback של הצופה.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 וה
// המנוע משלב אותם ביצואי תמונה/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 יחסי נפתר יחסית למארח הבקשה כאשר ההערה מתווספת; השרת מושך את התמונה רק בזמן השריפה — ראה את ההערה על הייצוא למטה |
API של AnnotationManager
| חבר | מטרה |
|---|---|
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 של PNGs לכל עמוד
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 ממקומות שונים:
| מישור | מי מוריד את התמונה | במארח אינטרנט או פיתוח |
|---|---|---|
| הצופה בדפדפן | דפדפן המשתמש | התמונה מופיעה |
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/נתונים מחוץ לסשן הצופה, ואז טען אותם לאסימון החדש |
האם דף זה היה מועיל?