Viewer
คลาสตัวดูเอกสารหลัก
Viewer (namespace Doconut) คือจุดเข้าถึงสาธารณะสำหรับการเปิดเอกสารจากคอนโทรลเลอร์ MVC, หน้า Web Forms, และตัวจัดการต่าง ๆ มันเป็นบริการ transient ที่ประกอบด้วย DoconutHost.Initialize; ให้ resolve ที่ที่คุณใช้มัน:
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() ทำงานได้เช่นกันเมื่อ DoconutHost.Initialize ทำงานแล้ว — มัน resolve บริการเดียวกัน — ซึ่งทำให้โค้ดที่ย้ายมาจากแพ็กเกจคลาสสิกยังคงคอมไพล์ได้ ก่อน Initialize, มันจะโยน InvalidOperationException.
Viewer ไม่เก็บสถานะเอกสารต่อคำขอและโดยเจตนา ไม่ implements IDisposable: เซสชันเอกสารทำงานอย่างอิสระจากมัน, ดังนั้นการทำลาย Viewer จะไม่สามารถปิดเอกสารที่เปิดอยู่ได้ (ดู วิธีการทำงานของ Viewer).
OpenDocumentAsync (เปิดเอกสารแบบอะซิงโครนัส)
เปิดเอกสารและคืนค่าโทเค็นเซสชันที่วิดเจ็ตใช้สำหรับทุกคำขอถัดไป เมื่อ UnsafeMode เป็น false (ค่าเริ่มต้น), โทเค็นจะถูกมอบให้กับเซสชัน ASP.NET ของคำขอปัจจุบัน — เรียกจากคำขอที่มีสถานะเซสชัน (ดู เซสชัน & ความปลอดภัย).
| การโหลดทับ | ใช้เมื่อ |
|---|---|
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 });
// จากการอัปโหลด (HttpPostedFileBase ใน MVC; HttpPostedFile ใน 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 (แบบซิงโครนัส)
สำหรับโค้ดเบื้องหลังของ Web Forms และโค้ดอื่นที่ไม่ได้ใช้หน้าแบบอะซิงโครนัส:
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)แต่ละอันจะคืนค่าโทเค็นและยังเก็บไว้ใน viewer.Token. fileName ต้องมีส่วนขยายที่ถูกต้อง. ตัวหุ้มเหล่านี้ปลอดภัยต่อการเรียกจากหน้า Web Forms: เส้นทางการเปิดจะไม่กลับมาทำงานบนบริบทของคำขอ ASP.NET, ดังนั้นการรอคอยจึงไม่สามารถทำให้เกิด deadlock. สิ่งเดียวกัน ไม่ เป็นจริงสำหรับทุก API ของ Doconut แบบอะซิงโครนัส — ดูส่วน Web Forms ของ ปลั๊กอินแปลงไฟล์.
CloseDocument
void CloseDocument(string token)ลบเซสชัน (ปล่อยเอนจินเอกสารโดยทันที), ลบการให้สิทธิ์ของโทเค็นจากเซสชัน ASP.NET ของคำขอปัจจุบัน, และเพิกถอนโทเค็น. ตัวเลือก — การหมดอายุแบบเลื่อนทำการทำความสะอาดเดียวกัน — แต่แนะนำสำหรับเอกสารขนาดใหญ่.
การสืบค้นเซสชัน
| Member | Returns |
|---|---|
int GetPageCount(string token) | จำนวนหน้าทั้งหมดของเอกสารที่เปิดอยู่ |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | ขนาดหน้าที่แสดงผลเริ่มต้นที่การซูม 100% — พื้นที่พิกัดสำหรับคำอธิบายที่สร้างในโค้ด |
IReadOnlyList<string> GetWorksheetNames(string token) | แผ่นงานที่แสดงผลของสเปรดชีตตามลำดับในเวิร์กบุ๊ก; ว่างสำหรับเอกสารอื่น |
แต่ละรายการจะโยน InvalidOperationException (Document session not found. Please re-open document.) หากโทเค็นไม่รู้จักหรือหมดอายุ, และ ArgumentException สำหรับโทเค็นที่ว่างเปล่า.
ตัวเลือกเอกสาร
ตัวเลือกที่ไม่ขึ้นกับรูปแบบต่อการเปิดแต่ละครั้ง (namespace Doconut):
| Type | Property | Default | Description |
|---|---|---|---|
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~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Field | Example | Meaning |
|---|---|---|
Leading ^ | ^ | การจัดวางที่มุมทั้งหมดแบบเลือกได้. หากไม่มี, จะใช้การวางตำแหน่งปกติ. |
| Text | Confidential | ข้อความที่วาดบนแต่ละหน้า. ต้องไม่ว่างเปล่า. |
| Color | Red | สีที่มีชื่อ. |
| FontSize | 24 | ขนาดฟอนต์; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้น. |
| FontName | Verdana | ชื่อฟอนต์. ตระกูลฟอนต์. ต้องติดตั้งบนเซิร์ฟเวอร์ — Windows Server มีฟอนต์น้อยกว่าคอมพิวเตอร์เดสก์ท็อป. |
| Opacity | 80 | 0 ถึง 255. ต้องสามารถแปลงได้. |
| Angle | -45 | การหมุนเป็นองศา; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้น. |
ตัวแยกวิเคราะห์คาดหวังฟิลด์หกฟิลด์อย่างแม่นยำหลังจาก ^ ที่เป็นตัวเลือก. คำจำกัดความที่ไม่ถูกต้องจะถูกแทนที่ด้วยข้อความ Invalid Watermark ที่มองเห็นได้แทนที่จะหายไปโดยเงียบ.
การตัดสินใจเรื่องใบอนุญาต
| License state | Custom value supplied | Rendered result |
|---|---|---|
| ใบอนุญาตผู้ชมแบบชำระเงินที่ถูกต้อง | No | Clean page |
| ใบอนุญาตผู้ชมแบบชำระเงินที่ถูกต้อง | Yes | Custom watermark |
| ใบอนุญาตชั่วคราว/สาธิตที่ใช้งานอยู่ | No | Clean page |
| ใบอนุญาตชั่วคราว/สาธิตที่ใช้งานอยู่ | Yes | Custom watermark |
| ใบอนุญาตที่หายไป, ถูกปฏิเสธ, หมดอายุ, เวอร์ชันไม่ตรง, หรือโดเมนไม่ถูกต้อง | Either | Evaluation watermark; the custom value does not replace it |
การตัดสินใจเดียวกันนี้ใช้กับหน้าที่ให้บริการและการส่งออกคำอธิบาย. ลายน้ำที่กำหนดเองเป็นคุณลักษณะของแอปพลิเคชันที่มีใบอนุญาต, ไม่ใช่วิธีการแทนที่ลายน้ำการประเมิน.
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(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)บนแพคเกจนี้จะคืนค่าเสมอ null และคำขอเมตาดาต้าของวิดเจ็ตตอบกลับ 501 Not Implemented: การอ่านแท็ก DICOM ไม่พร้อมใช้งานบน .NET Framework. DICOM rendering — หน้า, เฟรม, และแอนิเมชัน — ทำงานได้. ดู ปลั๊กอิน DICOM.
ตัวช่วยทรัพยากร — ReferenceCss / ReferenceScripts
สร้างแท็ก <link> และ <script> สำหรับทรัพยากรที่โมดูลทรัพยากรให้บริการภายใต้ DoconutOptions.ResourcesPath ตามลำดับการพึ่งพา ไฟล์สำหรับฟีเจอร์ที่ต้องมีใบอนุญาต (Search, Annotation) จะถูกสร้าง เฉพาะเมื่อใบอนุญาตอนุญาตให้.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // สถานะใบอนุญาต, เพื่อป้องกันรหัสการเริ่มต้น ribbon
bool IsAnnotationEnabled { get; }CssConfig แฟล็ก: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).
ScriptConfig แฟล็ก: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (the core viewer scripts), IncludeSearchScripts and IncludeSearchBar (search-gated), IncludeAnnotationScripts and IncludeAnnotationBar (annotation-gated), EmitFeatureFlags (default true: also writes an inline window.Doconut.features = { search, annotation, editor } script; set it to false under a Content-Security-Policy that blocks inline script).
Both return HTML: write them with @Html.Raw(...) in MVC 5 (produce them in the controller — views have no @inject) or <%= %> in Web Forms. ดู เริ่มต้นอย่างเร็ว แสดงตัวอย่างทั้งสอง.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)คืนค่าเป็นบล็อก <script> ที่เริ่มต้นวิดเจ็ตบนองค์ประกอบที่มี id elementId และแสดงเอกสาร: docViewer({...}) สร้างจาก ViewerConfig (ค่าเริ่มต้น: BasePath: '/', ResPath: 'doconut-res/images'), จากนั้น .View(token). เขียนหลังสคริปต์ของตัวดู. สคริปต์ที่สร้างไม่มีการอ้างอิงถึงอ็อบเจ็กต์ของตัวดู, ดังนั้นหน้าที่มีแถบเครื่องมือของตนเองควรเริ่มต้นวิดเจ็ตด้วยตนเองแทน. ดู ViewerConfig.
ฟาร์มเว็บ
string? AccessToken เก็บตั๋วที่ลงนามซึ่งออกโดยการเปิดล่าสุดเมื่อโหมดกระจายเปิดใช้งานและ UnsafeMode เป็น false; มันเป็น null บนเซิร์ฟเวอร์เดียว. ส่งไปยังวิดเจ็ตพร้อมโทเคน: objViewer.View(token, accessToken).
หน้านี้เป็นประโยชน์หรือไม่?