מציג

מחלקת מציג המסמכים הראשית

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

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

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)

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

GetPageDimensions

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

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

GetWorksheetNames

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 כדי להציג ריבון מורשה רק כאשר השרת אכן יגיש אותו — ראו התחלה מהירה.

אפשרויות מסמך

אפשרויות לכל פתיחה, בלתי תלויות בפורמט (מרחב שמות 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)

השיטה קיימת למטרת התאמת API, אך מציג ה‑DICOM של .NET 6 אינו יכול לספק תגיות טכניות. היא מחזירה null עבור סשנים של DICOM ולא‑DICOM; בסשן 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 }))

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