ตัวดู

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

Viewer (namespace Doconut) คือจุดเข้าถึงสาธารณะสำหรับการเปิดเอกสารจาก Razor pages, MVC controllers, Blazor components หรือ minimal APIs. มันเป็น sealed, ลงทะเบียนเป็นบริการ transient โดย AddDoconut(), และได้รับการแก้ไขผ่านการฉีดคอนสตรัคเตอร์ — ไม่ควรสร้างมันโดยตรง.

Viewer ไม่เก็บสถานะต่อคำขอและตั้งใจ ไม่ implement IDisposable: เซสชันเอกสารทำงานอย่างอิสระในแคชเซสชัน, ดังนั้นการทำลายบริการจะไม่สามารถทำลายเอกสารที่เปิดอยู่ได้ (ดู แนวคิดหลัก → วิธีการทำงานของ Viewer).

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 ต้องมีส่วนขยายที่ถูกต้อง — มันเป็นตัวกำหนดการตรวจจับรูปแบบ
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)

จำนวนหน้าทั้งหมดของเซสชันที่เปิดอยู่. จะโยนข้อผิดพลาดหากโทเค็นไม่รู้จักหรือหมดอายุ.

DocOptions

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

ประเภทคุณสมบัติค่าเริ่มต้นคำอธิบาย
stringPassword""รหัสผ่านสำหรับเอกสารที่ได้รับการป้องกัน (คัดลอกไปยังการกำหนดค่ารูปแบบโดยอัตโนมัติ).
intImageResolution0ล้าสมัย. เก็บไว้เพื่อความเข้ากันได้เท่านั้น — ตั้งค่า ImageResolution ในการกำหนดค่ารูปแบบแทน.
stringWatermark""ข้อความลายน้ำที่กำหนดเองที่วาดบนหน้าที่เรนเดอร์. สตริงรูปแบบ: "^Text~Color~FontSize~FontName~Opacity~Angle", เช่น "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60การหมดอายุแบบเลื่อนของเซสชันเป็นนาที.
boolIsSecuredtrueไม่ได้บังคับในขณะนี้ — จองไว้. การผูกโทเค็นถูกควบคุมโดยทั่วโลกโดย DoconutOptions.UnsafeMode (ดู แนวคิดหลัก → Sessions & Security).

คลาสนี้ยังเปิดเผยคุณสมบัติพิเศษที่ตั้งใจอยู่นอกกระแสการดูแบบโฮสต์เดียวปกติ:

ประเภทคุณสมบัติค่าเริ่มต้นคำอธิบาย
boolIsWebFarmfalseทำเครื่องหมายการเปิดเป็นสถานการณ์เว็บฟาร์ม. ใช้เฉพาะกับสถาปัตยกรรมการจัดเก็บ/เซสชันที่แชร์ที่สอดคล้องกัน.
stringWebFarmPath""เส้นทางที่แชร์ที่ใช้โดยกระบวนการทำงานเว็บฟาร์มพิเศษ. ว่างในตัวดูแบบโฮสต์เดียวปกติ.
boolEditModefalseจองไว้สำหรับกระบวนการทำงาน Editor ที่แยกออก; ปล่อย 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
    });
ฟิลด์ตัวอย่างความหมาย
นำหน้า ^^การจัดวางที่มุมทั้งหมดแบบเลือกได้. หากไม่มี จะใช้การวางลายน้ำปกติ.
ข้อความConfidentialข้อความที่แสดงบนแต่ละหน้า. ต้องไม่ว่างเปล่า.
สีRedสีที่ระบุซึ่งเข้าใจโดยชั้นการวาด.
ขนาดฟอนต์24ขนาดฟอนต์; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้นของเรนเดอร์.
ชื่อฟอนต์Verdanaฟอนต์ที่ร้องขอ. ตรวจสอบว่าติดตั้งในสภาพแวดล้อมการปรับใช้แล้ว.
ความทึบ80ค่าบายต์ตั้งแต่ 0 ถึง 255. ต้องแปลงได้สำเร็จ.
มุม-45มุมการหมุนเป็นองศา; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้น.

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

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

สถานะใบอนุญาตค่าที่กำหนดเองที่ให้ผลลัพธ์ที่แสดง
ใบอนุญาตผู้ชมแบบชำระเงินที่ถูกต้องไม่หน้าสะอาด
ใบอนุญาตผู้ชมแบบชำระเงินที่ถูกต้องใช่ลายน้ำแบบกำหนดเอง
ผู้ชมฐานชั่วคราว/สาธิตที่ใช้งานอยู่ไม่หน้าฐานผู้ชมที่สะอาด
ผู้ชมฐานชั่วคราว/สาธิตที่ใช้งานอยู่ใช่ลายน้ำแบบกำหนดเองเมื่อเส้นทางผู้ชมฐานที่สะอาดใช้
ใบอนุญาตที่หายไป, ถูกปฏิเสธ, หมดอายุ, เวอร์ชันไม่ตรง, หรือโดเมนไม่ถูกต้องใดก็ได้ลายน้ำการบังคับใช้/การประเมิน; ค่าที่กำหนดเองไม่สามารถแทนที่ได้
การเรนเดอร์ปลั๊กอินภายใต้กฎการประเมินใดก็ได้ลายน้ำการประเมิน

การตัดสินใจเดียวกันนี้จะถูกนำไปใช้กับภาพหน้าที่ให้บริการและการส่งออกคำอธิบาย. ผลลัพธ์ 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(…)ไฟล์ PNG ที่ฝังคำอธิบาย
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP ของ PNG ต่อหน้า ที่ฝังคำอธิบาย

เมตาดาต้า DICOM

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

ส่งคืนเมตาดาต้าแท็ก DICOM สำหรับเซสชันที่เปิดผ่านปลั๊กอิน DICOM; null สำหรับเอกสารที่ไม่ใช่ DICOM.

ตัวช่วยทรัพยากร — ReferenceCss / ReferenceScripts

สร้างแท็ก <link>/<script> สำหรับทรัพยากรที่ฝังอยู่ที่ให้บริการโดย UseDoconutResources(), ตามลำดับการพึ่งพาที่ถูกต้อง. ชุดสำหรับคุณลักษณะที่จำกัดโดยใบอนุญาตเช่นการค้นหาและการอธิบายจะถูกสร้าง เฉพาะเมื่อใบอนุญาตเปิดใช้งาน, ทำให้ UI ของไคลเอนต์สอดคล้องกับพฤติกรรมของเซิร์ฟเวอร์.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + ตัวดู + การค้นหา + คำอธิบาย
string ReferenceScripts(ScriptConfig? config = null)

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

ScriptConfig แฟล็ก: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and IncludeAnnotationBar (annotation-gated).

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 }))

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

ส่งคืนชื่อแผ่นงานของสเปรดชีตที่เปิดอยู่ตามลำดับของเวิร์กบุ๊ก, หรือรายการว่างเมื่อเอกสารที่เปิดไม่ใช่สเปรดชีต.

เพิ่มในเวอร์ชัน 26.9.0.

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