מציג
מחלקת מציג המסמכים הראשית
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 חייב לשאת את ההרחבה הנכונה — היא מניעה את זיהוי הפורמט |
// פתיחה פשוטה
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 עבור אסימון ריק.
GetWorksheetNames
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):
| סוג | מאפיין | ברירת מחדל | תיאור |
|---|---|---|---|
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. |
string | WebFarmPath | "" | מיושן — אין לו השפעה. השתמשו ב-FileShareConfig.RootPath במקום זאת. |
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 | זווית סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל. |
ה-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
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)השיטה קיימת למטרת התאמת API, אך מציג ה‑DICOM של .NET 6 אינו יכול לספק תגיות טכניות. היא מחזירה 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 }))האם דף זה היה מועיל?