GroupDocs.Annotation เป็นแบบไม่ขึ้นกับ UI. มันอ่านและเขียนมาร์กอัปภายในเอกสารและไม่วาดอะไรบนหน้าจอ. สำหรับไลบรารีเซิร์ฟเวอร์ นี่คือการแยกที่เหมาะสม — และมันทำให้เกิดคำถามหนึ่งสำหรับทุกคนที่นำไปใช้: คนจะวาดการอธิบายจริง ๆ อย่างไร?

คำตอบทั่วไปมักจะหนัก: ฝังตัวดูเอกสารเชิงพาณิชย์, หรือใช้ตัวอย่าง Angular แล้วพยายามขยายต่อ. มีวิธีที่เบากว่า ภาพหน้า, แคนวาส, และหก endpoint — ไม่มีคอมโพเนนต์ตัวดู, ไม่มีเฟรมเวิร์กฝั่งหน้า, ไม่มีขั้นตอนการสร้าง, ไม่มี CDN. มันยังทำงานโดยไม่มีการเข้าถึงเครือข่ายออกเลย, ซึ่งสำคัญมากกว่าที่เคยเป็น.

ตัวอย่างอยู่บน GitHub:
browser-annotation-ui-net — dotnet run แล้วลากกล่องบนหน้า.

แนวคิดในหนึ่งย่อหน้า

เรนเดอร์แต่ละหน้าหนึ่งครั้งเป็น PNG โดยไม่มี annotation แล้วแคชไว้. ส่งรายการ annotation ไปยังเบราว์เซอร์เป็นข้อมูล. แคนวาสวาดมาร์กอัปบนภาพ. การเพิ่มคอมเมนต์จึงเป็นการเขียนเล็ก ๆ ไปยังเอกสารพร้อมรีโหลดรายการ — ไม่ใช่การเรนเดอร์หน้าใหม่ — และมาร์กอัปยังคงสามารถเลือก, คลิก, และตอบกลับได้ แทนที่จะถูกฝังลงในรูปภาพ.

จุดเชื่อมต่อ

วิธี เส้นทาง วัตถุประสงค์
GET /api/documents/{name}/info จำนวนหน้าและขนาดของแต่ละหน้า, หน่วยเป็น points
GET /api/documents/{name}/pages/{n}/image PNG ของหน้า n
GET /api/documents/{name}/annotations ทุก annotation เป็นสี่เหลี่ยมหนึ่งรูปในหน่วยหน้า
POST /api/documents/{name}/annotations เพิ่มหนึ่งรายการ
PUT /api/documents/{name}/annotations/{id} เปลี่ยนข้อความหรือเพิ่มการตอบกลับ
DELETE /api/documents/{name}/annotations/{id} ลบหนึ่งรายการ

การเขียนแต่ละครั้งจะคืนรายการเต็ม, ดังนั้นเบราว์เซอร์ไม่ต้องคำนวณว่าเซิร์ฟเวอร์มีอะไรอยู่ตอนนี้.

การเรนเดอร์

PreviewOptions previewOptions = new(page => File.Create(CachePath(name, page)))
{
    PreviewFormat = PreviewFormats.PNG,
    PageNumbers = new[] { pageNumber },   // 1-based
    RenderAnnotations = false,            // the canvas draws the markup
    Resolution = 144
};

annotator.Document.GeneratePreview(previewOptions);

เปรียบเทียบ timestamp ของภาพที่แคชกับของเอกสารและเรนเดอร์ใหม่เฉพาะเมื่อเอกสารเปลี่ยนจริง.

พิกเซลเข้า, หน่วยหน้าออก

แคนวาสเก็บสี่เหลี่ยมของมันในพิกเซลของภาพและส่งขนาดของภาพที่วาดบน — ไม่ใช่สเกลแฟกเตอร์:

body: JSON.stringify({
    page: currentPage,
    x, y, width, height,
    imageWidth: img.clientWidth,
    imageHeight: img.clientHeight,
    message: window.prompt('Comment'),
    user: 'Reviewer'
})

การตัดสินใจเดียวนี้ทำให้ UI คงถูกต้องเมื่อความละเอียดพรีวิวเปลี่ยน, เมื่อ CSS ขยายภาพ, หรือเมื่อใครสักคนเปิดบนโทรศัพท์. เซิร์ฟเวอร์ทำการคำนวณ:

double scaleX = page.Width / request.ImageWidth;
double scaleY = page.Height / request.ImageHeight;

annotator.Add(new AreaAnnotation
{
    PageNumber = page.PageNumber - 1,     // PageInfo is 1-based, annotations are 0-based
    Box = new Rectangle(
        (float)(request.X * scaleX), (float)(request.Y * scaleY),
        (float)(request.Width * scaleX), (float)(request.Height * scaleY)),
    BackgroundColor = 0xFFE699,
    PenColor = 0xE08C00,
    Opacity = 0.35,
    Message = request.Message,
    User = new User { Id = 1, Name = request.User, Role = Role.Editor }
});

AreaAnnotation.Box วัดจากมุมบนซ้ายของหน้า — ทิศทางเดียวกับที่เบราว์เซอร์วัด — ดังนั้นกล่องที่วาดจะแมปด้วยสเกลโดยไม่มีการพลิก.

ส่งรูปทรงสี่เหลี่ยมหนึ่งรูปไปยังเบราว์เซอร์

มาร์กอัปข้อความไม่ได้ใช้จุดกำเนิดนั้น. HighlightAnnotation.Points และที่เกี่ยวข้องวัดจากมุม ล่างซ้าย. แปลงบนเซิร์ฟเวอร์, เพื่อให้ฝั่งหน้าเห็นเฉพาะกล่องบนซ้ายเท่านั้น:

x = minX;
y = page.Height - maxY;      // flip to top-left
width = maxX - minX;
height = maxY - minY;

ทำเช่นนี้และไฮไลท์ที่เพิ่มใน Word, ใน Acrobat, หรือโดย automated review pass จะปรากฏในตำแหน่งที่ถูกต้องใน UI ของคุณโดยที่ JavaScript ไม่ต้องรู้เรื่องเรขาคณิตของ PDF.

การเขียนสลับไฟล์

Annotator เปิดไฟล์ต้นฉบับอยู่และไม่สามารถบันทึกทับไฟล์ที่กำลังอ่านได้:

using (Annotator annotator = new Annotator(path))
{
    annotator.Add(annotation);
    annotator.Save(path + ".tmp");
}

File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);

ใช้ lock ต่อเอกสารหนึ่งไฟล์รอบลำดับทั้งหมด. คำขอสองคำขอที่อ่าน, แก้ไขและเขียนทับไฟล์เดียวกันพร้อมกันจะทำให้หนึ่งการเปลี่ยนแปลงหายไป.

สิ่งที่การออกแบบนี้ไม่แก้ไข

ควรบอกอย่างตรงไปตรงมา, เพราะมันตัดสินว่าคุณสามารถส่งมอบได้หรือไม่:

  • Annotation ids change after a write. พวกมันถูกกำหนดขณะอ่านเอกสาร, ไม่ได้ถูกเก็บไว้ในเอกสาร. UI ที่รีโหลดรายการหลังการเปลี่ยนแปลงทุกครั้งก็ใช้ได้. ระบบหลายผู้ใช้ควรเก็บ annotation ในตารางของตนเองและใช้ import and export เพื่อย้ายเข้าและออกจากไฟล์ — ซึ่งเป็นวิธีที่คุณจะได้ audit trail และ per-user visibility.
  • The whole document is rewritten on every change. เหมาะกับสัญญา 30 หน้า, ไม่เหมาะกับคลังเอกสาร 2,000 หน้า.
  • There is no authentication. ทุกผู้เรียกในตัวอย่างเป็น “Reviewer”.

เรียกใช้

git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi

หรือในคอนเทนเนอร์, พร้อม --network none หากคุณต้องการดูการทำงานโดยไม่มีการส่งออกเลย:

docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui

เวอร์ชันขั้นตอนต่อขั้นตอนอยู่ในเอกสาร:
Build an annotation UI for your web app. หากคุณได้ฝังตัวดู PDF ด้วย JavaScript ไว้แล้ว, ให้คงไว้สำหรับการแสดงผลและใช้ endpoint เหล่านี้เฉพาะสำหรับการจัดเก็บ — กฎเรขาคณิตไม่มีการเปลี่ยนแปลง.