Viewer – Doconut เอกสาร

Viewer (namespace Doconut) คือจุดเข้าถึงสาธารณะสำหรับการเปิดเอกสารจากคอนโทรลเลอร์ MVC, หน้า Web Forms, และแฮนด์เลอร์ต่าง ๆ มันเป็นบริการ transient ที่สร้างโดย DoconutHost.Initialize; ให้ดึงมันออกมาในที่ที่คุณใช้:

csharp

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() ก็ทำงานได้เช่นกันเมื่อ DoconutHost.Initialize ได้ทำงานแล้ว — มันจะ resolve บริการเดียวกัน — ซึ่งทำให้โค้ดที่ย้ายมาจากแพคเกจคลาสสิกยังคงคอมไพล์ได้ ก่อน Initialize จะโยน InvalidOperationException.

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

OpenDocumentAsync

เปิดเอกสารและคืนค่า token ของเซสชันที่วิดเจ็ตใช้สำหรับทุกคำขอถัดไป เมื่อ UnsafeMode เป็น false (ค่าเริ่มต้น) token จะถูกมอบให้กับเซสชัน ASP.NET ของคำขอปัจจุบัน — เรียกจากคำขอที่มีสถานะเซสชัน (ดู Sessions & Security).

รูปแบบการเรียก	ใช้เมื่อ
`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 (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

ข้อยกเว้นที่ต้องจัดการ:

LicenseException — พบใบอนุญาตแต่ถูกปฏิเสธ (ข้อความจะบอกรายละเอียดเหตุผล) หรือรูปแบบต้องการความสามารถของปลั๊กอินที่ใบอนุญาตไม่ได้ให้.
FormatNotSupportedException — ไม่มี viewer ใดรองรับส่วนขยายของไฟล์.
InvalidDataException — เนื้อหาเสียหายหรือไม่ตรงกับส่วนขยายของไฟล์.

OpenDocument (synchronous)

สำหรับโค้ด‑behind ของ Web Forms และโค้ดอื่นที่ไม่ใช้หน้าแบบ asynchronous:

text

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

แต่ละเมธอดจะคืนค่า token และยังเก็บไว้ใน viewer.Token. fileName ต้องมีส่วนขยายที่ถูกต้อง ตัวห่อเหล่านี้ปลอดภัยต่อการเรียกจากหน้า Web Forms: เส้นทางการเปิดจะไม่กลับมาทำงานบนบริบทของคำขอ ASP.NET, ดังนั้นการรอคอยจะไม่ทำให้เกิด deadlock. สิ่งนี้ ไม่ เป็นจริงสำหรับทุก Doconut API แบบ asynchronous — ดูส่วน Web Forms ของ ปลั๊กอินแปลงไฟล์.

CloseDocument

text

void CloseDocument(string token)

ลบเซสชัน (ปล่อยเอนจินเอกสารทันที), ลบสิทธิ์ของโทเค็นจากเซสชัน ASP.NET ของคำขอปัจจุบัน, และเพิกถอนโทเค็น. ตัวเลือก — การหมดอายุแบบเลื่อนทำความสะอาดเดียวกัน — แต่แนะนำสำหรับเอกสารขนาดใหญ่.

การสอบถามเซสชัน

สมาชิก	ผลลัพธ์
`int GetPageCount(string token)`	จำนวนหน้าทั้งหมดของเอกสารที่เปิดอยู่
`(int Width, int Height) GetPageDimensions(string token, int page = 1)`	ขนาดหน้าที่เรนเดอร์โดยค่าเริ่มต้นที่การซูม 100% — พื้นที่พิกัดสำหรับลายน้ำที่สร้างในโค้ด
`IReadOnlyList<string> GetWorksheetNames(string token)`	เวิร์กชีตที่เรนเดอร์ของสเปรดชีตตามลำดับในเวิร์กบุ๊ก; ว่างสำหรับเอกสารประเภทอื่น

แต่ละเมธอดจะโยนข้อยกเว้นหากโทเค็นไม่รู้จักหรือหมดอายุ.

DocOptions

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

ประเภท	คุณสมบัติ	ค่าเริ่มต้น	คำอธิบาย
`string`	`Password`	`""`	รหัสผ่านสำหรับเอกสารที่ป้องกัน (คัดลอกไปยังการตั้งค่ารูปแบบโดยอัตโนมัติ).
`string`	`Watermark`	`""`	ข้อความลายน้ำแบบกำหนดเองที่วาดบนหน้าที่เรนเดอร์ — ดูด้านล่าง.
`int`	`TimeOut`	`60`	การหมดอายุแบบเลื่อนของเซสชัน, หน่วยเป็นนาที.
`string`	`BrowserId`	`""`	เว็บฟาร์ม: เบราว์เซอร์ที่ตั๋วที่ลงนามผูกไว้. ตั้งค่าด้วย `DoconutFarmBinding.EnsureBrowserId` (ดู เซสชัน & ความปลอดภัย).
`string`	`UserId`	`""`	เว็บฟาร์ม: ผู้ใช้ที่ลงชื่อเข้าใช้ที่ตั๋วผูกไว้, จาก `DoconutFarmBinding.ResolveUserId`.
`int`	`ImageResolution`	`0`	ล้าสมัย. ตั้ง `ImageResolution` ในการตั้งค่ารูปแบบแทน.
`bool`	`IsSecured`	`true`	จองไว้; ไม่บังคับใช้. การควบคุมการเข้าถึงคือ `DoconutOptions.UnsafeMode`.
`bool`	`IsWebFarm` / `string` `WebFarmPath`	`false` / `""`	เก็บไว้สำหรับโค้ดที่ย้ายมาจากแพ็กเกจคลาสสิก. พวกมันไม่ได้สลับโหมดฟาร์ม — `AddDoconutDistributed` ทำ.
`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
    });

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

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

การตัดสินใจใบอนุญาต

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

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

Annotations 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)`	โหลดซองที่เข้ารหัสที่ส่งกลับโดย `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)

ในแพ็กเกจนี้มันจะคืนค่า null เสมอ และคำขอเมตาดาต้าของวิดเจ็ตตอบกลับเป็น 501 Not Implemented: การอ่านแท็ก DICOM ไม่พร้อมใช้งานบน .NET Framework. การ เรนเดอร์ DICOM — หน้า, เฟรม, และแอนิเมชัน — ทำงานได้. ดู ปลั๊กอิน DICOM.

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

สร้างแท็ก <link> และ <script> สำหรับทรัพยากรที่โมดูลทรัพยากรให้บริการภายใต้ DoconutOptions.ResourcesPath ตามลำดับการพึ่งพา. ไฟล์สำหรับฟีเจอร์ที่ต้องใช้ใบอนุญาต (Search, Annotation) จะถูกสร้าง เฉพาะเมื่อใบอนุญาตอนุญาต.

text

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // license state, for guarding ribbon init code
bool IsAnnotationEnabled { get; }

แฟล็กของ CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (ต้องใช้การค้นหา), IncludeAnnotationCss (ต้องใช้การอธิบาย).

แฟล็กของ ScriptConfig: IncludeJQuery (จำเป็นสำหรับทั้งหมด), IncludeBootstrap, IncludeViewerScripts (สคริปต์หลักของผู้ชม), IncludeSearchScripts และ IncludeSearchBar (ต้องใช้การค้นหา), IncludeAnnotationScripts และ IncludeAnnotationBar (ต้องใช้การอธิบาย).

ทั้งสองคืนค่าเป็น HTML: เขียนด้วย @Html.Raw(...) ใน MVC 5 (สร้างในคอนโทรลเลอร์ — วิวไม่มี @inject) หรือ <%= %> ใน Web Forms. ดู เริ่มต้นอย่างเร็ว แสดงตัวอย่างทั้งสอง.

RenderViewer

text

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

คืนค่าเป็นบล็อก <script> ที่เริ่มต้นวิดเจ็ตบนองค์ประกอบที่มี id elementId และแสดงเอกสาร: docViewer({...}) ที่สร้างจาก ViewerConfig (ค่าเริ่มต้น: BasePath: '/', ResPath: 'doconut-res/images'), จากนั้นเรียก .View(token). เขียนหลังสคริปต์ของผู้ชม. สคริปต์ที่สร้างไม่มีการอ้างอิงถึงอ็อบเจ็กต์ผู้ชม, ดังนั้นหน้าที่มีแถบเครื่องมือของตนเองควรเริ่มต้นวิดเจ็ตด้วยตนเองแทน. ดู การกำหนดค่า Viewer.

ฟาร์มเว็บ

string? AccessToken เก็บตั๋วที่ลงนามซึ่งออกโดยการเปิดล่าสุดเมื่อโหมดกระจายเปิดใช้งานและ UnsafeMode เป็น false; มันเป็น null บนเซิร์ฟเวอร์เดียว. ส่งให้วิดเจ็ตพร้อมกับโทเคน: objViewer.View(token, access).