מציג
מחלקת מציג המסמכים הראשית
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 חייב לשאת את ההרחבה הנכונה — היא מניעה את זיהוי הפורמט |
// פתיחה פשוטה
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
void CloseDocument(string token)מסיר את הסשן מהמטמון (משחרר את מנוע המסמך מיידית), מוחק את סמן האבטחה, ומבטל את מתן הגישה. אופציונלי — תפוגה מחליקה מבצעת את ניקוי האותו — אך מומלץ למסמכים גדולים.
GetPageCount
int GetPageCount(string token)סך כל העמודים של הסשן הפתוח. זורק InvalidOperationException (Document session not found. Please re-open document.) אם האסימון אינו ידוע או פג, ו-ArgumentException עבור אסימון ריק.
GetPageDimensions
(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 במקום זאת. שימו לב לאיות — הספרייה הקודמת כתבה זאת IsWebfarm. |
string | WebFarmPath | "" | מיושן — אין לו השפעה. השתמשו ב-FileShareConfig.RootPath, כפי שמתואר ב-פריסות מבוזרות. בעבר כתוב WebfarmPath. |
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 | זווית סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל. |
המפרש מצפה בדיוק לשישה שדות אחרי ה^ האופציונלי. הגדרה לא תקינה מוחלפת על ידי 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
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)השיטה קיימת ליישור API, אך חבילה זו אינה יכולה לספק תגים טכניים של DICOM: קורא המטה‑נתונים משגר רק גרסת .NET 8. הוא מחזיר null עבור סשני DICOM ולא‑DICOM; בסשן 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 }))עוזרים אלו הם הדרך הנתמכת להעברת משאבי הדפדפן. יישומים שהעתיקו את docViewer.js, documentLinks.js, ו‑docViewer.UI.js אל wwwroot צריכים להסיר את ההעתקים הללו ברגע שהדף מוצג מהתגים שהופקו.
האם דף זה היה מועיל?