Viewer – Doconut เอกสาร

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

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

OpenDocumentAsync

เปิดเอกสารและคืนค่า token ของเซสชันที่วิดเจ็ตไคลเอนต์ใช้สำหรับคำขอทุกครั้งต่อไป

การโหลดทับ	ใช้เมื่อ
`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

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
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)

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

DocOptions

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

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`string`	`Password`	`""`	รหัสผ่านสำหรับเอกสารที่ป้องกัน (จะคัดลอกไปยังคอนฟิกรูปแบบโดยอัตโนมัติ).
`int`	`ImageResolution`	`0`	Obsolete. เก็บไว้เพื่อความเข้ากันได้เท่านั้น — ตั้งค่า `ImageResolution` ในคอนฟิกรูปแบบแทน.
`string`	`Watermark`	`""`	ข้อความลายน้ำที่กำหนดเองที่วาดบนหน้าที่เรนเดอร์. รูปแบบสตริง: `"^Text~Color~FontSize~FontName~Opacity~Angle"`, ตัวอย่าง `"^Sample Copy~Red~24~Verdana~80~-45"`.
`int`	`TimeOut`	`60`	เวลาเลื่อนหมดอายุของเซสชันเป็นนาที.
`bool`	`IsSecured`	`true`	Not currently enforced — reserved. การผูก token ถูกควบคุมโดยทั่วโลกโดย `DoconutOptions.UnsafeMode` (ดูแนวคิดหลัก → เซสชันและความปลอดภัย).

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

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`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
    });

ฟิลด์	ตัวอย่าง	ความหมาย
Leading `^`	`^`	ตัวเลือกการจัดวางแบบทุกมุม. หากไม่มีจะใช้การวางลายน้ำปกติ.
Text	`Confidential`	ข้อความที่แสดงบนแต่ละหน้า. ต้องไม่เป็นค่าว่าง.
Color	`Red`	สีที่กำหนดชื่อซึ่งเข้าใจโดยชั้นวาด.
FontSize	`24`	ขนาดฟอนต์; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้นของเรนเดอร์.
FontName	`Verdana`	ฟอนต์ที่ต้องการ. ตรวจสอบให้แน่ใจว่าติดตั้งในสภาพแวดล้อมการปรับใช้.
Opacity	`80`	ค่าไบต์จาก 0 ถึง 255. ต้องแปลงสำเร็จ.
Angle	`-45`	มุมการหมุนเป็นองศา; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้น.

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

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

สถานะใบอนุญาต	ค่าที่กำหนดเอง	ผลลัพธ์ที่แสดง
Valid paid viewer license	No	Clean page
Valid paid viewer license	Yes	Custom watermark
Active Temporary/Demo base viewer	No	Clean base-viewer page
Active Temporary/Demo base viewer	Yes	Custom watermark when the clean base-viewer path applies
Missing, rejected, expired, wrong-version, or invalid-domain license	Either	Enforcement/evaluation watermark; the custom value does not override it
Plugin rendering under evaluation rules	Either	Evaluation watermark

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

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)`	โหลดคำอธิบายจาก envelope ที่เข้ารหัสเป็น 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 + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

ScriptConfig flags: 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 }))