Anotasi
Tambahkan dukungan anotasi ke penampil
Anotasi di Doconut berfungsi dalam dua arah: pengguna menggambar anotasi di widget peramban dan server menyimpannya per halaman, atau kode Anda membuatnya dan memuatnya ke dalam sesi terbuka. Bagaimanapun, anotasi tersebut ditampilkan pada halaman dan dapat dibakar ke dalam ekspor PDF atau PNG.
Dukungan anotasi dibatasi oleh kemampuan lisensi Annotation (diberikan secara otomatis di bawah lisensi Temporary yang aktif).
Aktifkan UI anotasi
Anotasi adalah modul Viewer, bukan toolbar mandiri. Halaman harus menyertakan sumber daya Viewer, toolbar Viewer, mount Viewer, dan objViewer yang telah diinisialisasi; Ribbon Anotasi kemudian dipasang dan dilampirkan ke instance yang sama.
Keluarkan file anotasi bersama file viewer. Mereka dibatasi lisensi, sehingga tag mereka muncul hanya ketika kemampuan diberikan. Pada MVC 5, buat tag di controller (view tidak memiliki @inject):
public class ViewerController : Controller
{
public ActionResult Index()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
});
ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // pita anotasi yang disematkan
});
ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
return View();
}
}Pertahankan komposisi Viewer lengkap dalam markup:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Kontrol Penampil, termasuk tombol yang membuka Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>File Anotasi menghasilkan Ribbon di dalam annBarMount; Anda tidak menyalin tombol atau dialognya. Inisialisasi docViewer terlebih dahulu, kemudian buat Ribbon hanya ketika server mengonfirmasi bahwa Anotasi berlisensi:
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
var annBar = null;
var currentToken = '';
var objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
onAnnLoaded: function () { if (annBar) annBar.handleAnnLoaded(); },
onAnnSaved: function () { if (annBar) annBar.handleAnnSaved(); },
onAnnSaveError: function () { if (annBar) annBar.handleAnnSaveError(); },
onAnnClosed: function () { if (annBar) annBar.handleAnnClosed(); },
onError: function (message) { console.error('Viewer error:', message); }
});
@if ((bool)ViewBag.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: function () { return { token: currentToken }; },
onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
});
annBar.attach(objViewer);
</text>
}
</script>Tanpa kemampuan tersebut, ReferenceScripts menghilangkan skrip Ribbon, sehingga if sisi server menjaga panggilan doconutAnnotationBar(...) yang tidak dilindungi agar tidak merusak halaman. Pada Web Forms, tulis penjagaan yang sama seperti <% if (IsAnnotationEnabled) { %> … <% } %>.
Menyimpan dari Ribbon mengirim data ke DocImage.axd (AnnSave), yang menyimpannya dalam sesi dokumen per halaman. Memuat (AnnLoad) terjadi secara otomatis ketika halaman dengan anotasi dirender.
Buka dan tutup Ribbon dari toolbar Anda sendiri dengan annBar.open() dan annBar.close(). API publiknya:
| Metode | Tujuan |
|---|---|
attach(objViewer) | Hubungkan Ribbon ke viewer yang telah diinisialisasi; diperlukan sekali |
open() / close() | Masuk atau keluar dari penyuntingan anotasi |
reset() | Kembalikan Ribbon ke keadaan tertutup, tidak dalam penyuntingan |
isOpen() / annotating() | Baca status Ribbon / status penyuntingan anotasi viewer |
reopenEditable() | Muat ulang anotasi halaman saat ini sebagai objek yang dapat disunting |
updateActionState() | Segarkan kontrol simpan dan hapus setelah perubahan host |
headerSlot() | Slot header opsional untuk kontrol milik host |
onStatus, onToast, onLayout, onEditStart, dan onEditEnd adalah callback host opsional. Objek endpoints juga dapat menyediakan exportPdf, exportPng, imageUpload, dan imageList; kontrol tanpa endpoint yang dikonfigurasi tetap tersembunyi.
Dua jenis callback, terhubung dua cara
Kode anotasi menggunakan dua gaya callback, dan masing‑masing gagal secara diam ketika dihubungkan dengan cara yang lain:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedadalah opsi daridocViewer({...}), seperti setiap callback viewer.Created,Changed,Deleted, danPropertiesadalah fungsi global yang ditemukan berdasarkan nama: id viewer yang diprefix ke event. Untuk viewer di#div_ctlDocid‑nya adalahctlDoc, sehingga fungsi‑fungsinya adalahctlDoc_Created,ctlDoc_Changed,ctlDoc_Deleted, danctlDoc_Properties. Fungsi yang salah eja atau diubah namanya tidak akan pernah dipanggil.
SaveAnnotations() tidak mengembalikan apakah berhasil disimpan: hasilnya datang melalui onAnnSaved atau onAnnSaveError. Kode yang membaca nilai kembaliannya tidak pernah membersihkan flag "perubahan yang belum disimpan".
Membuat anotasi dalam C#
Dapatkan manager yang terikat pada sesi terbuka, tambahkan anotasi, dan muat mereka (dengan using Doconut.Annotations; untuk tipe‑tipe dan using System.Drawing; untuk Rectangle dan Color):
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
// Terikat pada dimensi halaman sesi terbuka
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// Satu stempel per halaman
for (int page = 1; page <= pageCount; page++)
{
manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
$"PAGE {page}", 28, 4, Color.Maroon)
{
Opacity = 60,
Rotate = -8
});
}
manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
"Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));
// Muat ke dalam sesi - penampil mengambilnya, dan perender menempelkannya ke
// ekspor image/PDF.
viewer.LoadAnnotationData(token, manager);
return new HttpStatusCodeResult(200);
}Tipe Anotasi
Semua tipe berada di Doconut.Annotations dan mewarisi dari BaseAnnotation (nomor halaman plus Rectangle pembatas):
| Tipe | Catatan |
|---|---|
StampAnnotation | Stempel teks dengan ukuran font, border, warna; mendukung Opacity, Rotate |
NoteAnnotation | Catatan tempel dengan teks, warna latar, ukuran font, TitleColor |
RectangleAnnotation | Warna border dan isi, Title/ShowTitle |
CircleAnnotation | Border dan isi, ShowBorder |
EllipseAnnotation | Border dan isi, ShowBorder |
TriangleAnnotation | Warna border, BackColor, ShowBorder |
LineAnnotation | Garis lurus dengan lebar dan warna |
ArrowAnnotation | Garis dengan kepala panah; Direction dapat diatur (ArrowDirection, titik kompas, default E) |
FreehandAnnotation | Goresan bebas dari titik FreehandData yang terenkode |
ImageAnnotation | Gambar dari URL. URL relatif diresolusikan terhadap host permintaan saat ini ketika anotasi ditambahkan — lihat catatan ekspor di bawah |
API AnnotationManager
| Anggota | Tujuan |
|---|---|
Add(BaseAnnotation) | Antrian sebuah anotasi |
GetAnnotations() / GetAnnotations(int page) | Periksa apa yang dimiliki manager |
ClearAnnotations() / ClearAnnotations(int page) | Hapus semua / per halaman |
GetAnnotationData() / GetAnnotationData(int page) | Data anotasi terenkode — amplop yang dikonsumsi widget |
GetAnnotationXml() | Bentuk XML |
Viewer mencerminkan operasi load dan read terhadap sebuah sesi: LoadAnnotationData(token, manager) atau LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml), dan GetAnnotationXML(token).
Ekspor dengan anotasi dibakar
// PDF semua halaman dengan anotasi yang dirender di atasnya
public async Task<ActionResult> ExportPdf(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
return File(pdf, "application/pdf", "export.pdf");
}
// Atau ZIP berisi PNG per halaman
public async Task<ActionResult> ExportPngZip(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
return File(zip, "application/zip", "annotations-png.zip");
}Ekspor menggunakan pembakar yang sama seperti rendering di layar, serta lisensi dan keputusan watermark khusus yang sama.
Anotasi gambar pada host intranet mengekspor sebagai "Image blocked"
Penampil dan ekspor mengambil gambar ImageAnnotation's dari tempat yang berbeda:
| Permukaan | Siapa yang mengunduh gambar | Pada host intranet atau pengembangan |
|---|---|---|
| Penampil di peramban | Peramban pengguna | Gambar muncul |
ExportAnnotationsToPdfAsync / …PngZipAsync | Server | Placeholder berwarna merah "Image blocked" |
Ketika server mengambil gambar untuk dimasukkan, ia menolak alamat yang mengarah kembali ke jaringan pribadi: loopback (localhost, 127.0.0.1), 0.0.0.0, link-local (169.254.x.x), rentang privat 10.x, 172.16–31.x, dan 192.168.x, carrier‑grade NAT (100.64.0.0/10), serta alamat link‑local dan unique‑local IPv6. Ini melindungi server dari penggunaan untuk mengakses sistem internal melalui URL gambar yang dibuat, dan tidak ada saklar untuk mematikannya.
URL gambar relatif diselesaikan terhadap host dari permintaan saat ini, jadi pada localhost, pada server intranet, atau pada situs mana pun yang diakses melalui alamat pribadi, gambar muncul di penampil dan ekspor berisi placeholder sebagai gantinya. Itu adalah mekanisme perlindungan yang bekerja, bukan kegagalan rendering. Jika ekspor harus menyertakan gambar, layani gambar dari host dengan alamat publik dan gunakan URL absolut. Nama host yang tidak dapat diselesaikan akan ditolak dengan cara yang sama; kegagalan unduhan lainnya akan menampilkan URL dan pesan kesalahan berwarna merah di tempat gambar seharusnya.
Alur kerja persistensi
- Buka dokumen dan dapatkan tokennya.
- Muat XML atau data terenkode yang disimpan sebelumnya ke dalam token tersebut.
- Biarkan widget membaca dan mengedit anotasi sesi.
- Ambil XML dengan
GetAnnotationXML(token)ketika aplikasi Anda memutuskan untuk menyimpan. - Ekspor PDF atau PNG ketika diperlukan deliverable yang diratakan.
- Tutup sesi dokumen.
Jangan gunakan token penampil sebagai pengidentifikasi anotasi permanen — token tersebut berakhir bersama sesi, dan daur ulang pool aplikasi mengakhiri setiap sesi pada satu server. Simpan data anotasi terhadap dokumen dan pengidentifikasi versi Anda sendiri.
Catatan keamanan dan rendering
- Permintaan anotasi menggunakan keamanan sesi dan token yang sama seperti permintaan halaman.
- Validasi dan kontrol setiap URL gambar yang diberikan pengguna.
- Payload bebas tangan yang besar dan ekspor resolusi tinggi meningkatkan penggunaan memori; uji dokumen realistis dan nilai zoom.
Pemecahan Masalah
| Gejala | Pemeriksaan |
|---|---|
| Ribbon Anotasi tidak ada | Kemampuan Annotation dan empat flag CSS/script anotasi |
| Menyimpan melaporkan kesalahan | Kedaluwarsa token atau sesi, dan BasePath widget |
ctlDoc_Created (atau fungsi acara lain) tidak pernah dijalankan | Nama fungsi: id penampil + _ + acara, sebagai fungsi global |
| Anotasi C# tidak muncul | Nomor halaman dimulai dari satu, dan data dimuat ke dalam token aktif |
| Anotasi gambar muncul di layar tetapi tidak di ekspor | Host gambar memiliki alamat pribadi atau loopback — lihat di atas |
| Dokumen yang dibuka kembali tidak memiliki anotasi | Simpan XML atau data di luar sesi penampil, lalu muat ke dalam token baru |
Apakah halaman ini membantu?