ตัวดูเอกสาร – Doconut เอกสาร

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

Viewer ไม่เก็บสถานะต่อคำขอและโดยเจตนา ไม่ implement IDisposable: เซสชันเอกสารทำงานอย่างอิสระในแคชของเซสชัน, ดังนั้นการทำลายบริการจะไม่สามารถทำลายเอกสารที่เปิดอยู่ได้ (ดู Core Concepts → วิธีการทำงานของ 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):

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`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` (ดู Core Concepts → เซสชันและความปลอดภัย).

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

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`bool`	`IsWebFarm`	`false`	ทำเครื่องหมายการเปิดเป็นสถานการณ์เว็บฟาร์ม. ใช้เฉพาะกับสถาปัตยกรรมที่เก็บข้อมูล/เซสชันแบบแชร์ที่สอดคล้อง.
`string`	`WebFarmPath`	`""`	เส้นทางที่แชร์ที่ใช้โดยกระบวนการเว็บฟาร์มพิเศษ. ว่างในตัวดูโฮสต์เดียวปกติ.
`bool`	`EditMode`	`false`	จองไว้สำหรับกระบวนการ 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)

เมธอดนี้มีเพื่อให้สอดคล้องกับ API, แต่ตัวดู DICOM ของ .NET 6 ไม่สามารถให้แท็กทางเทคนิคได้. มันจะคืนค่า null สำหรับเซสชัน DICOM และไม่ใช่ DICOM; ในเซสชัน DICOM มันยังเขียนคำเตือนครั้งเดียวที่อธิบายข้อจำกัดของแพลตฟอร์ม. การเรนเดอร์หน้า, เฟรม, และแอนิเมชันยังคงได้รับการสนับสนุน.

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

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

text

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (ควบคุมโดยการค้นหา), IncludeAnnotationCss (ควบคุมโดยการอธิบายภาพ).

ScriptConfig flags: IncludeJQuery (จำเป็นสำหรับทั้งหมด), IncludeBootstrap, IncludeViewerScripts (แกน: docViewer.js + ตัวแยก + ลิงก์), IncludeSearchScripts และ IncludeSearchBar (ควบคุมโดยการค้นหา), IncludeAnnotationScripts และ IncludeAnnotationBar (ควบคุมโดยการอธิบายภาพ).

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.