מציג – Doconut תיעוד

Viewer (namespace Doconut) הוא נקודת הכניסה הציבורית לפתיחת מסמכים מדפי Razor, בקרים של MVC, רכיבי Blazor, או API מינימליים. הוא sealed, רשום כשירות transient על ידי AddDoconut(), ונפתר דרך הזרקת קונסטרקטור — לעולם אל תיצור אותו ישירות.

Viewer אינו מחזיק במצב per-request ומתכוון לא לממש IDisposable: סשני המסמכים חיים באופן עצמאי במטמון הסשן, ולכן השמדת השירות לעולם לא תגרום לסגירת מסמך פתוח (ראה Core Concepts → How the Viewer Works).

OpenDocumentAsync

פותח מסמך ומחזיר את אסימון הסשן שהווידג'ט של הלקוח משתמש בו לכל הבקשות הבאות.

גרסה	מתי להשתמש
`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` חייב לשאת את ההרחבה הנכונה — היא מניעה את זיהוי הפורמט

csharp

// פתיחה פשוטה
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 — תוכן הקובץ פגום או אינו תואם להרחבה שלו.

CloseDocument

text

void CloseDocument(string token)

מסיר את הסשן מהמטמון (משמיד את מנוע המסמך מיידית), מוחק את סימן האבטחה, ומבטל את ההרשאה לגישה. אופציונלי — פקיעת החלקה מבצעת את ניקוי האותו — אך מומלץ למסמכים גדולים.

GetPageCount

text

int GetPageCount(string token)

סך כל העמודים של הסשן הפתוח. זורק חריגה אם האסימון אינו מוכר או פג תוקף.

DocOptions

אפשרויות בלתי תלויות בפורמט לכל פתיחה (namespace 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` (ראה Core Concepts → Sessions & Security).

המחלקה גם חושפת מאפיינים מיוחדים שנמצאים במכוון מחוץ לזרימת הצפייה הרגילה של מארח יחיד:

סוג	מאפיין	ברירת מחדל	תיאור
`bool`	`IsWebFarm`	`false`	מסמן את פעולת הפתיחה כתרחיש של חוות אינטרנט. השתמש רק עם ארכיטקטורת אחסון/סשן משותפת תואמת.
`string`	`WebFarmPath`	`""`	נתיב משותף המשמש בתהליך העבודה של חוות אינטרנט מיוחדת. ריק במציג הרגיל של מארח יחיד.
`bool`	`EditMode`	`false`	שמורה לתהליך העבודה של העורך המופץ בנפרד; השאר `false` למציג הסטנדרטי.

סימן מים מותאם

DocOptions.Watermark משתמש בשישה שדות מופרדים בטילדה. קידומת אופציונלית ^ מבקשת פריסת כל הפינות:

text

^Text~Color~FontSize~FontName~Opacity~Angle

csharp

string 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`	זווית סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל.

המפרש מצפה בדיוק לשישה שדות אחרי ^ האופציונלי. הגדרה לא תקינה מוחלפת ב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(…)`	קבצי PNG עם הערות משולבות
`Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)`	ZIP של PNGs לכל עמוד עם הערות משולבות

מטא‑נתוני DICOM

text

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

מחזיר מטא‑נתוני תג DICOM עבור סשנים שנפתחו דרך תוסף DICOM; null עבור מסמכים שאינם DICOM.

עוזרי משאבים — ReferenceCss / ReferenceScripts

הפץ את תגי <link>/<script> עבור המשאבים המוטמעים שמסופקים על ידי UseDoconutResources(), בסדר תלות נכון. חבילות לתכונות המוגבלות ברישיון כגון חיפוש והערות נשלחות רק כאשר הרישיון מאפשר אותן, תוך שמירה על ממשק הלקוח תואם להתנהגות השרת.

text

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

דגלי CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (מוגבל לחיפוש), IncludeAnnotationCss (מוגבל להערות).

דגלי ScriptConfig: IncludeJQuery (נדרש על ידי כולם), IncludeBootstrap, IncludeViewerScripts (ליבה: docViewer.js + מפצל + קישורים), IncludeSearchScripts ו‑IncludeSearchBar (מוגבל לחיפוש), IncludeAnnotationScripts ו‑IncludeAnnotationBar (מוגבל להערות).

html

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

GetWorksheetNames

text

IReadOnlyList<string> GetWorksheetNames(string token)

מחזיר את שמות הגליונות של גליון אלקטרוני פתוח, לפי סדר חוברת העבודה, או רשימה ריקה כאשר המסמך הפתוח אינו גליון אלקטרוני.

התווסף ב‑26.9.0.