ผู้ดูเอกสาร

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

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

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

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)

จำนวนหน้าทั้งหมดของเซสชันที่เปิดอยู่. จะโยน InvalidOperationException (Document session not found. Please re-open document.) หากโทเค็นไม่รู้จักหรือหมดอายุ, และ ArgumentException สำหรับโทเค็นว่าง.

GetPageDimensions (ขนาดหน้ากระดาษ)

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

ขนาดหน้าที่เรนเดอร์เริ่มต้นของเอกสารที่ซูม 100% — พื้นที่พิกัดสำหรับหมายเหตุที่สร้างในโค้ด. page ถูกยอมรับเพื่อความเข้ากันได้; ผลลัพธ์คือค่าปริยายของเอกสาร. จะโยน InvalidOperationException (Document session not found. Please re-open document.) หากโทเค็นไม่รู้จักหรือหมดอายุ, และ ArgumentException สำหรับโทเค็นว่าง.

GetWorksheetNames (ชื่อแผ่นงาน)

text
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 view เพื่อแสดง Ribbon ที่ได้รับใบอนุญาตเฉพาะเมื่อเซิร์ฟเวอร์จะให้บริการจริง — ดู เริ่มต้นอย่างเร็ว.

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

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

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

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

ประเภทคุณสมบัติค่าเริ่มต้นคำอธิบาย
boolIsWebFarmfalseล้าสมัย — ไม่มีผล. เผยแพร่เอกสารด้วย DistributedDocumentPublisher.PublishAsync (หรือ IDistributedPublishQueue.EnqueueAsync) และตั้งค่า FileShareConfig.RootPath แทน.
stringWebFarmPath""ล้าสมัย — ไม่มีผล. ใช้ FileShareConfig.RootPath แทน.
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 Invalid Watermark ที่มองเห็นได้ของ SDK แทนที่จะหายไปโดยเงียบ.

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

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

การตัดสินใจเดียวกันจะถูกนำไปใช้กับภาพหน้าที่ให้บริการและการส่งออกหมายเหตุ 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 ต่อหน้า พร้อมหมายเหตุที่ฝังอยู่

ข้อมูลเมตา 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 (ต้องมีการค้นหา), 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).

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

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