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

סגירת מסמך

text
void CloseDocument(string token)

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

קבלת מספר עמודים

text
int GetPageCount(string token)

סך כל העמודים של הסשן הפתוח. זורק InvalidOperationException (Document session not found. Please re-open document.) אם האסימון אינו ידוע או פג תוקף, ו‑ArgumentException עבור אסימון ריק.

קבלת ממדי עמוד

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

גודל העמוד המוצג כברירת מחדל של המסמך ב‑100 % זום — מרחב הקואורדינטות לאנוטציות שנבנות בקוד. page מתקבל למטרת תאימות; התוצאה היא ברירת המחדל של המסמך. זורק InvalidOperationException (Document session not found. Please re-open document.) אם האסימון אינו ידוע או פג תוקף, ו‑ArgumentException עבור אסימון ריק.

קבלת שמות גיליונות עבודה

text
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):

סוגמאפייןברירת מחדלתיאור
stringPassword""סיסמה למסמכים מוגנים (מועתקת לתצורת הפורמט אוטומטית).
intImageResolution0מיושן. נשמר רק לצורך תאימות — במקום זאת הגדר ImageResolution בתצורת הפורמט.
stringWatermark""טקסט סימן מים מותאם אישית שנצייר על דפים מוצגים. מחרוזת פורמט: "^Text~Color~FontSize~FontName~Opacity~Angle", לדוגמה "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60תפוגת משך מושב מתחלפת בדקות.
boolIsSecuredtrueלא נאכף כרגע — שמור. קישור אסימון נשלט גלובלית על ידי DoconutOptions.UnsafeMode (ראה מושגים מרכזיים → מושבים ואבטחה).

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

סוגמאפייןברירת מחדלתיאור
boolIsWebFarmfalseמיושן — אין לו השפעה. פרסם את המסמך עם DistributedDocumentPublisher.PublishAsync (או IDistributedPublishQueue.EnqueueAsync) והגדר במקום זאת FileShareConfig.RootPath.
stringWebFarmPath""מיושן — אין לו השפעה. השתמש ב-FileShareConfig.RootPath במקום זאת.
boolEditModefalseשמורה לתהליך העבודה של העורך המופץ בנפרד; השאר את 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זווית סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל.

ה-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

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 + מציג + חיפוש + הסבר
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).

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 }))

האם דף זה היה מועיל?