คำอธิบายประกอบ
เพิ่มการสนับสนุนการอธิบายประกอบให้กับ Viewer
การอธิบายประกอบใน Doconut ทำงานในสองทิศทาง: ผู้ใช้วาดบนวิดเจ็ตในเบราว์เซอร์และเซิร์ฟเวอร์บันทึกไว้ต่อหน้า, หรือโค้ดของคุณสร้างขึ้นโดยโปรแกรมและโหลดเข้าสู่เซสชันที่เปิดอยู่ ไม่ว่ากรณีใดก็ตาม พวกมันจะแสดงบนหน้าและสามารถฝังลงในไฟล์ PDF/PNG ที่ส่งออกได้
การสนับสนุนการอธิบายประกอบถูกจำกัดโดยความสามารถของใบอนุญาต Annotation (มอบให้โดยอัตโนมัติภายใต้ใบอนุญาต Temporary ที่ใช้งานอยู่)
เปิดใช้งาน UI ของการอธิบายประกอบ
การอธิบายประกอบเป็นโมดูลของ Viewer ไม่ใช่แถบเครื่องมือแบบสแตนด์อโลน หน้าเต็มต้องรวม
ทรัพยากร Viewer, แถบเครื่องมือ Viewer, การเมานท์ Viewer, และ objViewer ที่ได้เริ่มต้นแล้ว; จากนั้น
Ribbon ของการอธิบายประกอบจะถูกเมานท์และเชื่อมต่อกับอินสแตนซ์เดียวกันนั้น
ปล่อย bundle ของการอธิบายประกอบพร้อมกับ bundle ของ viewer — พวกมันถูกจำกัดด้วยใบอนุญาต, ดังนั้นแท็กจะปรากฏก็ต่อเมื่อความสามารถพร้อมใช้งาน:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // ริบบิ้น annotation ที่ฝังอยู่
}))ทำให้การประกอบ Viewer ทั้งหมดมองเห็นได้ใน markup:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- การควบคุม Viewer, รวมถึงปุ่มที่เปิด Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Bundle ของการอธิบายประกอบสร้าง DOM ของ Ribbon ภายใน annBarMount; คุณไม่จำเป็นต้อง
คัดลอกปุ่มหรือ markup ของไดอะล็อก เริ่มต้น docViewer ก่อน, แล้วสร้าง Ribbon
เฉพาะเมื่อเซิร์ฟเวอร์ยืนยันว่าการอธิบายประกอบได้รับใบอนุญาต:
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: (message) => console.error('Viewer error:', message)
});
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token: currentToken }),
onStatus: (message) => console.log(message),
onToast: (message, type) => console.log(type, message),
onLayout: () => requestAnimationFrame(() => objViewer.Refit())
});
annBar.attach(objViewer);
</text>
}
</script>หากไม่มีความสามารถ, ReferenceScripts จะละเว้นสคริปต์ของ Ribbon, ทำให้ if ด้านเซิร์ฟเวอร์คงไว้ซึ่งการเรียก doconutAnnotationBar(...) ที่ไม่มีการป้องกันจากการทำให้หน้าเสียหาย
การบันทึกจาก Ribbon จะโพสต์ข้อมูลผ่าน middleware (AnnSave), ซึ่งเก็บไว้ใน
เซสชันเอกสารต่อหน้า การโหลด (AnnLoad) จะเกิดขึ้นโดยอัตโนมัติเมื่อหน้าที่มี
การอธิบายประกอบแสดงผล callbacks สี่ตัว onAnn* จะทำให้ Ribbon ซิงโครไนซ์กับ
วงจรชีวิตของ viewer
เปิดและปิด Ribbon จากแถบเครื่องมือ Viewer ที่เป็นของโฮสต์ใดก็ได้:
annBar.open();
annBar.close();API สาธารณะของ Ribbon มีดังนี้:
| Method | Purpose |
|---|---|
attach(objViewer) | เชื่อมต่อ Ribbon กับ viewer ที่ได้เริ่มต้นแล้ว; จำเป็นต้องทำครั้งเดียว |
open() / close() | เริ่มหรือหยุดการแก้ไขการอธิบายประกอบ |
reset() | คืนค่า Ribbon ให้เป็นสถานะปิดและไม่อยู่ในโหมดแก้ไข |
isOpen() / annotating() | อ่านสถานะของ Ribbon / สถานะการแก้ไขการอธิบายประกอบของ viewer |
reopenEditable() | โหลดการอธิบายประกอบของหน้าปัจจุบันใหม่เป็นวัตถุที่สามารถแก้ไขได้ |
updateActionState() | รีเฟรชความพร้อมของการควบคุมบันทึก/ลบ หลังจากที่โฮสต์มีการเปลี่ยนแปลง |
headerSlot() | รับช่องส่วนขยายหัวเรื่องแบบเลือกสำหรับการควบคุมที่เป็นของโฮสต์ |
onStatus, onToast, onLayout, onEditStart, และ onEditEnd เป็น callbacks ของโฮสต์ที่เป็นตัวเลือกได้. วัตถุ endpoints สามารถให้บริการเพิ่มเติมได้แก่ exportPdf, exportPng, imageUpload, และ imageList; ควบคุมที่ไม่มี endpoint ที่กำหนดไว้จะถูกซ่อน
สำหรับลำดับการเริ่มต้นของ Viewer, Search, และ Annotation ที่รวมกัน, ดูที่ เริ่มต้นอย่างเร็ว.
Bundle ของการอธิบายประกอบเพิ่มเครื่องมือการเขียนในเบราว์เซอร์, แต่ข้อมูลยังคงเป็นของเซสชันเอกสารด้านเซิร์ฟเวอร์ที่ระบุด้วยโทเค็น การเปิดแหล่งข้อมูลใหม่จะสร้างเซสชันใหม่; ให้บันทึก XML หรือ envelope ของการอธิบายประกอบที่เข้ารหัสไว้ในแอปพลิเคชันของคุณหากต้องการให้การอธิบายประกอบคงอยู่หลังจากอายุการใช้งานของเซสชันสิ้นสุด.
สองประเภทของ callback, เชื่อมต่อสองวิธี
โค้ดการทำ annotation ใช้สองรูปแบบของ callback, และแต่ละแบบจะล้มเหลวอย่างเงียบเมื่อเชื่อมต่อในทางตรงกันข้าม:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedเป็น ตัวเลือก ของdocViewer({...}), เช่นเดียวกับ callback ของ viewer ทุกตัว.Created,Changed,Deleted, และPropertiesเป็น ฟังก์ชันระดับ global ที่ค้นพบโดยชื่อ: โดยมีไอดีของ viewer นำหน้ากับเหตุการณ์. สำหรับ viewer ใน#div_ctlDocไอดีคือctlDoc, ดังนั้นฟังก์ชันคือctlDoc_Created,ctlDoc_Changed,ctlDoc_Deleted, และctlDoc_Properties. ฟังก์ชันที่สะกดผิดหรือเปลี่ยนชื่อจะไม่ถูกเรียกใช้เลย.
SaveAnnotations() ไม่ได้คืนค่าว่าบันทึกสำเร็จหรือไม่: ผลลัพธ์จะมาผ่าน onAnnSaved หรือ onAnnSaveError. โค้ดที่อ่านค่าที่คืนกลับจะไม่มีการเคลียร์แฟล็ก "unsaved changes" flag.
สร้าง annotation ด้วย C#
รับ manager ที่ผูกกับเซสชันที่เปิดอยู่, เพิ่ม annotation, และโหลดพวกมัน (โดยใช้ using Doconut.Annotations; สำหรับประเภทและ using System.Drawing; สำหรับ Rectangle/Color):
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
// ผูกกับขนาดหน้าของเซสชันที่เปิดอยู่
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// หนึ่งตราประทับต่อหน้า
for (int page = 1; page <= pageCount; page++)
{
manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
$"PAGE {page}", 28, 4, Color.Maroon)
{
Opacity = 60,
Rotate = -8
});
}
manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
"Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));
// โหลดเข้าสู่เซสชัน — วิดเจ็ตดึงข้อมูลเหล่านี้ผ่าน AnnLoad และ
// renderer ทำให้พวกมันกลายเป็นการส่งออกเป็นภาพ/PDF.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});ประเภทของ Annotation
ทุกประเภทอยู่ใน Doconut.Annotations และสืบทอดจาก BaseAnnotation (หมายเลขหน้า + bounding Rectangle):
| ประเภท | หมายเหตุ |
|---|---|
StampAnnotation | สติ๊กเกอร์ข้อความที่มีขนาดฟอนต์, เส้นขอบ, สี; รองรับ Opacity, Rotate |
NoteAnnotation | โน้ตแบบสติ๊กกี้ที่มีข้อความ, สีพื้นหลัง, ขนาดฟอนต์, TitleColor |
RectangleAnnotation | สีเส้นขอบ + สีเติม, Title/ShowTitle |
CircleAnnotation | เส้นขอบ + เติม, ShowBorder |
EllipseAnnotation | เส้นขอบ + เติม, ShowBorder |
TriangleAnnotation | สีเส้นขอบ, BackColor, ShowBorder |
LineAnnotation | เส้นตรงที่มีความกว้างและสี |
ArrowAnnotation | เส้นที่มีหัวศร; สามารถตั้งค่า Direction (ประเภท ArrowDirection, จุดทิศ, ค่าเริ่มต้น E) |
FreehandAnnotation | เส้นวาดอิสระจากจุดที่เข้ารหัส FreehandData |
ImageAnnotation | รูปภาพจาก URL. URL relative จะถูกแก้ไขตามโฮสต์ของคำขอเมื่อเพิ่ม annotation; เซิร์ฟเวอร์จะดึงรูปภาพเฉพาะในขณะ burn — ดูหมายเหตุการส่งออกด้านล่าง |
API ของ AnnotationManager
| สมาชิก | วัตถุประสงค์ |
|---|---|
Add(BaseAnnotation) | คิวการสร้าง annotation |
GetAnnotations() / GetAnnotations(int page) | ตรวจสอบสิ่งที่ manager ถืออยู่ |
ClearAnnotations() / ClearAnnotations(int page) | ลบทั้งหมด / ต่อหน้า |
GetAnnotationData() / GetAnnotationData(int page) | สตริงข้อมูล annotation ที่เข้ารหัส — ซอง Base64 (สิ่งที่ widget ใช้) |
GetAnnotationXml() | รูปแบบ XML |
Viewer สะท้อนการโหลด/อ่านต่อกับเซสชัน: LoadAnnotationData(token, manager) หรือ LoadAnnotationData(token, encodedData) (ซอง Base64 จาก GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).
ส่งออกพร้อม annotation ที่ถูก burn เข้าไป
// PDF ของทุกหน้าที่มีคำอธิบายประกอบถูกเรนเดอร์ลงบนหน้า
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
return Results.File(pdf, "application/pdf", "export.pdf");
});
// หรือ ZIP ของ PNG ต่อหน้า
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
return Results.File(zip, "application/zip", "annotations-png.zip");
});การส่งออกใช้เครื่องบันทึกเดียวกับการเรนเดอร์บนหน้าจอ, ดังนั้นสิ่งที่ผู้ใช้เห็นคือสิ่งที่ไฟล์มี — ยกเว้น annotation ของรูปภาพ, ซึ่งอธิบายในต่อไป.
การทำเครื่องหมายภาพบนโฮสต์อินทราเน็ตส่งออกเป็น "ภาพถูกบล็อก"
ตัวดูและการส่งออกดึงภาพของ ImageAnnotation จากแหล่งที่ต่างกัน:
| พื้นผิว | ผู้ที่ดาวน์โหลดภาพ | บนโฮสต์อินทราเน็ตหรือการพัฒนา |
|---|---|---|
| ตัวดูในเบราว์เซอร์ | เบราว์เซอร์ของผู้ใช้ | ภาพปรากฏ |
ExportAnnotationsToPdfAsync / …PngZipAsync | เซิร์ฟเวอร์ | ตัวแทนที่เป็นสีแดง "ภาพถูกบล็อก" |
เมื่อเซิร์ฟเวอร์ดึงภาพเพื่อฝังลงในเอกสาร มันจะปฏิเสธที่อยู่ที่ชี้กลับไปยังเครือข่ายส่วนตัว: loopback (localhost, 127.0.0.1), 0.0.0.0, link‑local (169.254.x.x), ช่วงที่เป็นส่วนตัว 10.x, 172.16–31.x, และ 192.168.x, carrier‑grade NAT (100.64.0.0/10), และที่อยู่ IPv6 link‑local และ unique‑local การทำเช่นนี้ปกป้องเซิร์ฟเวอร์จากการถูกใช้เพื่อเข้าถึงระบบภายในผ่าน URL ของภาพที่จัดทำขึ้น และไม่มีสวิตช์ใดที่สามารถปิดการทำงานนี้ได้
URL ของภาพแบบสัมพันธ์จะถูกแก้ไขโดยอ้างอิงกับโฮสต์ของคำขอปัจจุบัน ดังนั้นบน localhost, บนเซิร์ฟเวอร์อินทราเน็ต, หรือบนไซต์ใด ๆ ที่เข้าถึงผ่านที่อยู่ส่วนตัว ภาพจะแสดงในตัวดูและการส่งออกจะมีตัวแทนที่แทนที่ นั่นคือการทำงานของการป้องกัน ไม่ใช่ความล้มเหลวในการเรนเดอร์ หากการส่งออกต้องมีภาพ ให้ให้บริการจากโฮสต์ที่มีที่อยู่สาธารณะและใช้ URL แบบสมบูรณ์ ชื่อโฮสต์ที่ไม่สามารถแก้ไขได้จะถูกปฏิเสธในลักษณะเดียวกัน; ความล้มเหลวในการดาวน์โหลดอื่น ๆ จะวาด URL และข้อความแสดงข้อผิดพลาดเป็นสีแดงในตำแหน่งที่ภาพควรอยู่
ขั้นตอนการคงข้อมูล
- เปิดเอกสารและรับโทเค็นของมัน.
- โหลด XML หรือข้อมูลที่เข้ารหัสที่เก็บไว้ก่อนหน้านี้เข้าไปในโทเค็นนั้น.
- ให้วิดเจ็ตอ่านและแก้ไขการทำเครื่องหมายของเซสชัน.
- ดึง XML ด้วย
GetAnnotationXML(token)เมื่อแอปพลิเคชันของคุณตัดสินใจบันทึก. - ส่งออกเป็น PDF/PNG เมื่อจำเป็นต้องมีไฟล์ที่แบน.
- ปิดเซสชันของเอกสาร.
อย่าใช้โทเค็นตัวดูที่ไม่โปร่งใสเป็นตัวระบุการทำเครื่องหมายถาวร ให้เชื่อมโยงข้อมูลการทำเครื่องหมายที่บันทึกไว้กับเอกสารและตัวระบุเวอร์ชันของคุณเอง.
หมายเหตุด้านความปลอดภัยและการเรนเดอร์
- คำขอการทำเครื่องหมายใช้ความปลอดภัยของเซสชัน/โทเค็นเดียวกับคำขอหน้า.
- ตรวจสอบและควบคุม URL ของภาพที่ผู้ใช้ส่งเข้ามาเพื่อหลีกเลี่ยงการปลอมแปลงคำขอจากฝั่งเซิร์ฟเวอร์.
- การส่งออกใช้การตัดสินใจเกี่ยวกับลิขสิทธิ์/ลายน้ำแบบกำหนดเองเช่นเดียวกับการเรนเดอร์หน้าบนหน้าจอ.
- โหลดข้อมูลแบบวาดมือขนาดใหญ่และการส่งออกความละเอียดสูงจะเพิ่มการใช้หน่วยความจำ; ทดสอบเอกสารและค่าซูมที่เป็นจริง.
การแก้ไขปัญหา
| อาการ | ตรวจสอบ |
|---|---|
| ริบบอนการทำเครื่องหมายหายไป | Annotation ความสามารถและสี่แฟล็ก CSS/สคริปต์การทำเครื่องหมาย |
| คอลแบ็กการบันทึกรายงานข้อผิดพลาด | การหมดอายุของโทเค็น/เซสชันและมิดเดิลแวร์ BasePath |
ctlDoc_Created (หรือฟังก์ชันเหตุการณ์อื่น) ไม่ทำงาน | ชื่อฟังก์ชัน: รหัสตัวดู + _ + เหตุการณ์, เป็นฟังก์ชันระดับทั่วโลก |
| การทำเครื่องหมาย C# ไม่ปรากฏ | การนับหน้าเริ่มจาก 1 และข้อมูลถูกโหลดเข้าสู่โทเค็นที่ใช้งานอยู่ |
| การทำเครื่องหมายภาพปรากฏบนหน้าจอแต่ไม่อยู่ในการส่งออก | โฮสต์ของภาพมีที่อยู่ส่วนตัวหรือ loopback — ดูด้านบน |
| เอกสารที่เปิดใหม่ไม่มีการทำเครื่องหมาย | บันทึก XML/ข้อมูลนอกเซสชันตัวดู แล้วโหลดเข้าสู่โทเค็นใหม่ |
หน้านี้เป็นประโยชน์หรือไม่?