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

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

ไลบรารี .NET Standard ก่อนหน้านี้เปิดเผยคอนสตรัคเตอร์สาธารณะที่รับ memory cache, HTTP context accessor, และหนึ่งหรือหลายเส้นทางใบอนุญาต. คอนสตรัคเตอร์นั้นได้หายไป; service graph จะจัดหาขึ้นอยู่เหล่านั้น.

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

OpenDocumentAsync

เปิดเอกสารและคืนค่า session token ที่วิดเจ็ตของไคลเอนต์ใช้สำหรับคำขอถัดไปทั้งหมด. ทุกการเปิดเป็นแบบ asynchronous — ไม่มี OpenDocument แบบ synchronous.

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

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

GetWorksheetNames

text

IReadOnlyList<string> GetWorksheetNames(string token)

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

เฉพาะ worksheet ที่ถูกเรนเดอร์เท่านั้นที่จะแสดง: worksheet ที่ซ่อนและว่างจะถูกละเว้น, และเมื่อ ExcelConfig.SheetNames จำกัดการเรนเดอร์, จะมีเฉพาะ worksheet เหล่านั้นเท่านั้นที่ปรากฏ. Worksheet ไม่จำเป็นต้องเป็นหนึ่งหน้า — worksheet ขนาดใหญ่มากจะถูกเรนเดอร์หลายหน้า. จะโยนข้อผิดพลาดหาก token ไม่รู้จักหรือหมดอายุ.

เพิ่มใน 26.9.0.

ธงความสามารถ

สมาชิก	ความหมาย
`bool IsSearchEnabled`	ใบอนุญาตปัจจุบันให้สิทธิ์ `Search`
`bool IsAnnotationEnabled`	ใบอนุญาตปัจจุบันให้สิทธิ์ `Annotation`

ใช้สิ่งเหล่านี้ใน Razor view เพื่อแสดง Ribbon ที่ได้รับใบอนุญาตเฉพาะเมื่อเซิร์ฟเวอร์จะให้บริการจริง — ดู เริ่มต้นอย่างเร็ว.

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

ตัวเลือกที่ไม่ขึ้นกับรูปแบบต่อการเปิดแต่ละครั้ง (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`	ทำเครื่องหมายการเปิดเป็นสถานการณ์ที่ใช้ที่เก็บข้อมูลร่วม โปรดสังเกตการใช้ตัวพิมพ์ – ไลบรารีก่อนหน้านี้สะกดคำนี้เป็น `IsWebfarm`
`string`	`WebFarmPath`	`""`	เส้นทางที่ใช้ร่วมกันโดยเวิร์กโฟลว์นั้น เคยสะกดเป็น `WebfarmPath`. เป็นค่าว่างในผู้ชมโฮสต์เดียวปกติ และไม่จำเป็นบนเส้นทางการเผยแพร่ที่อธิบายใน การปรับใช้แบบกระจาย
`bool`	`EditMode`	`false`	จองไว้สำหรับเวิร์กโฟลว์การแก้ไขที่แจกจ่ายแยกต่างหาก; ปล่อยให้ `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(…)`	ไฟล์ PNG ที่ฝังหมายเหตุไว้ในไฟล์
`Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)`	ZIP ของ PNG แยกหน้าที่ฝังหมายเหตุไว้ในไฟล์

แต่ละรายการต้องรับโทเคนของเซสชัน รูปแบบ GetAnnotationManager(pageWidth, pageHeight) ที่ไม่ต้องใช้เซสชันของไลบรารีก่อนหน้ายังคงอยู่สำหรับสร้างหมายเหตุนอกเซสชัน แต่การโหลดยังคงต้องใช้โทเคน

เมตาดาต้า DICOM

text

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

เมธอดนี้มีไว้เพื่อให้สอดคล้องกับ API แต่แพคเกจนี้ไม่สามารถจัดหาป้ายกำกับเทคนิคของ DICOM ได้: ตัวอ่านเมตาเดตามาพร้อมกับรุ่น .NET 8 เท่านั้น มันคืนค่า 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 + splitter + links), 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 }))

ตัวช่วยเหล่านี้เป็นวิธีที่สนับสนุนสำหรับการส่งทรัพยากรให้กับเบราว์เซอร์ แอปพลิเคชันที่คัดลอก docViewer.js, documentLinks.js, และ docViewer.UI.js ไปยัง wwwroot ควรลบสำเนาเหล่านั้นออกเมื่อหน้าแสดงผลจากแท็กที่สร้าง