Anotasi

Tambahkan dukungan anotasi ke penampil

Anotasi di Doconut bekerja dalam dua arah: pengguna menggambarnya di widget browser dan server menyimpannya per halaman, atau kode Anda membuatnya secara programatis dan memuatnya ke dalam sesi yang terbuka. Bagaimanapun, mereka ditampilkan pada halaman dan dapat dibakar ke dalam ekspor PDF/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 lengkap 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 bundel anotasi bersamaan dengan bundel viewer — mereka dibatasi lisensi, sehingga tag hanya muncul ketika kemampuan tersedia:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss     = true,
    IncludeAnnotationCss = true   // jquery-ui.min.css + annotationBar.css
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeViewerScripts      = true,
    IncludeAnnotationScripts  = true, // jquery-ui, raphael.js, annotation.js
    IncludeAnnotationBar      = true  // pita anotasi yang disematkan
}))

Pertahankan komposisi Viewer lengkap terlihat dalam markup:

html
<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>

Bundel Anotasi menghasilkan DOM Ribbon di dalam annBarMount; Anda tidak perlu menyalin tombol atau markup dialognya. Inisialisasi docViewer terlebih dahulu, kemudian buat Ribbon hanya ketika server mengonfirmasi bahwa Anotasi berlisensi:

html
<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: 'doconut',
        ResPath: 'doconut-res/images',
        onAnnLoaded:    () => annBar?.handleAnnLoaded(),
        onAnnSaved:     () => annBar?.handleAnnSaved(),
        onAnnSaveError: () => annBar?.handleAnnSaveError(),
        onAnnClosed:    () => annBar?.handleAnnClosed(),
        onError:        (message) => console.error('Viewer error:', message)
    });

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onStatus: (message) => console.log(message),
        onToast: (message, type) => console.log(type, message),
        onLayout: () => requestAnimationFrame(() => 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.

Menyimpan dari Ribbon mengirim data melalui middleware (AnnSave), yang menyimpannya dalam sesi dokumen per halaman. Memuat (AnnLoad) terjadi secara otomatis ketika halaman dengan anotasi ditampilkan. Empat panggilan balik onAnn* menjaga Ribbon tetap sinkron dengan siklus hidup viewer.

Buka dan tutup dari toolbar Viewer yang dimiliki host mana pun:

javascript
annBar.open();
annBar.close();

API Ribbon publik adalah:

MetodeTujuan
attach(objViewer)Hubungkan Ribbon ke viewer yang telah diinisialisasi; diperlukan satu kali
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 ketersediaan kontrol simpan/hapus setelah perubahan host
headerSlot()Dapatkan slot ekstensi header opsional untuk kontrol yang dimiliki host

onStatus, onToast, onLayout, onEditStart, dan onEditEnd adalah panggilan balik host opsional. Objek endpoints dapat juga menyediakan exportPdf, exportPng, imageUpload, dan imageList; kontrol tanpa endpoint yang dikonfigurasi tetap tersembunyi. Untuk urutan startup gabungan Viewer, Search, dan Annotation, lihat Panduan Cepat.

Bundel anotasi menambahkan alat authoring browser, tetapi data tetap milik sesi dokumen sisi server yang diidentifikasi oleh token. Membuka kembali sumber menciptakan sesi baru; simpan XML atau envelope anotasi yang terenkode dalam aplikasi Anda jika anotasi harus bertahan melampaui masa hidup sesi.

Dua jenis callback, dihubungkan dua cara

Kode anotasi menggunakan dua gaya callback, dan masing‑masing gagal secara diam ketika dihubungkan dengan cara yang lain:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed adalah opsi dari docViewer({...}), seperti setiap callback penampil.
  • Created, Changed, Deleted, dan Properties adalah fungsi global yang ditemukan berdasarkan nama: id penampil yang diprefix ke acara. Untuk penampil di #div_ctlDoc id‑nya adalah ctlDoc, sehingga fungsi‑fungsinya adalah ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted, dan ctlDoc_Properties. Fungsi yang salah eja atau diubah namanya tidak akan pernah dipanggil.

SaveAnnotations() tidak mengembalikan apakah ia menyimpan: hasilnya datang melalui onAnnSaved atau onAnnSaveError. Kode yang membaca nilai kembaliannya tidak pernah membersihkan flag "perubahan yang belum disimpan".

Buat anotasi dalam C#

Dapatkan sebuah manager yang terikat pada sesi terbuka, tambahkan anotasi, dan muat mereka (dengan using Doconut.Annotations; untuk tipe‑tipe dan using System.Drawing; untuk Rectangle/Color):

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer 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 — widget mengambilnya melalui AnnLoad dan
    // renderer mengubahnya menjadi ekspor image/PDF.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Tipe Anotasi

Semua tipe berada di Doconut.Annotations dan mewarisi dari BaseAnnotation (nomor halaman + Rectangle pembatas):

TypeNotes
StampAnnotationCap teks dengan ukuran font, border, warna; mendukung Opacity, Rotate
NoteAnnotationCatatan tempel dengan teks, warna latar, ukuran font, TitleColor
RectangleAnnotationWarna border + isi, Title/ShowTitle
CircleAnnotationBorder + isi, ShowBorder
EllipseAnnotationBorder + isi, ShowBorder
TriangleAnnotationWarna border, BackColor, ShowBorder
LineAnnotationGaris lurus dengan lebar dan warna
ArrowAnnotationGaris dengan kepala panah; Direction dapat diatur (tipe ArrowDirection, titik kompas, default E)
FreehandAnnotationGoresan bebas dari titik FreehandData yang terenkode
ImageAnnotationGambar dari URL. Sebuah relatif URL diresolusikan terhadap host permintaan saat anotasi ditambahkan; server mengambil gambar hanya pada waktu pembakaran — lihat catatan ekspor di bawah

API AnnotationManager

MemberPurpose
Add(BaseAnnotation)Antrian anotasi
GetAnnotations() / GetAnnotations(int page)Periksa apa yang dimiliki manager
ClearAnnotations() / ClearAnnotations(int page)Hapus semua / per halaman
GetAnnotationData() / GetAnnotationData(int page)String data‑anotasi yang terenkode — sebuah envelope Base64 (apa yang dikonsumsi widget)
GetAnnotationXml()Bentuk XML

Viewer mencerminkan operasi muat/baca terhadap sebuah sesi: LoadAnnotationData(token, manager) atau LoadAnnotationData(token, encodedData) (envelope Base64 dari GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Ekspor dengan anotasi terbakar

csharp
// PDF semua halaman dengan anotasi yang dirender di atasnya
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
    return Results.File(pdf, "application/pdf", "export.pdf");
});

// Atau ZIP berisi PNGs per halaman
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
    return Results.File(zip, "application/zip", "annotations-png.zip");
});

Ekspor menggunakan pembakar yang sama seperti rendering di layar, sehingga apa yang dilihat pengguna adalah apa yang terkandung dalam file — kecuali untuk anotasi gambar, yang dijelaskan berikutnya.

Anotasi gambar pada host intranet mengekspor sebagai "Image blocked"

Penampil dan ekspor mengambil gambar ImageAnnotation's dari tempat yang berbeda:

PermukaanSiapa yang mengunduh gambarPada host intranet atau pengembangan
Penampil di perambanPeramban penggunaGambar muncul
ExportAnnotationsToPdfAsync / …PngZipAsyncServerPlaceholder berwarna merah "Image blocked"

Ketika server mengambil gambar untuk disematkan, 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 diresolusikan terhadap host dari permintaan saat ini, jadi pada localhost, pada server intranet, atau pada situs apa pun yang diakses melalui alamat pribadi, gambar akan muncul di penampil dan ekspor berisi placeholder sebagai gantinya. Itu adalah mekanisme perlindungan yang berfungsi, bukan kegagalan rendering. Jika ekspor harus menyertakan gambar, layani gambar dari host dengan alamat publik dan gunakan URL absolut. Nama host yang tidak dapat diresolusikan ditolak dengan cara yang sama; kegagalan unduhan lainnya menampilkan URL dan pesan kesalahan berwarna merah di tempat gambar seharusnya.

Alur kerja Persistensi

  1. Buka dokumen dan dapatkan tokennya.
  2. Muat XML atau data terkode yang sebelumnya disimpan ke dalam token tersebut.
  3. Biarkan widget membaca dan menyunting anotasi sesi.
  4. Ambil XML dengan GetAnnotationXML(token) ketika aplikasi Anda memutuskan untuk menyimpan.
  5. Ekspor PDF/PNG ketika diperlukan deliverable yang diratakan.
  6. Tutup sesi dokumen.

Jangan gunakan token penampil yang opak sebagai pengidentifikasi anotasi permanen. Kaitkan data anotasi yang dipersistensikan dengan dokumen Anda sendiri serta pengidentifikasi versi.

Catatan Keamanan dan Rendering

  • Permintaan anotasi menggunakan keamanan sesi/token yang sama seperti permintaan halaman.
  • Validasi dan kontrol setiap URL gambar yang diberikan pengguna untuk menghindari pemalsuan permintaan sisi server.
  • Ekspor menerapkan keputusan lisensi/custom-watermark yang sama seperti rendering halaman di layar.
  • Payload bebas tangan yang besar dan ekspor resolusi tinggi meningkatkan penggunaan memori; uji dokumen realistis dan nilai zoom.

Pemecahan Masalah

GejalaPemeriksaan
Pita anotasi tidak munculKemampuan Annotation dan empat flag CSS/script anotasi
Callback penyimpanan melaporkan errorKedaluwarsa token/sesi dan middleware BasePath
ctlDoc_Created (atau fungsi acara lain) tidak pernah dijalankanNama fungsi: id penampil + _ + event, sebagai fungsi global
Anotasi C# tidak munculPenomoran halaman dimulai dari satu dan data dimuat ke dalam token aktif
Anotasi gambar muncul di layar tetapi tidak di eksporHost gambar memiliki alamat pribadi atau loopback — lihat di atas
Dokumen yang dibuka kembali tidak memiliki anotasiPersistensikan XML/data di luar sesi penampil, lalu muat ke dalam token baru

Apakah halaman ini membantu?