การทำหมายเหตุ
เพิ่มการสนับสนุนการทำหมายเหตุให้กับ Viewer
การทำหมายเหตุใน Doconut ทำงานในสองทิศทาง: ผู้ใช้วาดมันในวิดเจ็ตของเบราว์เซอร์และเซิร์ฟเวอร์เก็บไว้ต่อหน้า, หรือโค้ดของคุณสร้างมันและโหลดเข้าสู่เซสชันที่เปิดอยู่. ไม่ว่าจะอย่างไรก็ตามมันจะแสดงผลบนหน้าและสามารถฝังลงในไฟล์ PDF หรือ PNG ได้.
การสนับสนุนการทำหมายเหตุถูกจำกัดโดยความสามารถของใบอนุญาต Annotation (ได้รับโดยอัตโนมัติภายใต้ใบอนุญาต Temporary ที่ใช้งานอยู่).
เปิดใช้งาน UI การทำหมายเหตุ
การทำหมายเหตุเป็นโมดูลของ Viewer ไม่ใช่แถบเครื่องมือแบบแยกอิสระ. หน้าเว็บต้องรวมทรัพยากรของ Viewer, แถบเครื่องมือ Viewer, การเมานท์ Viewer, และ objViewer ที่ได้เริ่มต้นแล้ว; จากนั้น Ribbon การทำหมายเหตุจะถูกเมานท์และแนบกับอินสแตนซ์เดียวกัน.
ส่งออกไฟล์การทำหมายเหตุพร้อมกับไฟล์ Viewer. พวกมันถูกจำกัดโดยใบอนุญาต, ดังนั้นแท็กของพวกมันจะแสดงเฉพาะเมื่อความสามารถได้รับการมอบให้. ใน MVC 5, สร้างแท็กในคอนโทรลเลอร์ (view ไม่มี @inject):
public class ViewerController : Controller
{
public ActionResult Index()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
});
ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // ริบบิ้นหมายเหตุที่ฝังอยู่
});
ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
return View();
}
}เก็บส่วนประกอบ 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>ไฟล์การทำหมายเหตุสร้าง Ribbon ภายใน annBarMount; คุณไม่ต้องคัดลอกปุ่มหรือไดอะล็อกของมัน. เริ่มต้น docViewer ก่อน, จากนั้นสร้าง Ribbon เฉพาะเมื่อเซิร์ฟเวอร์ยืนยันว่าการทำหมายเหตุได้รับใบอนุญาต:
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
var annBar = null;
var currentToken = '';
var objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
onAnnLoaded: function () { if (annBar) annBar.handleAnnLoaded(); },
onAnnSaved: function () { if (annBar) annBar.handleAnnSaved(); },
onAnnSaveError: function () { if (annBar) annBar.handleAnnSaveError(); },
onAnnClosed: function () { if (annBar) annBar.handleAnnClosed(); },
onError: function (message) { console.error('Viewer error:', message); }
});
@if ((bool)ViewBag.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: function () { return { token: currentToken }; },
onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
});
annBar.attach(objViewer);
</text>
}
</script>หากไม่มีความสามารถ, ReferenceScripts จะละเว้นสคริปต์ของ Ribbon, ดังนั้น if ฝั่งเซิร์ฟเวอร์จะรักษาการเรียก doconutAnnotationBar(...) ที่ไม่มีการป้องกันไม่ให้ทำให้หน้าเสียหาย. ใน Web Forms, เขียนการป้องกันเดียวกันเป็น <% if (IsAnnotationEnabled) { %> … <% } %>.
การบันทึกจาก Ribbon จะโพสต์ข้อมูลไปยัง DocImage.axd (AnnSave), ซึ่งจะเก็บไว้ในเซสชันเอกสารต่อหน้า. การโหลด (AnnLoad) จะเกิดขึ้นโดยอัตโนมัติเมื่อหน้าที่มีการทำหมายเหตุแสดงผล.
เปิดและปิด Ribbon จากแถบเครื่องมือของคุณเองด้วย annBar.open() และ annBar.close(). API สาธารณะของมัน:
| วิธีการ | วัตถุประสงค์ |
|---|---|
attach(objViewer) | เชื่อมต่อ Ribbon กับ viewer ที่ได้เริ่มต้นแล้ว; ต้องทำครั้งเดียว |
open() / close() | เข้าหรือออกจากการแก้ไขการทำหมายเหตุ |
reset() | คืนค่า Ribbon ไปยังสถานะปิด, ไม่อยู่ในโหมดแก้ไข |
isOpen() / annotating() | อ่านสถานะของ Ribbon / สถานะการแก้ไขหมายเหตุของ viewer |
reopenEditable() | โหลดการทำหมายเหตุของหน้าปัจจุบันใหม่เป็นอ็อบเจ็กต์ที่สามารถแก้ไขได้ |
updateActionState() | รีเฟรชปุ่มบันทึกและลบหลังจากการเปลี่ยนแปลงของโฮสต์ |
headerSlot() | ช่องหัวเรื่องที่เป็นตัวเลือกสำหรับคอนโทรลที่เป็นของโฮสต์ |
onStatus, onToast, onLayout, onEditStart, และ onEditEnd เป็น callback ของโฮสต์ที่เป็นตัวเลือก. อ็อบเจ็กต์ endpoints ยังสามารถให้ exportPdf, exportPng, imageUpload, และ imageList; คอนโทรลที่ไม่มี endpoint ที่กำหนดจะถูกซ่อน.
สองประเภทของ callback, เชื่อมต่อสองวิธี
โค้ดการทำ annotation ใช้สองสไตล์ของ callback, และแต่ละแบบจะล้มเหลวโดยไม่มีการแจ้งเตือนเมื่อเชื่อมต่อในทางตรงกันข้าม:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedเป็น ตัวเลือก ของdocViewer({...}), เช่น callback ของ viewer ทุกตัว.Created,Changed,Deleted, และPropertiesเป็น ฟังก์ชันทั่วโลกที่ค้นหาตามชื่อ: โดยมีรหัส viewer นำหน้ากับเหตุการณ์. สำหรับ viewer ใน#div_ctlDocรหัสคือctlDoc, ดังนั้นฟังก์ชันคือctlDoc_Created,ctlDoc_Changed,ctlDoc_Deleted, และctlDoc_Properties. ฟังก์ชันที่สะกดผิดหรือเปลี่ยนชื่อจะไม่ถูกเรียกใช้เลย.
SaveAnnotations() ไม่ได้คืนค่าว่าบันทึกสำเร็จหรือไม่: ผลลัพธ์จะมาผ่าน onAnnSaved หรือ onAnnSaveError. โค้ดที่อ่านค่าที่คืนกลับจะไม่เคลียร์แฟล็ก "การเปลี่ยนแปลงที่ยังไม่ได้บันทึก".
สร้าง annotation ด้วย C#
รับ manager ที่ผูกกับเซสชันที่เปิดอยู่, เพิ่ม annotation, และโหลดพวกมัน (โดยใช้ using Doconut.Annotations; สำหรับประเภทและ using System.Drawing; สำหรับ Rectangle และ Color):
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<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));
// โหลดเข้าสู่เซสชัน - ตัวดูดึงข้อมูลเหล่านั้น, และเรนเดอร์ฝังลงใน
// การส่งออก image/PDF.
viewer.LoadAnnotationData(token, manager);
return new HttpStatusCodeResult(200);
}ประเภทของ 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 เชิงสัมพันธ์ จะถูกแก้ไขโดยอ้างอิงกับโฮสต์ของคำขอปัจจุบันเมื่อเพิ่ม annotation — ดูบันทึกการส่งออกด้านล่าง |
API ของ AnnotationManager
| สมาชิก | วัตถุประสงค์ |
|---|---|
Add(BaseAnnotation) | จัดคิว annotation |
GetAnnotations() / GetAnnotations(int page) | ตรวจสอบสิ่งที่ manager ถืออยู่ |
ClearAnnotations() / ClearAnnotations(int page) | ลบทั้งหมด / ต่อหน้า |
GetAnnotationData() / GetAnnotationData(int page) | ข้อมูล annotation ที่เข้ารหัส — ซองที่ widget ใช้ |
GetAnnotationXml() | รูปแบบ XML |
Viewer สะท้อนการโหลดและการอ่านต่อเซสชัน: LoadAnnotationData(token, manager) หรือ LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml), และ GetAnnotationXML(token).
ส่งออกพร้อม annotation ที่ฝังอยู่
// PDF ของทุกหน้าที่มีคำอธิบายถูกเรนเดอร์ลงบนหน้า
public async Task<ActionResult> ExportPdf(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
return File(pdf, "application/pdf", "export.pdf");
}
// หรือ ZIP ของ PNG แยกตามหน้า
public async Task<ActionResult> ExportPngZip(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
return File(zip, "application/zip", "annotations-png.zip");
}การส่งออกใช้เครื่องมือ burner เดียวกับการเรนเดอร์บนหน้าจอและใช้ใบอนุญาตและการตัดสินใจ watermark แบบกำหนดเองเดียวกัน.
คำอธิบายภาพบนโฮสต์อินทราเน็ตที่ส่งออกเป็น “Image blocked”
ผู้ดูและการส่งออกดึงภาพของ ImageAnnotation จากแหล่งที่ต่างกัน:
| พื้นผิว | ผู้ที่ดาวน์โหลดภาพ | บนโฮสต์อินทราเน็ตหรือการพัฒนา |
|---|---|---|
| ผู้ดูในเบราว์เซอร์ | เบราว์เซอร์ของผู้ใช้ | ภาพปรากฏ |
ExportAnnotationsToPdfAsync / …PngZipAsync | เซิร์ฟเวอร์ | ตัวแทนสีแดง "Image blocked" |
เมื่อเซิร์ฟเวอร์ดึงภาพเพื่อฝังลงในเอกสาร มันจะปฏิเสธที่อยู่ที่ชี้กลับไปยังเครือข่ายส่วนตัว: 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 ของภาพแบบ relative จะถูกแก้ไขโดยอิงกับโฮสต์ของคำขอปัจจุบัน ดังนั้นบน localhost, บนเซิร์ฟเวอร์อินทราเน็ต, หรือบนเว็บไซต์ใด ๆ ที่เข้าถึงผ่านที่อยู่ส่วนตัว ภาพจะแสดงในผู้ดูและการส่งออกจะมีตัวแทนแทนที่แทน นั่นคือการทำงานของการป้องกัน ไม่ใช่ความล้มเหลวในการเรนเดอร์ หากการส่งออกต้องมีภาพ ให้ให้บริการจากโฮสต์ที่มีที่อยู่สาธารณะและใช้ URL แบบ absolute ชื่อโฮสต์ที่ไม่สามารถแก้ไขได้จะถูกปฏิเสธในลักษณะเดียวกัน; ความล้มเหลวในการดาวน์โหลดอื่น ๆ จะวาด URL และข้อความแสดงข้อผิดพลาดเป็นสีแดงในตำแหน่งที่ภาพควรอยู่.
กระบวนการคงสภาพ
- เปิดเอกสารและรับโทเค็นของมัน.
- โหลด XML หรือข้อมูลที่เข้ารหัสที่เก็บไว้ก่อนหน้านี้เข้าสู่โทเค็นนั้น.
- ให้วิดเจ็ตอ่านและแก้ไขคำอธิบายของเซสชัน.
- ดึง XML ด้วย
GetAnnotationXML(token)เมื่อแอปพลิเคชันของคุณตัดสินใจบันทึก. - ส่งออกเป็น PDF หรือ PNG เมื่อจำเป็นต้องมีไฟล์ส่งมอบแบบแบน.
- ปิดเซสชันของเอกสาร.
ห้ามใช้โทเค็นของผู้ดูเป็นตัวระบุคำอธิบายถาวร — โทเค็นจะหมดอายุพร้อมกับเซสชัน, และการรีไซเคิลของพูลแอปพลิเคชันจะทำให้ทุกเซสชันบนเซิร์ฟเวอร์เดียวสิ้นสุด. ให้เก็บข้อมูลคำอธิบายไว้กับเอกสารและตัวระบุเวอร์ชันของคุณเอง.
หมายเหตุด้านความปลอดภัยและการเรนเดอร์
- คำขอคำอธิบายใช้การรักษาความปลอดภัยของเซสชันและโทเค็นเดียวกับคำขอหน้า.
- ตรวจสอบและควบคุม URL ของภาพที่ผู้ใช้ส่งมา.
- Payload แบบวาดมือขนาดใหญ่และการส่งออกความละเอียดสูงจะเพิ่มการใช้หน่วยความจำ; ทดสอบเอกสารที่เป็นจริงและค่าการซูม.
การแก้ไขปัญหา
| อาการ | ตรวจสอบ |
|---|---|
| Ribbon คำอธิบายหายไป | ความสามารถ Annotation และสี่แฟล็ก CSS/สคริปต์ของคำอธิบาย |
| การบันทึกรายงานข้อผิดพลาด | โทเค็นหรือการหมดอายุของเซสชัน, และ BasePath ของวิดเจ็ต |
ctlDoc_Created (หรือฟังก์ชันเหตุการณ์อื่น) ไม่เคยทำงาน | ชื่อฟังก์ชัน: viewer id + _ + event, เป็นฟังก์ชันระดับ global |
| คำอธิบาย C# ไม่ปรากฏ | หมายเลขหน้านับจาก 1, และข้อมูลถูกโหลดเข้าสู่โทเค็นที่ใช้งานอยู่ |
| คำอธิบายภาพแสดงบนหน้าจอแต่ไม่อยู่ในการส่งออก | โฮสต์ของภาพมีที่อยู่ส่วนตัวหรือ loopback — ดูด้านบน |
| เอกสารที่เปิดใหม่ไม่มีคำอธิบาย | บันทึก XML หรือข้อมูลนอกเซสชันผู้ดู, จากนั้นโหลดเข้าสู่โทเค็นใหม่ |
หน้านี้เป็นประโยชน์หรือไม่?