GroupDocs.Annotation bersifat UI-agnostic. Ia membaca dan menulis markup di dalam dokumen dan tidak menggambar apa pun di layar. Untuk sebuah perpustakaan server, itulah pemisahan yang tepat — dan ini meninggalkan satu pertanyaan bagi semua orang yang mengadopsinya: bagaimana seseorang sebenarnya menggambar anotasi?
Jawaban biasanya berat: menyematkan penampil komersial, atau mengadopsi demo Angular lalu mencoba memperluasnya. Ada yang lebih ringan. Gambar halaman, kanvas, dan enam endpoint — tanpa komponen penampil, tanpa kerangka kerja front-end, tanpa langkah build, tanpa CDN. Ini juga berjalan tanpa akses jaringan keluar sama sekali, yang kini lebih penting daripada sebelumnya.
Contoh tersedia di GitHub:
browser-annotation-ui-net —
dotnet run dan seret sebuah kotak di halaman.
Ide dalam satu paragraf
Render setiap halaman sekali sebagai PNG tanpa anotasi dan simpan dalam cache. Kirim daftar anotasi ke browser sebagai data. Kanvas menggambar markup di atas gambar. Menambahkan komentar kemudian menjadi penulisan kecil ke dokumen plus memuat ulang daftar — bukan render ulang halaman — dan markup tetap dapat dipilih, dapat diklik, dan dapat dijawab alih-alih menjadi bagian dari gambar.
Endpoint
| Metode | Rute | Tujuan |
|---|---|---|
GET |
/api/documents/{name}/info |
jumlah halaman dan ukuran setiap halaman, dalam poin |
GET |
/api/documents/{name}/pages/{n}/image |
PNG dari halaman n |
GET |
/api/documents/{name}/annotations |
setiap anotasi sebagai satu persegi panjang dalam satuan halaman |
POST |
/api/documents/{name}/annotations |
tambahkan satu |
PUT |
/api/documents/{name}/annotations/{id} |
ubah pesan atau tambahkan balasan |
DELETE |
/api/documents/{name}/annotations/{id} |
hapus satu |
Setiap penulisan mengembalikan daftar lengkap, sehingga browser tidak pernah harus menebak apa yang kini disimpan server.
Rendering
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);
Bandingkan cap waktu gambar yang di-cache dengan dokumen dan render ulang hanya ketika dokumen benar-benar berubah.
Piksel masuk, satuan halaman keluar
Kanvas menyimpan persegi panjangnya dalam piksel gambar dan mengirim ukuran gambar yang digambarnya — bukan faktor skala:
body: JSON.stringify({
page: currentPage,
x, y, width, height,
imageWidth: img.clientWidth,
imageHeight: img.clientHeight,
message: window.prompt('Comment'),
user: 'Reviewer'
})
Keputusan itu yang membuat UI tetap benar ketika resolusi pratinjau berubah, ketika CSS menskalakan gambar, atau ketika seseorang membukanya di ponsel. Server melakukan perhitungan:
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 diukur dari sudut kiri atas halaman — arah yang sama dengan yang diukur browser — sehingga kotak yang digambar dipetakan dengan skala tanpa dibalik.
Kirim satu bentuk persegi panjang ke browser
Markup teks tidak berbagi asal itu. HighlightAnnotation.Points dan yang terkait diukurnya dari sudut kiri bawah. Konversi di server, sehingga front end hanya pernah melihat kotak kiri atas:
x = minX;
y = page.Height - maxY; // flip to top-left
width = maxX - minX;
height = maxY - minY;
Lakukan ini dan sorotan yang ditambahkan di Word, di Acrobat, atau oleh sebuah automated review pass akan muncul di tempat yang tepat di UI Anda tanpa JavaScript mengetahui apa pun tentang geometri PDF.
Penulisan menukar file
Annotator menyimpan sumber terbuka dan tidak dapat menyimpan di atas file yang sedang dibacanya:
using (Annotator annotator = new Annotator(path))
{
annotator.Add(annotation);
annotator.Save(path + ".tmp");
}
File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);
Ambil kunci per-dokumen di sekitar seluruh urutan. Dua permintaan yang membaca, mengubah, dan menulis ulang file yang sama secara bersamaan akan kehilangan salah satu perubahan.
Apa yang tidak diselesaikan oleh desain ini
Layak dikatakan secara jelas, karena ini menentukan apakah Anda dapat mengirimkannya sebagaimana adanya:
- ID anotasi berubah setelah penulisan. Mereka diberikan saat dokumen dibaca, tidak disimpan di dalamnya. UI yang memuat ulang daftar setelah setiap perubahan baik-baik saja. Sistem multi-pengguna harus menyimpan anotasi di tabelnya sendiri dan menggunakan impor serta ekspor untuk memindahkannya masuk dan keluar file — yang juga cara Anda mendapatkan jejak audit dan visibilitas per pengguna.
- Seluruh dokumen ditulis ulang pada setiap perubahan. Baik untuk kontrak 30 halaman, tidak tepat untuk arsip 2.000 halaman.
- Tidak ada otentikasi. Setiap pemanggil dalam contoh adalah “Reviewer”.
Jalankan
git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi
Atau dalam kontainer, dengan --network none jika Anda ingin melihatnya bekerja tanpa keluar sama sekali:
docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui
Versi langkah demi langkah ada di dokumentasi: Buat UI anotasi untuk aplikasi web Anda. Jika Anda sudah menyematkan penampil PDF JavaScript, pertahankan untuk tampilan dan gunakan endpoint ini hanya untuk penyimpanan — tidak ada aturan geometri yang berubah.