GroupDocs.Annotation بدون وابستگی به رابط کاربری است. این کتابخانه داخل اسناد نشانه‌گذاری می‌خواند و می‌نویسد و هیچ چیزی را روی صفحه رسم نمی‌کند. برای یک کتابخانه سرور این تقسیم‌بندی صحیح است — و یک سؤال برای همه کسانی که آن را به کار می‌گیرند باقی می‌گذارد: چگونه یک فرد واقعاً نشانه‌گذاری را رسم می‌کند؟

پاسخ‌های معمول سنگین هستند: یک نمایشگر تجاری را جاسازی کنید، یا دموی Angular را بپذیرید و سپس سعی کنید آن را گسترش دهید. یک راه‌حل سبک‌تر وجود دارد. تصاویر صفحات، یک بوم (canvas) و شش نقطه انتهایی — بدون کامپوننت نمایشگر، بدون فریم‌ورک فرانت‌اند، بدون مرحله ساخت، بدون CDN. همچنین بدون نیاز به دسترسی شبکه خروجی کار می‌کند، که این موضوع بیش از قبل اهمیت دارد.

نمونه در GitHub موجود است:
browser-annotation-ui-net — dotnet run و یک جعبه را روی صفحه بکشید.

ایده در یک پاراگراف

هر صفحه را یک بار به صورت PNG بدون نشانه‌گذاری رندر کنید و آن را در کش ذخیره کنید. لیست نشانه‌گذاری‌ها را به مرورگر به صورت داده بفرستید. بوم (canvas) نشانه‌گذاری‌ها را روی تصویر می‌کشد. افزودن یک نظر سپس یک نوشتن کوچک به سند به‌همراه بارگذاری مجدد لیست است — نه رندر مجدد صفحه — و نشانه‌گذاری‌ها قابل انتخاب، کلیک‌پذیر و پاسخ‌گویی می‌مانند به‌جای اینکه در یک تصویر ثابت شوند.

نقطه‌های انتهایی

متد مسیر هدف
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'
})

این تصمیم واحد، 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 یا توسط یک بازبینی خودکار اضافه شده است، در مکان صحیح UI شما ظاهر می‌شود بدون اینکه جاوااسکریپت چیزی دربارهٔ هندسهٔ PDF بداند.

نوشتن فایل‌های موقت

Annotator منبع را باز نگه می‌دارد و نمی‌تواند روی فایلی که در حال خواندن است، ذخیره‌سازی انجام دهد:

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

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

قفل‌گذاری سطح‑سندی را در اطراف کل توالی بگیرید. دو درخواست که همزمان فایل را می‌خوانند، تغییر می‌دهند و بازنویسی می‌کنند، یکی از تغییرات را از دست می‌دهند.

آنچه این طراحی حل نمی‌کند

قابل ذکر است، زیرا تصمیم می‌گیرد آیا می‌توانید آن را به همان شکل فعلی تحویل دهید یا نه:

  • Annotation ids change after a write. آنها هنگام خواندن سند اختصاص می‌یابند و در سند ذخیره نمی‌شوند. یک UI که پس از هر تغییر لیست را دوباره بارگذاری می‌کند، مشکلی ندارد. یک سیستم چندکاربره باید نشانه‌گذاری‌ها را در جدول خود نگه دارد و از واردات/صادرات برای جابجایی آنها به داخل و خارج فایل استفاده کند — که همین روش است که امکان داشتن ردپای حسابرسی و دیدگاه per‑user را می‌دهد.
  • 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

نسخهٔ گام‌به‌گام در مستندات موجود است:
ساخت یک UI نشانه‌گذاری برای برنامه وب شما. اگر قبلاً یک نمایشگر PDF جاوااسکریپت را جاسازی کرده‌اید، آن را برای نمایش نگه دارید و فقط از این نقطه‌های انتهایی برای ذخیره‌سازی استفاده کنید — هیچ‌یک از قوانین هندسی تغییر نمی‌کند.