การทำหมายเหตุ

เพิ่มการสนับสนุนการทำหมายเหตุให้กับตัวดู

การทำหมายเหตุใน Doconut ทำงานในสองทิศทาง: ผู้ใช้วาดมันในวิดเจ็ตของเบราว์เซอร์และเซิร์ฟเวอร์บันทึกไว้ต่อหน้า, หรือโค้ดของคุณสร้างมันโดยโปรแกรมและโหลดเข้าเซสชันที่เปิดอยู่. ไม่ว่าจะอย่างไรก็ตาม มันจะแสดงผลบนหน้าและสามารถฝังลงในไฟล์ PDF/PNG ที่ส่งออกได้.

การสนับสนุนการทำหมายเหตุถูกจำกัดโดยความสามารถของใบอนุญาต Annotation (ได้รับโดยอัตโนมัติภายใต้ใบอนุญาต Temporary ที่ใช้งานอยู่).

เปิดใช้งาน UI การทำหมายเหตุ

การทำหมายเหตุเป็นโมดูลของ Viewer ไม่ใช่แถบเครื่องมือแยกส่วน หน้าเต็มต้องรวมทรัพยากร Viewer, แถบเครื่องมือ Viewer, การเมานท์ Viewer, และ objViewer ที่ได้เริ่มต้นแล้ว; จากนั้น Ribbon การทำหมายเหตุจะถูกเมานท์และแนบกับอินสแตนซ์เดียวกันนั้น.

ส่งออกชุดบันเดิลการทำหมายเหตุพร้อมกับบันเดิลของ Viewer — พวกมันถูกจำกัดโดยใบอนุญาต, ดังนั้นแท็กจะปรากฏเฉพาะเมื่อความสามารถพร้อมใช้งาน:

html
@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  // แถบคำอธิบายที่ฝังอยู่
}))

เก็บส่วนประกอบ Viewer ทั้งหมดให้มองเห็นในมาร์กอัป:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- การควบคุม Viewer, รวมถึงปุ่มที่เปิด Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

บันเดิลการทำหมายเหตุสร้าง DOM ของ Ribbon ภายใน annBarMount; คุณไม่จำเป็นต้องคัดลอกปุ่มหรือมาร์กอัปของไดอะล็อก. เริ่มต้น docViewer ก่อน, จากนั้นสร้าง Ribbon เฉพาะเมื่อเซิร์ฟเวอร์ยืนยันว่าการทำหมายเหตุได้รับใบอนุญาต:

html
<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: 'doconut',
        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 จะโพสต์ข้อมูลผ่านมิดเดิลแวร์ (AnnSave), ซึ่งเก็บไว้ในเซสชันเอกสารต่อหน้า. การโหลด (AnnLoad) เกิดขึ้นอัตโนมัติเมื่อหน้าที่มีการทำหมายเหตุแสดงผล. สี่ callback onAnn* ทำให้ Ribbon ซิงโครไนซ์กับวงจรชีวิตของ viewer.

เปิดและปิดมันจากแถบเครื่องมือ Viewer ที่เป็นของโฮสต์ใดก็ได้:

javascript
annBar.open();
annBar.close();

API สาธารณะของ Ribbon มีดังนี้:

วิธีการวัตถุประสงค์
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 ที่กำหนดจะยังคงซ่อนอยู่.

สำหรับลำดับการเริ่มต้นของ Viewer, Search, และ Annotation ที่รวมกัน, ดูที่ เริ่มต้นอย่างเร็ว.

บันเดิลการทำหมายเหตุเพิ่มเครื่องมือการเขียนในเบราว์เซอร์, แต่ข้อมูลยังคงเป็นของเซสชันเอกสารฝั่งเซิร์ฟเวอร์ที่ระบุด้วยโทเค็น. การเปิดแหล่งข้อมูลใหม่จะสร้างเซสชันใหม่; เก็บ XML หรือเอนเวลอปการทำหมายเหตุที่เข้ารหัสไว้ในแอปพลิเคชันของคุณหากการทำหมายเหตุต้องคงอยู่หลังจากช่วงเวลาเซสชันสิ้นสุด.

สองประเภทของ 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 โค้ดที่อ่านค่าที่คืนกลับจะไม่เคลียร์แฟล็ก “unsaved changes”

สร้าง annotation ด้วย C#

รับ manager ที่ผูกกับ session ที่เปิดอยู่, เพิ่ม annotation, และโหลดพวกมัน (โดยใช้ using Doconut.Annotations; สำหรับประเภทและ using System.Drawing; สำหรับ Rectangle/Color):

csharp
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 ฝังพวกมันลงใน image/PDF exports.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

ประเภทของ Annotation

ทุกประเภทอยู่ใน Doconut.Annotations และสืบทอดจาก BaseAnnotation (หมายเลขหน้า + bounding Rectangle):

TypeNotes
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; เซิร์ฟเวอร์จะดึงรูปภาพเฉพาะในช่วงการบันทึก — ดูหมายเหตุการส่งออกด้านล่าง

API ของ AnnotationManager

MemberPurpose
Add(BaseAnnotation)คิว annotation
GetAnnotations() / GetAnnotations(int page)ตรวจสอบสิ่งที่ manager เก็บไว้
ClearAnnotations() / ClearAnnotations(int page)ลบทั้งหมด / ตามหน้า
GetAnnotationData() / GetAnnotationData(int page)สตริงข้อมูล annotation ที่เข้ารหัส — ซอง Base64 (สิ่งที่ widget ใช้)
GetAnnotationXml()รูปแบบ XML

Viewer สะท้อนการโหลด/อ่านต่อ session: LoadAnnotationData(token, manager) หรือ LoadAnnotationData(token, encodedData) (ซอง Base64 จาก GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token)

ส่งออกพร้อม annotation ที่ฝังไว้

csharp
// 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 รูปภาพที่อธิบายในต่อไป

การใส่คำอธิบายภาพบนโฮสต์อินทราเน็ตส่งออกเป็น "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 และข้อความแสดงข้อผิดพลาดเป็นสีแดงในตำแหน่งที่ภาพควรอยู่.

กระบวนการคงสภาพ

  1. เปิดเอกสารและรับโทเค็นของมัน.
  2. โหลด XML หรือข้อมูลที่เข้ารหัสที่เก็บไว้ก่อนหน้านี้เข้าสู่โทเค็นนั้น.
  3. ให้วิดเจ็ตอ่านและแก้ไขคำอธิบายการเซสชัน.
  4. ดึง XML ด้วย GetAnnotationXML(token) เมื่อแอปพลิเคชันของคุณตัดสินใจบันทึก.
  5. ส่งออก PDF/PNG เมื่อจำเป็นต้องมีไฟล์ส่งมอบที่แบน.
  6. ปิดเซสชันเอกสาร.

ห้ามใช้โทเค็นตัวดูที่ไม่โปร่งใสเป็นตัวระบุคำอธิบายถาวร. ให้เชื่อมโยงข้อมูลคำอธิบายที่บันทึกไว้กับเอกสารและตัวระบุเวอร์ชันของคุณเอง.

หมายเหตุด้านความปลอดภัยและการเรนเดอร์

  • คำขอคำอธิบายใช้ความปลอดภัยของเซสชัน/โทเค็นเดียวกับคำขอหน้า.
  • ตรวจสอบและควบคุม URL ของภาพที่ผู้ใช้ส่งมาเพื่อหลีกเลี่ยงการปลอมแปลงคำขอฝั่งเซิร์ฟเวอร์.
  • การส่งออกใช้การตัดสินใจเรื่องลิขสิทธิ์/ลายน้ำแบบกำหนดเองเช่นเดียวกับการเรนเดอร์หน้าบนหน้าจอ.
  • ภาระงานฟรีแฮนด์ขนาดใหญ่และการส่งออกความละเอียดสูงจะเพิ่มการใช้หน่วยความจำ; ทดสอบเอกสารและค่าซูมที่เป็นจริง.

การแก้ไขปัญหา

อาการตรวจสอบ
ริบบิ้นคำอธิบายหายความสามารถของ Annotation และสี่แฟล็ก CSS/สคริปต์ของคำอธิบาย
คอลแบ็คบันทึกรายงานข้อผิดพลาดการหมดอายุของโทเค็น/เซสชันและมิดเดิลแวร์ BasePath
ctlDoc_Created (หรือฟังก์ชันเหตุการณ์อื่น) ไม่ทำงานชื่อฟังก์ชัน: viewer id + _ + event, เป็นฟังก์ชันระดับ global
คำอธิบาย C# ไม่ปรากฏการนับหน้าเป็นแบบหนึ่งฐานและข้อมูลถูกโหลดเข้าสู่โทเค็นที่ใช้งานอยู่
คำอธิบายภาพปรากฏบนหน้าจอแต่ไม่อยู่ในการส่งออกโฮสต์ของภาพมีที่อยู่ส่วนตัวหรือ loopback — ดูด้านบน
เอกสารที่เปิดใหม่ไม่มีคำอธิบายบันทึก XML/ข้อมูลนอกเซสชันตัวดู, จากนั้นโหลดเข้าสู่โทเค็นใหม่

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