Anotasi

Anotasi di Doconut bekerja dalam dua arah: pengguna menggambarnya di widget peramban dan server menyimpannya per halaman, atau kode Anda membuatnya secara programatik dan memuatnya ke dalam sesi yang terbuka. Kedua cara tersebut menampilkan anotasi 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; kemudian Ribbon Anotasi 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.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  // the embedded annotation ribbon
}))

Pertahankan komposisi Viewer lengkap terlihat 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>

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:

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

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

Buka dan tutup dari toolbar Viewer milik host mana pun:

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

API Ribbon publik adalah:

onStatus, onToast, onLayout, onEditStart, dan onEditEnd adalah callback host opsional. Objek endpoints dapat tambahan 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 di peramban, tetapi data tetap menjadi 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.

Membuat anotasi di C#

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

app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Terikat pada dimensi halaman sesi yang 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 the
    // renderer membakar mereka ke dalam 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):

API AnnotationManager

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

Ekspor dengan anotasi dibakar

// PDF dari 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 pencitraan di layar, sehingga apa yang dilihat pengguna adalah apa yang terdapat dalam file.

Alur kerja Persistensi

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

Jangan gunakan token penampil yang tidak transparan sebagai pengidentifikasi anotasi permanen. Kaitkan data anotasi yang dipersistensikan dengan dokumen dan pengidentifikasi versi Anda sendiri.

Catatan Keamanan dan Rendering

• Permintaan anotasi menggunakan keamanan sesi/token yang sama seperti permintaan halaman.
• URL ImageAnnotation relatif diselesaikan dari host permintaan dan harus tetap dapat dijangkau oleh server saat proses pembakaran.
• Validasi dan kontrol setiap URL gambar yang diberikan pengguna untuk menghindari pemalsuan permintaan sisi server.
• Ekspor menerapkan keputusan lisensi/ watermark khusus 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