ตัวดู

คลาสตัวดูเอกสารหลัก

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

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

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

OpenDocumentAsync

เปิดเอกสารและส่งคืนโทเคนเซสชันที่วิดเจ็ตของไคลเอนต์ใช้สำหรับคำขอถัดไปทั้งหมด. การเปิดแต่ละครั้งเป็นแบบ 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)

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

GetPageCount

text
int GetPageCount(string token)

จำนวนหน้าทั้งหมดของเซสชันที่เปิดอยู่. จะทำให้เกิดข้อยกเว้น InvalidOperationException (Document session not found. Please re-open document.) หากโทเคนไม่รู้จักหรือหมดอายุ, และ ArgumentException สำหรับโทเคนว่าง.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

ขนาดหน้าที่เรนเดอร์โดยปริยายของเอกสารที่ซูม 100% — พื้นที่พิกัดสำหรับหมายเหตุที่สร้างในโค้ด. page ถูกยอมรับเพื่อความเข้ากันได้; ผลลัพธ์คือค่าปริยายของเอกสาร. จะทำให้เกิดข้อยกเว้น InvalidOperationException (Document session not found. Please re-open document.) หากโทเคนไม่รู้จักหรือหมดอายุ, และ ArgumentException สำหรับโทเคนว่าง.

รับชื่อแผ่นงาน

text
IReadOnlyList<string> GetWorksheetNames(string token)

ส่งคืนชื่อแผ่นงานของสเปรดชีตที่เปิดอยู่ตามลำดับของเวิร์กบุ๊ก หรือรายการว่างเมื่อเอกสารที่เปิดไม่ใช่สเปรดชีต

เฉพาะแผ่นงานที่ถูกเรนเดอร์เท่านั้นที่จะแสดงในรายการ: แผ่นงานที่ซ่อนและแผ่นงานที่ว่างจะถูกละเว้น และเมื่อ ExcelConfig.SheetNames จำกัดการเรนเดอร์ จะมีเฉพาะแผ่นงานเหล่านั้นเท่านั้นที่ปรากฏ แผ่นงานหนึ่งไม่จำเป็นต้องเป็นหนึ่งหน้า — แผ่นงานที่ใหญ่มากจะถูกเรนเดอร์ข้ามหลายหน้า จะทำการโยนข้อยกเว้น InvalidOperationException (Document session not found. Please re-open document.) หากโทเคนไม่รู้จักหรือหมดอายุ และ ArgumentException สำหรับโทเคนที่ว่างเปล่า

เพิ่มในเวอร์ชัน 26.9.0.

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

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

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

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

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

ประเภทคุณสมบัติค่าเริ่มต้นคำอธิบาย
stringPassword""รหัสผ่านสำหรับเอกสารที่ได้รับการปกป้อง (คัดลอกเข้าสู่การกำหนดค่ารูปแบบโดยอัตโนมัติ).
intImageResolution0ล้าสมัย. เก็บไว้เพื่อความเข้ากันได้เท่านั้น — ตั้งค่า ImageResolution ในการกำหนดค่ารูปแบบแทน.
stringWatermark""ข้อความลายน้ำที่กำหนดเองที่วาดบนหน้าที่เรนเดอร์ สตริงรูปแบบ: "^Text~Color~FontSize~FontName~Opacity~Angle", เช่น "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60การหมดอายุแบบเลื่อนของเซสชันเป็นนาที.
boolIsSecuredtrueไม่ได้บังคับใช้ในขณะนี้ — จองไว้ การผูกโทเคนถูกควบคุมโดยทั่วโลกโดย DoconutOptions.UnsafeMode (ดู Core Concepts → Sessions & Security).

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

ประเภทคุณสมบัติค่าเริ่มต้นคำอธิบาย
boolIsWebFarmfalseล้าสมัย — ไม่มีผล. เผยแพร่เอกสารด้วย DistributedDocumentPublisher.PublishAsync (หรือ IDistributedPublishQueue.EnqueueAsync) และตั้งค่า FileShareConfig.RootPath แทน โปรดสังเกตการใช้ตัวอักษร — ไลบรารีก่อนหน้านี้สะกดเป็น IsWebfarm.
stringWebFarmPath""ล้าสมัย — ไม่มีผล. ใช้ FileShareConfig.RootPath ตามที่อธิบายใน การปรับใช้แบบกระจาย. ก่อนหน้านี้สะกดเป็น WebfarmPath.
boolEditModefalseจองไว้สำหรับกระบวนการแก้ไขที่แจกจ่ายแยกต่างหาก; ปล่อยให้ 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 ^^การจัดวางแบบทุกมุมแบบเลือกได้ หากไม่มีจะใช้การวางลายน้ำปกติ.
TextConfidentialข้อความที่เรนเดอร์บนแต่ละหน้า ต้องไม่ว่างเปล่า.
ColorRedสีที่ระบุชื่อที่ชั้นวาดเข้าใจ.
FontSize24ขนาดฟอนต์; หากค่าตัวเลขไม่ถูกต้องจะใช้ค่าเริ่มต้นของเรนเดอร์.
FontNameVerdanaฟอนต์ที่ต้องการ ตรวจสอบว่าติดตั้งในสภาพแวดล้อมการปรับใช้แล้ว.
Opacity80ค่าบิตจาก 0 ถึง 255 ต้องแปลงสำเร็จ.
Angle-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(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 ต่อหน้า ที่ฝังคำอธิบายไว้

แต่ละรายการต้องรับโทเค็นของเซสชัน รูปแบบ 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 + ตัวดู + การค้นหา + คำอธิบาย
string ReferenceScripts(ScriptConfig? config = null)

CssConfig แฟล็ก: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (ที่เปิดใช้งานโดยการค้นหา), IncludeAnnotationCss (ที่เปิดใช้งานโดยคำอธิบาย)

ScriptConfig แฟล็ก: IncludeJQuery (จำเป็นสำหรับทั้งหมด), IncludeBootstrap, IncludeViewerScripts (แกนหลัก: docViewer.js + ตัวแบ่ง + ลิงก์), IncludeSearchScripts และ IncludeSearchBar (ที่เปิดใช้งานโดยการค้นหา), IncludeAnnotationScripts และ IncludeAnnotationBar (ที่เปิดใช้งานโดยคำอธิบาย), EmitFeatureFlags (ค่าเริ่มต้น true: ยังเขียนสคริปต์ inline window.Doconut.features = { search, annotation, editor }; ตั้งค่าเป็น false ภายใต้ Content‑Security‑Policy ที่บล็อกสคริปต์ inline)

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 ควรลบสำเนาเหล่านั้นออกเมื่อหน้าถูกเรนเดอร์จากแท็กที่สร้างขึ้น.

หน้านี้เป็นประโยชน์หรือไม่?