Viewer

คลาสตัวดูเอกสารหลัก

Viewer (namespace Doconut) คือจุดเข้าถึงสาธารณะสำหรับการเปิดเอกสารจากคอนโทรลเลอร์ MVC, หน้า Web Forms, และตัวจัดการต่าง ๆ มันเป็นบริการ transient ที่ประกอบด้วย DoconutHost.Initialize; ให้ resolve ที่ที่คุณใช้มัน:

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

new Viewer() ทำงานได้เช่นกันเมื่อ DoconutHost.Initialize ทำงานแล้ว — มัน resolve บริการเดียวกัน — ซึ่งทำให้โค้ดที่ย้ายมาจากแพ็กเกจคลาสสิกยังคงคอมไพล์ได้ ก่อน Initialize, มันจะโยน InvalidOperationException.

Viewer ไม่เก็บสถานะเอกสารต่อคำขอและโดยเจตนา ไม่ implements IDisposable: เซสชันเอกสารทำงานอย่างอิสระจากมัน, ดังนั้นการทำลาย Viewer จะไม่สามารถปิดเอกสารที่เปิดอยู่ได้ (ดู วิธีการทำงานของ 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)เอกสารไม่ได้เป็นไฟล์บนดิสก์ (อัปโหลด, ฐานข้อมูล, blob). fileInfo ต้องมีส่วนขยายที่ถูกต้อง — มันจะเลือกรูปแบบ
csharp
// เปิดอย่างง่าย
string token = await viewer.OpenDocumentAsync(path);

// พร้อมการกำหนดค่าและตัวเลือกตามรูปแบบแต่ละประเภท
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// จากการอัปโหลด (HttpPostedFileBase ใน MVC; HttpPostedFile ใน 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 — ไม่มี Viewer ที่รองรับส่วนขยายของไฟล์.
  • 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, ดังนั้นการรอคอยจึงไม่สามารถทำให้เกิด deadlock. สิ่งเดียวกัน ไม่ เป็นจริงสำหรับทุก API ของ Doconut แบบอะซิงโครนัส — ดูส่วน Web Forms ของ ปลั๊กอินแปลงไฟล์.

CloseDocument

text
void CloseDocument(string token)

ลบเซสชัน (ปล่อยเอนจินเอกสารโดยทันที), ลบการให้สิทธิ์ของโทเค็นจากเซสชัน ASP.NET ของคำขอปัจจุบัน, และเพิกถอนโทเค็น. ตัวเลือก — การหมดอายุแบบเลื่อนทำการทำความสะอาดเดียวกัน — แต่แนะนำสำหรับเอกสารขนาดใหญ่.

การสืบค้นเซสชัน

MemberReturns
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 สำหรับโทเค็นที่ว่างเปล่า.

ตัวเลือกเอกสาร

ตัวเลือกที่ไม่ขึ้นกับรูปแบบต่อการเปิดแต่ละครั้ง (namespace Doconut):

TypePropertyDefaultDescription
stringPassword""รหัสผ่านสำหรับเอกสารที่ป้องกัน (คัดลอกไปยังการกำหนดค่ารูปแบบโดยอัตโนมัติ).
stringWatermark""ข้อความลายน้ำที่กำหนดเองที่วาดบนหน้าที่แสดงผล — ดูด้านล่าง.
intTimeOut60การหมดอายุแบบเลื่อนของเซสชัน, หน่วยเป็นนาที.
stringBrowserId""ฟาร์มเว็บ: เบราว์เซอร์ที่ตั๋วที่ลงนามผูกไว้. ตั้งค่าด้วย DoconutFarmBinding.EnsureBrowserId (ดู เซสชันและความปลอดภัย).
stringUserId""ฟาร์มเว็บ: ผู้ใช้ที่เข้าสู่ระบบที่ตั๋วผูกไว้, จาก DoconutFarmBinding.ResolveUserId.
intImageResolution0ล้าสมัย. ตั้งค่า ImageResolution ในการกำหนดค่ารูปแบบแทน.
boolIsSecuredtrueสงวนไว้; ไม่บังคับใช้. การควบคุมการเข้าถึงคือ DoconutOptions.UnsafeMode.
boolIsWebFarm / string WebFarmPathfalse / ""เก็บไว้สำหรับโค้ดที่ย้ายมาจากแพคเกจคลาสสิก. พวกมันไม่ได้สลับโหมดฟาร์ม — AddDoconutDistributed ทำ.
boolEditModefalseสงวนไว้สำหรับเครื่องมือแก้ไขที่แจกแยก; ปล่อย false.

ลายน้ำที่กำหนดเอง

DocOptions.Watermark รับฟิลด์หกฟิลด์ที่คั่นด้วย tilde. ตัวเลือกนำหน้า ^ ขอการจัดวางที่มุมทั้งหมด:

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
    });
FieldExampleMeaning
Leading ^^การจัดวางที่มุมทั้งหมดแบบเลือกได้. หากไม่มี, จะใช้การวางตำแหน่งปกติ.
TextConfidentialข้อความที่วาดบนแต่ละหน้า. ต้องไม่ว่างเปล่า.
ColorRedสีที่มีชื่อ.
FontSize24ขนาดฟอนต์; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้น.
FontNameVerdanaชื่อฟอนต์. ตระกูลฟอนต์. ต้องติดตั้งบนเซิร์ฟเวอร์ — Windows Server มีฟอนต์น้อยกว่าคอมพิวเตอร์เดสก์ท็อป.
Opacity800 ถึง 255. ต้องสามารถแปลงได้.
Angle-45การหมุนเป็นองศา; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้น.

ตัวแยกวิเคราะห์คาดหวังฟิลด์หกฟิลด์อย่างแม่นยำหลังจาก ^ ที่เป็นตัวเลือก. คำจำกัดความที่ไม่ถูกต้องจะถูกแทนที่ด้วยข้อความ Invalid Watermark ที่มองเห็นได้แทนที่จะหายไปโดยเงียบ.

การตัดสินใจเรื่องใบอนุญาต

License stateCustom value suppliedRendered result
ใบอนุญาตผู้ชมแบบชำระเงินที่ถูกต้องNoClean page
ใบอนุญาตผู้ชมแบบชำระเงินที่ถูกต้องYesCustom watermark
ใบอนุญาตชั่วคราว/สาธิตที่ใช้งานอยู่NoClean page
ใบอนุญาตชั่วคราว/สาธิตที่ใช้งานอยู่YesCustom watermark
ใบอนุญาตที่หายไป, ถูกปฏิเสธ, หมดอายุ, เวอร์ชันไม่ตรง, หรือโดเมนไม่ถูกต้องEitherEvaluation watermark; the custom value does not replace it

การตัดสินใจเดียวกันนี้ใช้กับหน้าที่ให้บริการและการส่งออกคำอธิบาย. ลายน้ำที่กำหนดเองเป็นคุณลักษณะของแอปพลิเคชันที่มีใบอนุญาต, ไม่ใช่วิธีการแทนที่ลายน้ำการประเมิน.

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)โหลดซองที่เข้ารหัสซึ่งส่งกลับโดย 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 ต่อหน้า ที่ฝังคำอธิบายไว้

เมตาดาต้า DICOM

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

บนแพคเกจนี้จะคืนค่าเสมอ null และคำขอเมตาดาต้าของวิดเจ็ตตอบกลับ 501 Not Implemented: การอ่านแท็ก DICOM ไม่พร้อมใช้งานบน .NET Framework. DICOM rendering — หน้า, เฟรม, และแอนิเมชัน — ทำงานได้. ดู ปลั๊กอิน 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; }                       // สถานะใบอนุญาต, เพื่อป้องกันรหัสการเริ่มต้น ribbon
bool IsAnnotationEnabled { get; }

CssConfig แฟล็ก: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig แฟล็ก: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (the core viewer scripts), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and IncludeAnnotationBar (annotation-gated), EmitFeatureFlags (default true: also writes an inline window.Doconut.features = { search, annotation, editor } script; set it to false under a Content-Security-Policy that blocks inline script).

Both return HTML: write them with @Html.Raw(...) in MVC 5 (produce them in the controller — views have no @inject) or <%= %> in 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). เขียนหลังสคริปต์ของตัวดู. สคริปต์ที่สร้างไม่มีการอ้างอิงถึงอ็อบเจ็กต์ของตัวดู, ดังนั้นหน้าที่มีแถบเครื่องมือของตนเองควรเริ่มต้นวิดเจ็ตด้วยตนเองแทน. ดู ViewerConfig.

ฟาร์มเว็บ

string? AccessToken เก็บตั๋วที่ลงนามซึ่งออกโดยการเปิดล่าสุดเมื่อโหมดกระจายเปิดใช้งานและ UnsafeMode เป็น false; มันเป็น null บนเซิร์ฟเวอร์เดียว. ส่งไปยังวิดเจ็ตพร้อมโทเคน: objViewer.View(token, accessToken).

หน้านี้เป็นประโยชน์หรือไม่?