הסברים
הוסף תמיכת הערות לצופה
הסברים ב‑Doconut פועלים בשני כיוונים: משתמשים מציירים אותם בווידג'ט של הדפדפן והשרת שומר אותם לכל עמוד, או שהקוד שלך בונה אותם תכנותית וטוען אותם למפגש פתוח. בכל מקרה הם מוצגים בעמודים וניתן לשלבם בייצוא PDF/PNG.
תמיכת ההסבר מוגבלת על ידי היכולת ברישיון Annotation (ניתנת אוטומטית תחת רישיון זמני פעיל).
הפעלת ממשק המשתמש של ההסבר
הסבר הוא מודול של Viewer, ולא סרגל כלים עצמאי. על העמוד המלא לכלול את משאבי ה‑Viewer, סרגל הכלים של Viewer, הרכבה של Viewer, ו‑objViewer שהותחל; לאחר מכן רצועת ההסבר מותקנת ומצורפת לאותו מופע.
הפץ את חבילות ההסבר יחד עם חבילות ה‑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 המלאה גלויה בתגיות:
<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: '/',
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.
פתח וסגור אותה מכל סרגל כלים של Viewer שבבעלות המארח:
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; בקרות ללא נקודת קצה מוגדרת נשארות מוסתרות.
עבור רצף האתחול המשולב של Viewer, Search והסבר, ראו התחלה מהירה.
חבילת ההסבר מוסיפה את כלי העריכה בדפדפן, אך הנתונים עדיין שייכים למפגש המסמך בצד השרת שמזוהה על ידי הטוקן. פתיחה מחדש של המקור יוצרת מפגש חדש; שמור את ה‑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 שורף אותם לתוך ייצואי 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. כתובת יחסית נפתרת ביחס למארח הבקשה כאשר מוסיפים את ההערה; השרת מושך את התמונה רק בזמן השריפה — ראה את ההערה לייצוא למטה |
ממשק ה‑AnnotationManager 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 של 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# אינן מופיעות | מספור העמודים מתחיל מ‑1 והנתונים נטענו לתוך האסימון הפעיל |
| הערת תמונה מופיעה על המסך אך לא בייצוא | למארח התמונה יש כתובת פרטית או לופבק — ראה למעלה |
| מסמך שנפתח מחדש אין בו הערות | שמור XML/נתונים מחוץ לסשן הצופה, ואז טען אותם לתוך האסימון החדש |
האם דף זה היה מועיל?