GroupDocs.Annotation هو غير معتمد على واجهة المستخدم. يقرأ ويكتب العلامات داخل المستندات ولا يرسم شيئًا على الشاشة. بالنسبة لمكتبة الخادم، هذا هو الانقسام الصحيح — ويترك سؤالًا واحدًا للجميع الذين يتبنونها: كيف يرسم الشخص الفعليًا التعليق التوضيحي؟
الإجابات المعتادة ثقيلة: تضمين عارض تجاري، أو اعتماد عرض Angular ثم محاولة توسيعه. هناك حل أخف. صور الصفحات، لوحة رسم، وست نقاط نهاية — لا مكوّن عارض، لا إطار عمل للواجهة الأمامية، لا خطوة بناء، لا CDN. كما أنه يعمل دون أي وصول إلى الشبكة الخارجية، وهو ما أصبح أكثر أهمية الآن.
العينة موجودة على GitHub:
browser-annotation-ui-net —
dotnet run واسحب صندوقًا على الصفحة.
الفكرة في فقرة واحدة
قم بعرض كل صفحة مرة واحدة كملف PNG بدون تعليقات توضيحية واحتفظ به في الذاكرة المؤقتة. أرسل قائمة التعليقات إلى المتصفح كبيانات. تقوم لوحة الرسم برسم العلامات فوق الصورة. إضافة تعليق تصبح كتابة صغيرة إلى المستند بالإضافة إلى إعادة تحميل القائمة — وليس إعادة عرض الصفحة — وتبقى العلامات قابلة للتحديد والنقر والرد بدلاً من أن تُدمج في صورة.
نقاط النهاية
| Method | Route | Purpose |
|---|---|---|
GET |
/api/documents/{name}/info |
عدد الصفحات وحجم كل صفحة، بالنقاط |
GET |
/api/documents/{name}/pages/{n}/image |
صورة PNG للصفحة n |
GET |
/api/documents/{name}/annotations |
كل تعليق كأحد المستطيلات بوحدات الصفحة |
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);
قارن طابع زمن الصورة المخزنة مؤقتًا بطابع زمن المستند وأعد العرض فقط عندما يتغير المستند فعليًا.
البكسلات داخل، وحدات الصفحة خارجًا
تحافظ لوحة الرسم على مستطيلها بوحدات بكسل الصورة وتُرسل حجم الصورة التي رُسمت عليها — وليس عامل مقياس:
body: JSON.stringify({
page: currentPage,
x, y, width, height,
imageWidth: img.clientWidth,
imageHeight: img.clientHeight,
message: window.prompt('Comment'),
user: 'Reviewer'
})
ذلك القرار هو ما يحافظ على صحة واجهة المستخدم عندما يتغير دقة المعاينة، أو عندما يقوم 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 أو عبر مراجعة تلقائية في المكان الصحيح بواجهة المستخدم دون أن يعرف JavaScript شيئًا عن هندسة PDF.
الكتابة باستخدام ملفات التبديل
المُعلّق يحتفظ بالمصدر مفتوحًا ولا يمكنه الحفظ فوق الملف الذي يقرأه:
using (Annotator annotator = new Annotator(path))
{
annotator.Add(annotation);
annotator.Save(path + ".tmp");
}
File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);
خذ قفلًا لكل مستند حول التسلسل بأكمله. طلبان يقرآن، يغيران ويعيدان كتابة نفس الملف في آنٍ واحد سيفقدان أحد التغييرات.
ما لا يحله هذا التصميم
من الجدير قول ذلك بصراحة، لأنه يحدد ما إذا كان يمكنك نشره كما هو:
- تتغير معرفات التعليقات بعد الكتابة. تُعيّن أثناء قراءة المستند، ولا تُخزن فيه. واجهة مستخدم تُعيد تحميل القائمة بعد كل تغيير تكون مناسبة. يجب على نظام متعدد المستخدمين الاحتفاظ بالتعليقات في جدول خاص به واستخدام الاستيراد والتصدير لنقلها داخل وخارج الملف — وهو أيضًا ما يمنحك سجل تدقيق ورؤية حسب المستخدم.
- يُعاد كتابة المستند بالكامل عند كل تغيير. مناسب لعقد من 30 صفحة، غير مناسب لأرشيف من 2,000 صفحة.
- لا يوجد مصادقة. كل من يستدعي العينة هو “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
الإصدار خطوة بخطوة موجود في الوثائق:
إنشاء واجهة مستخدم للتعليقات التوضيحية لتطبيق الويب الخاص بك.
إذا كنت قد دمجت بالفعل عارض PDF بـ JavaScript، احتفظ به للعرض واستخدم هذه النقاط النهاية فقط للتخزين — لا تتغير أي من قواعد الهندسة.