ตัวดู
คลาสตัวดูเอกสารหลัก
Viewer (namespace Doconut) เป็นจุดเข้าถึงสาธารณะสำหรับการเปิดเอกสารจากหน้า Razor, คอนโทรลเลอร์ MVC, คอมโพเนนต์ Blazor หรือ Minimal API. มันถูก sealed, ลงทะเบียนเป็นบริการ transient โดย AddDoconut(), และได้รับการแก้ไขผ่านการฉีดคอนสตรัคเตอร์ — ไม่ควรสร้างมันโดยตรง.
Viewer ไม่เก็บสถานะต่อคำขอและตั้งใจ ไม่ implement IDisposable: เซสชันเอกสารทำงานอย่างอิสระในแคชของเซสชัน, ดังนั้นการทำลายบริการจะไม่สามารถทำให้เอกสารที่เปิดอยู่ถูกปิดได้ (ดู Core Concepts → How the Viewer Works).
OpenDocumentAsync (เปิดเอกสารแบบอะซิงค์)
เปิดเอกสารและส่งคืนโทเคนเซสชันที่วิดเจ็ตของไคลเอนต์ใช้สำหรับคำขอทั้งหมดต่อไป.
| Overload | ใช้เมื่อ |
|---|---|
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 view เพื่อแสดง Ribbon ที่มีใบอนุญาตเฉพาะเมื่อเซิร์ฟเวอร์จะให้บริการจริง — ดู เริ่มต้นอย่างเร็ว.
DocOptions
ตัวเลือกต่อการเปิด, ไม่ขึ้นกับรูปแบบ (namespace 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 | จองไว้สำหรับเวิร์กโฟลว์ Editor ที่แจกแยก; ปล่อยให้ false สำหรับผู้ชมมาตรฐาน. |
ลายน้ำที่กำหนดเอง
DocOptions.Watermark ใช้หกฟิลด์ที่คั่นด้วย tilde. ตัวเลือกนำหน้า ^ ขอการจัดวางแบบทุกมุม:
^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 | ขนาดฟอนต์; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้นของ renderer. |
| ชื่อฟอนต์ | 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
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)เมธอดนี้มีไว้เพื่อให้สอดคล้องกับ API, แต่ตัวดู DICOM ของ .NET 6 ไม่สามารถให้แท็กทางเทคนิคได้ มันคืนค่า null สำหรับเซสชัน DICOM และเซสชันที่ไม่ใช่ DICOM; ในเซสชัน DICOM จะเขียนคำเตือนหนึ่งครั้งที่อธิบายข้อจำกัดของแพลตฟอร์ม การเรนเดอร์หน้า, เฟรม, และแอนิเมชันยังคงรองรับ
ตัวช่วยทรัพยากร — ReferenceCss / ReferenceScripts
ส่งออกแท็ก <link>/<script> สำหรับทรัพยากรฝังที่ให้บริการโดย UseDoconutResources(), ตามลำดับการขึ้นต่อกันที่ถูกต้อง. แพ็กเกจสำหรับฟีเจอร์ที่ต้องมีใบอนุญาต เช่น การค้นหาและการทำหมายเหตุ จะถูกส่งออก เฉพาะเมื่อใบอนุญาตเปิดใช้งานฟีเจอร์เหล่านั้น เพื่อให้ UI ของไคลเอนต์สอดคล้องกับพฤติกรรมของเซิร์ฟเวอร์.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + ตัวดู + การค้นหา + คำอธิบาย
string ReferenceScripts(ScriptConfig? config = null)CssConfig แฟล็ก: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).
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 }))หน้านี้เป็นประโยชน์หรือไม่?