Viewer
מחלקת הצופה הראשית למסמכים
Viewer (namespace Doconut) הוא נקודת הכניסה הציבורית לפתיחת מסמכים מדפי Razor, בקרים של MVC, רכיבי Blazor, או API מינימליים. הוא sealed, רשום כשירות transient על ידי AddDoconut(), ונפתר באמצעות הזרקת קונסטרקטור — לעולם אל תבנה אותו ישירות.
Viewer אינו מחזיק במצב per‑request ומתכוון not לממש IDisposable: סשני המסמכים חיים באופן עצמאי במטמון הסשן, ולכן השמדת השירות לעולם לא תסגור מסמך פתוח (ראו מושגים בסיסיים → איך הצופה עובד).
פתיחת מסמך אסינכרוני
פותח מסמך ומחזיר את אסימון הסשן שהווידג'ט של הלקוח משתמש בו לכל הבקשות הבאות.
| גרסה | מתי להשתמש |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | פתיחה מהדיסק עם זיהוי פורמט אוטומטי וקונפיגורציית ברירת המחדל של הפורמט |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | נדרשות אפשרויות רינדור לכל פורמט (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | המסמך אינו קובץ על הדיסק (העלאה, מסד נתונים, blob). fileInfo חייב לשאת את הסיומת הנכונה — היא מניעה את זיהוי הפורמט |
// פתיחה פשוטה
string token = await viewer.OpenDocumentAsync(path);
// עם תצורה ואפשרויות לכל פורמט
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// מתוך העלאה
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));חריגות לטיפול:
LicenseException— רישיון שנמצא נדחה (ההודעה נושאת את סיבת הדחייה), או שהפורמט דורש יכולת תוסף שאינה ניתנת יותר. פקיעת לוח שנה ללא הודעת דחייה מתנהגת כרינדור עם סימן מים במקום לזרוק חריגה.FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— תוכן הקובץ פגום או שאינו תואם לסיומת שלו.
סגירת מסמך
void CloseDocument(string token)מסיר את הסשן מהמטמון (משחרר את מנוע המסמך מיד), מוחק את סמן האבטחה, ומבטל את מתן הגישה. אופציונלי — פקיעת זמן משיכה מבצעת את ניקוי המשאבים זהה — אך מומלץ עבור מסמכים גדולים.
קבלת מספר עמודים
int GetPageCount(string token)סך כל העמודים של הסשן הפתוח. זורק InvalidOperationException (Document session not found. Please re-open document.) אם האסימון אינו ידוע או פג תוקף, ו‑ArgumentException עבור אסימון ריק.
קבלת ממדי עמוד
(int Width, int Height) GetPageDimensions(string token, int page = 1)גודל העמוד המוצג כברירת מחדל של המסמך ב‑100 % זום — מרחב הקואורדינטות לאנוטציות שנבנות בקוד. page מתקבל למטרת תאימות; התוצאה היא ברירת המחדל של המסמך. זורק InvalidOperationException (Document session not found. Please re-open document.) אם האסימון אינו ידוע או פג תוקף, ו‑ArgumentException עבור אסימון ריק.
קבלת שמות גיליונות עבודה
IReadOnlyList<string> GetWorksheetNames(string token)מחזיר את שמות הגיליונות של גליון אלקטרוני פתוח, לפי סדר חוברת העבודה, או רשימה ריקה כאשר המסמך הפתוח אינו גליון אלקטרוני.
רק גליונות שמוצגים נרשמים: גליונות מוסתרים וגליונות ריקים אינם נכללים, וכאשר ExcelConfig.SheetNames מגביל רינדור, רק אותם גליונות מופיעים. גליון אינו תמיד עמוד אחד — גליון גדול מאוד מרונדר על פני מספר עמודים. זורק InvalidOperationException (Document session not found. Please re-open document.) אם האסימון אינו ידוע או פג תוקף, ו‑ArgumentException עבור אסימון ריק.
התווסף ב‑26.9.0.
דגלי יכולת
| חבר | משמעות |
|---|---|
bool IsSearchEnabled | הרישיון הנוכחי מעניק Search |
bool IsAnnotationEnabled | הרישיון הנוכחי מעניק Annotation |
השתמשו באלו בתצוגת Razor כדי להציג Ribbon מורשה רק כאשר השרת יגיש אותו בפועל — ראה התחלה מהירה.
אפשרויות מסמך
אפשרויות לכל פתיחה, בלתי תלויות בפורמט (מרחב שמות Doconut):
| סוג | מאפיין | ברירת מחדל | תיאור |
|---|---|---|---|
string | Password | "" | סיסמה למסמכים מוגנים (מועתקת לתצורת הפורמט אוטומטית). |
int | ImageResolution | 0 | מיושן. נשמר רק לצורך תאימות — במקום זאת הגדר ImageResolution בתצורת הפורמט. |
string | Watermark | "" | טקסט סימן מים מותאם אישית שנצייר על דפים מוצגים. מחרוזת פורמט: "^Text~Color~FontSize~FontName~Opacity~Angle", לדוגמה "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | תפוגת משך מושב מתחלפת בדקות. |
bool | IsSecured | true | לא נאכף כרגע — שמור. קישור אסימון נשלט גלובלית על ידי DoconutOptions.UnsafeMode (ראה מושגים מרכזיים → מושבים ואבטחה). |
המחלקה גם חושפת מאפיינים מיוחדים שנועדו להיות מחוץ לזרימת הצפייה הרגילה של מארח יחיד:
| סוג | מאפיין | ברירת מחדל | תיאור |
|---|---|---|---|
bool | IsWebFarm | false | מיושן — אין לו השפעה. פרסם את המסמך עם DistributedDocumentPublisher.PublishAsync (או IDistributedPublishQueue.EnqueueAsync) והגדר במקום זאת FileShareConfig.RootPath. |
string | WebFarmPath | "" | מיושן — אין לו השפעה. השתמש ב-FileShareConfig.RootPath במקום זאת. |
bool | EditMode | false | שמורה לתהליך העבודה של העורך המופץ בנפרד; השאר את false לצופה הסטנדרטי. |
סימן מים מותאם אישית
DocOptions.Watermark משתמש בשישה שדות מופרדים בטילדה. ^ מוביל אופציונלי מבקש פריסת כל הפינות:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| שדה | דוגמה | משמעות |
|---|---|---|
קידומת ^ | ^ | פריסת כל הפינות אופציונלית. ללא זה, נעשה שימוש במיקום סימן המים הרגיל. |
| טקסט | Confidential | טקסט שמוצג על כל דף. אסור שיהיה ריק. |
| צבע | Red | צבע בשם המובן על ידי שכבת הציור. |
| גודל גופן | 24 | גודל גופן; קלט מספרי לא תקין חוזר לברירת המחדל של הרנדרר. |
| שם גופן | Verdana | משפחת הגופנים המבוקשת. ודא שהיא מותקנת בסביבת הפריסה. |
| שקיפות | 80 | ערך בייט מ-0 עד 255. חייב להיתפרש בהצלחה. |
| זווית | -45 | זווית סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל. |
ה-parser מצפה בדיוק לשישה שדות אחרי ה^ האופציונלי. הגדרה לא תקינה מוחלפת בגיבוי הInvalid Watermark המוצג של ה-SDK במקום להיעלם בשקט.
החלטת רישיון
| מצב רישיון | ערך מותאם סופק | תוצאה מוצגת |
|---|---|---|
| רישיון צופה בתשלום תקף | לא | דף נקי |
| רישיון צופה בתשלום תקף | כן | סימן מים מותאם אישית |
| צופה בסיס זמני/דמו פעיל | לא | דף צופה בסיסי נקי |
| צופה בסיס זמני/דמו פעיל | כן | סימן מים מותאם אישית כאשר נתיב הצופה הבסיסי הנקי חל |
| רישיון חסר, נדחה, פג, גרסה שגויה, או תחום לא תקף | כל אחד | סימן מים של אכיפה/הערכה; הערך המותאם אינו עוקף אותו |
| הצגת תוסף תחת כללי הערכה | כל אחד | סימן מים של הערכה |
ההחלטה זהה מוחלת על תמונות דפים שמסופקות וייצוא ההערות. פלט GIF מונפש מסומן פריים אחרי פריים. לכן סימן מים מותאם אישית הוא תכונה של אפליקציה מורשית, ולא דרך להחליף או לדכא את סימן המים של ההערכה.
API של ההערות
טעינת והפצת ההערות בצד השרת. ההדרכה המלאה נמצאת במדריכים → ההערות; הממשק הוא:
| חבר | מטרה |
|---|---|
AnnotationManager GetAnnotationManager(string token) | מנהל הקשור למימדי העמוד של הסשן הפתוח |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | מנהל עם מימדי עמוד מפורשים |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | מנהל בלתי תלוי בסשן |
void LoadAnnotationData(string token, AnnotationManager manager) | טען הערות שנבנו ב‑C# לתוך הסשן |
void LoadAnnotationData(string token, string annotationData) | טען הערות מהדף המוצפן/מעטפת Base64 שהוחזרה על ידי AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | טען הערות מ‑XML |
XmlDocument GetAnnotationXML(string token) | ייצא את ההערות של הסשן כ‑XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF עם הערות משולבות |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | PNG אחד לכל עמוד, הערות משולבות, נכתב ל‑directoryPath (נוצר אם חסר); מחזיר את מספר התמונות שנכתבו |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | קובץ ZIP של PNGs לכל עמוד עם הערות משולבות |
מטא‑נתוני DICOM
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)מחזיר מטא‑נתוני תגיות DICOM עבור סשנים שנפתחים דרך תוסף DICOM; null עבור מסמכים שאינם DICOM.
עוזרי משאבים — ReferenceCss / ReferenceScripts
הפץ את תגיות <link>/<script> עבור המשאבים המוטמעים שמסופקים על ידי UseDoconutResources(), בסדר תלות נכון. חבילות עבור תכונות המוגבלות ברישיון כגון חיפוש והערות נשלחות רק כאשר הרישיון מאפשר זאת, כדי לשמור על ממשק המשתמש של הלקוח תואם להתנהגות השרת.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + מציג + חיפוש + הסבר
string ReferenceScripts(ScriptConfig? config = null)דגלי CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (מוגבל חיפוש), IncludeAnnotationCss (מוגבל הערות).
דגלי ScriptConfig: IncludeJQuery (נדרש על ידי כולם), IncludeBootstrap, IncludeViewerScripts (ליבת: docViewer.js + מפצל + קישורים), IncludeSearchScripts ו-IncludeSearchBar (מוגבל חיפוש), IncludeAnnotationScripts ו-IncludeAnnotationBar (מוגבל הערות), EmitFeatureFlags (ברירת מחדל true: גם כותב סקריפט inline של window.Doconut.features = { search, annotation, editor }; הגדר אותו ל-false תחת Content‑Security‑Policy שחוסמת סקריפטים inline).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))האם דף זה היה מועיל?