מציג

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

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

הספרייה הקודמת של .NET Standard חשפה קונסטרוקטור ציבורי שלוקח את מטמון הזיכרון, את גישה להקשר HTTP, ואחד או יותר מנתיבי רישיון. קונסטרוקטור זה נעלם; גרף השירותים מספק את התלויות הללו.

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

OpenDocumentAsync

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

גרסהמתי להשתמש
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)המסמך אינו קובץ על הדיסק (העלאה, מסד נתונים, בלוב). 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 עבור אסימון ריק.

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

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 במקום זאת. שימו לב לאיות — הספרייה הקודמת כתבה זאת IsWebfarm.
stringWebFarmPath""מיושן — אין לו השפעה. השתמשו ב-FileShareConfig.RootPath, כפי שמתואר ב-פריסות מבוזרות. בעבר כתוב WebfarmPath.
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זווית סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל.

המפרש מצפה בדיוק לשישה שדות אחרי ה^ האופציונלי. הגדרה לא תקינה מוחלפת על ידי fallback הInvalid Watermark הגלוי של ה‑SDK במקום להיעלם בשקט.

החלטת רישיון

מצב רישיוןערך מותאם שסופקתוצאה מוצגת
רישיון צפייה בתשלום תקףלאדף נקי
רישיון צפייה בתשלום תקףכןחותמת מים מותאמת
צופה בסיס זמני/הדגמה פעיללאדף צופה בסיסי נקי
צופה בסיס זמני/הדגמה פעילכןחותמת מים מותאמת כאשר נתיב הצופה הבסיסי הנקי חל
רישיון חסר, נדחה, פג תוקף, גרסה שגויה, או תחום לא חוקיכל אחדחותמת מים של אכיפה/הערכה; הערך המותאם אינו עוקף אותה
רינדור תוסף תחת כללי הערכהכל אחדחותמת מים של הערכה

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

API של ההערות

טעינת והוצאה של הערות בצד השרת. המדריך המלא נמצא ב‑Guides → Annotations; הממשק הוא:

חברמטרה
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 של קבצי PNG לכל דף עם אנוטציות משולבות

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

מטא‑נתוני DICOM

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

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

עוזרים אלו הם הדרך הנתמכת להעברת משאבי הדפדפן. יישומים שהעתיקו את docViewer.js, documentLinks.js, ו‑docViewer.UI.js אל ‎wwwroot צריכים להסיר את ההעתקים הללו ברגע שהדף מוצג מהתגים שהופקו.

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