הערות
הוסף תמיכת הערות לצופה
הערות ב‑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">
<!-- בקרות הצופה, כולל הכפתור שפותח 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 וה
// המעבד משלב אותם ביצואי image/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");
});ייצוא משתמש באותו מנשר כמו רינדור על המסך, ולכן מה שהמשתמשים רואים הוא מה שהקובץ מכיל — למעט הערות תמונה, המתוארות להלן.
הערות תמונה במארח אינטרנט מייצאות כ-"Image blocked"
הצופה והייצוא מקבלים את תמונת הImageAnnotation ממקומות שונים:
| משטח | מי מוריד את התמונה | במארח אינטרנט או פיתוח |
|---|---|---|
| הצופה בדפדפן | הדפדפן של המשתמש | התמונה מופיעה |
ExportAnnotationsToPdfAsync / …PngZipAsync | השרת | מציין מקום אדום "Image blocked" |
כאשר השרת מושך תמונה כדי לשלב אותה, הוא דוחה כתובות שמצביעות חזרה לרשתות פרטיות: לולאה (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/נתונים מחוץ לסשן הצופה, ואז טען אותם לתוך האסימון החדש |
האם דף זה היה מועיל?