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 เหล่านี้เฉพาะสำหรับการจัดเก็บ — กฎเรขาคณิตไม่มีการเปลี่ยนแปลง.