מציג

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

Viewer (namespace Doconut) הוא נקודת הכניסה הציבורית לפתיחת מסמכים מבקרי MVC, דפי Web Forms, ומטפלים. זהו שירות זמני המורכב מ‑DoconutHost.Initialize; קבל אותו במיקום שבו אתה משתמש בו:

csharp
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() גם עובד לאחר שDoconutHost.Initialize רץ — הוא פותר את אותם השירותים — מה ששומר על קוד שהועבר מהחבילה הקלאסית ומתקמפל. לפני Initialize, הוא זורק InvalidOperationException.

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

OpenDocumentAsync

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

גרסהמתי להשתמש
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 });

// מתוך העלאה (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

חריגות לטיפול:

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

OpenDocument (סינכרוני)

לקוד‑בקר של Web Forms וקוד אחר שאינו משתמש בדפים אסינכרוניים:

text
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

כל אחד מחזיר את האסימון וגם שומר אותו ב‑viewer.Token. fileName חייב לשאת את ההרחבה הנכונה. עטיפות אלו בטוחות לקריאה מדף Web Forms: נתיב הפתיחה לעולם אינו מתחדש בהקשר הבקשה של ASP.NET, ולכן המתנה עליו לא יכולה לגרום לחסימה. הדבר לא נכון עבור כל API אסינכרוני של Doconut — ראה את סעיף Web Forms ב‑תוסף ממיר.

סגור מסמך

text
void CloseDocument(string token)

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

שאילתות סשן

חברמחזיר
int GetPageCount(string token)סך כל העמודים של המסמך הפתוח
(int Width, int Height) GetPageDimensions(string token, int page = 1)גודל עמוד ברירת המחדל המוצג ב‑100 % זום — מרחב הקואורדינטות להערות שנבנות בקוד
IReadOnlyList<string> GetWorksheetNames(string token)גיליונות העבודה המוצגים של גיליון אלקטרוני, לפי סדר חוברת העבודה; ריק עבור מסמכים אחרים

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

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

אפשרויות בלתי תלויות בפורמט לכל פתיחה (מרחב שמות Doconut):

סוגמאפייןברירת מחדלתיאור
stringPassword""סיסמה למסמכים מוגנים (מועתקת לתצורת הפורמט אוטומטית).
stringWatermark""טקסט סימן מים מותאם אישית המצויר על דפים מוצגים — ראה למטה.
intTimeOut60תפוגה מתגלגלת של ההפעלה, בדקות.
stringBrowserId""חוות רשת: הדפדפן שהכרטיס החתום קשור אליו. הגדר זאת עם DoconutFarmBinding.EnsureBrowserId (ראה הפעלות ואבטחה).
stringUserId""חוות רשת: המשתמש המחובר שהכרטיס קשור אליו, מ‑DoconutFarmBinding.ResolveUserId.
intImageResolution0מיושן. הגדר ImageResolution בתצורת הפורמט במקום זאת.
boolIsSecuredtrueשמורה; לא נאכפת. בקרת גישה היא DoconutOptions.UnsafeMode.
boolIsWebFarm / string WebFarmPathfalse / ""נשמר עבור קוד שהועבר מהחבילה הקלאסית. הם לא מפעילים מצב חווה — AddDoconutDistributed עושה זאת.
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משפחת גופנים. חייב להיות מותקן על השרת — ל‑Windows Server יש פחות גופנים מאשר למחשב שולחני.
שקיפות800 עד 255. חייב להיות ניתן לפירוש.
זווית-45סיבוב במעלות; קלט מספרי לא תקין חוזר לברירת המחדל.

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

החלטת רישיון

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

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

API של הערות

טעינת והוצאת הערות בצד השרת. המדריך נמצא ב-הערות.

MemberPurpose
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)טען את המעטפה המקודדת שהוחזרה על‑ידי 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)

בחבילה זו הוא תמיד מחזיר null, ובקשת המטא‑נתונים של הווידג'ט מחזירה 501 Not Implemented: קריאת תגיות DICOM אינה זמינה ב‑.NET Framework. רינדור DICOM — עמודים, פריימים, והנפשה — עובד. ראה תוסף DICOM.

עוזרי משאבים — ReferenceCss / ReferenceScripts

הפץ את התגים <link> ו‑<script> עבור המשאבים שמודול המשאבים משרת תחת DoconutOptions.ResourcesPath, בסדר תלותיות. הקבצים לתכונות המוגבלות ברישיון (Search, Annotation) מופצים רק כאשר הרישיון מעניק אותם.

text
string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // מצב רישיון, למניעת קוד init ribbon
bool IsAnnotationEnabled { get; }

דגלי CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (מוגבל חיפוש), IncludeAnnotationCss (מוגבל הערה).

דגלי ScriptConfig: IncludeJQuery (נדרש על‑ידי כולם), IncludeBootstrap, IncludeViewerScripts (סקריפטים ליבת הצופה), IncludeSearchScripts ו‑IncludeSearchBar (מוגבל חיפוש), IncludeAnnotationScripts ו‑IncludeAnnotationBar (מוגבל הערה), EmitFeatureFlags (ברירת מחדל true: גם כותב סקריפט inline window.Doconut.features = { search, annotation, editor }; הגדר אותו ל‑false תחת Content‑Security‑Policy שחוסמת סקריפטים inline).

שניהם מחזירים HTML: כתבו אותם עם @Html.Raw(...) ב‑MVC 5 (הפקו אותם בבקר — לתצוגות אין @inject) או עם <%= %> ב‑Web Forms. התחלה מהירה מציגה את שניהם.

RenderViewer

text
string RenderViewer(string elementId, string token, ViewerConfig? config = null)

מחזיר בלוק <script> שמאתחל את הווידג'ט על האלמנט עם id elementId ומציג את המסמך: docViewer({...}) נבנה מה‑ViewerConfig (ברירת מחדל: BasePath: '/', ResPath: 'doconut-res/images'), ואז .View(token). כתבו זאת אחרי סקריפטי הצופה. הסקריפט שנוצר אינו שומר הפנייה לאובייקט הצופה, ולכן דף עם סרגל כלים משלו צריך לאתחל את הווידג'ט ידנית במקום זאת. ראה תצורת הצופה.

חוות אינטרנט

string? AccessToken מחזיק את הכרטיס החתום שהונפק על‑ידי הפתיחה האחרונה כאשר מצב מבוזר פעיל ו‑UnsafeMode הוא false; הוא null בשרת יחיד. שלחו אותו לווידג'ט עם הטוקן: objViewer.View(token, accessToken).

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