NexaScroll `NX.Scroll`

Name: NxCode IDE
Availability: InStock
Author: NxDOM

Manajemen posisi scroll (scrollTop / scrollLeft) untuk elemen berkelas .nx-scroll* — menyimpan ke localStorage (debounced), memulihkan saat init, dan mendukung elemen yang ditambahkan dinamis lewat MutationObserver.

API: NX.Scroll dan NX.NexaScroll (satu kelas, nxdom.js). Sumber: assets/modules/Dom/NexaScroll.js. Gaya scrollbar: assets/modules/assets/css/scroll.css (di-import dari assets/modules/nexa.css).

Opsi konstruktor

Opsi	Tipe	Default	Keterangan
`storageKey`	`string`	`'nexaScrollPositions'`	Satu key JSON di `localStorage` untuk semua posisi per elementId
`debounceDelay`	`number`	`100`	Jeda (ms) sebelum menulis ke `localStorage` setelah event `scroll`
`autoInit`	`boolean`	`true`	`true` → `init()` di akhir konstruktor. Untuk route SPA, sering `autoInit: false` lalu `init()` setelah DOM siap

Kelas yang dipindai

findScrollElements() memakai document.querySelectorAll untuk setiap kelas berikut (gabungan gaya + perilaku):

.nx-scroll, .nx-scroll-x
.nx-scroll-rounded, .nx-scroll-hidden, .nx-scroll-autohide, .nx-scroll-table, .nx-scroll-smooth, .nx-scroll-fade, .nx-scroll-shadow
.nx-scroll-thin, .nx-scroll-thick, .nx-scroll-primary

.nx-scroll — overflow vertikal; .nx-scroll-x — overflow horizontal (lihat scroll.css).

Identitas elemen (`elementId`)

Jika elemen punya atribut id, itu dipakai sebagai kunci penyimpanan.
Jika tidak, dibuat string bentuk nx-scroll-{classes}-{top}-{left} dari posisi dan kelas (kurang stabil bila layout berubah).

Praktik: beri id unik pada setiap area scroll yang ingin posisinya diingat.

Alur `init()`

findScrollElements() — isi Map internal scrollElements.
restoreScrollPositions() — baca localStorage, set scrollTop / scrollLeft (penundaan ~50 ms per elemen).
attachScrollListeners() — pasang scroll pada tiap elemen terdaftar.
observeDOM() — satu MutationObserver pada document.body (subtree). Node baru yang memuat / merupakan elemen scroll → setelah 100 ms dipanggil lagi findScrollElements, restoreScrollPositions, attachScrollListeners.

Catatan implementasi: pemanggilan ulang dari observer dapat menambah listener scroll ganda pada elemen yang sama. Untuk DOM yang sering diganti besar-besaran, pertimbangkan satu instance global atau deduplikasi listener / disconnect observer di sisi aplikasi.

destroy() — mengosongkan timer debounce dan Map elemen; tidak memutus MutationObserver yang dibuat di init().

Penyimpanan `localStorage`

Satu string JSON di bawah storageKey, bentuk:

JSON

{
  "id-elemen-a": { "scrollTop": 120, "scrollLeft": 0, "timestamp": 1730000000000 },
  "id-elemen-b": { "scrollTop": 0, "scrollLeft": 40, "timestamp": 1730000001000 }
}

Method utama

Method	Keterangan
`init()`	find → restore → attach → observe
`findScrollElements()`	Daftarkan ulang elemen dari kelas scroll (menimpa entri `Map` dengan `id` sama)
`restoreScrollPositions()`	Terapkan posisi tersimpan ke elemen di `Map`
`attachScrollListeners()`	Tambah handler `scroll` (debounce → `saveScrollPosition`)
`addElement(element, customId?)`	Daftarkan satu elemen manual; opsional `customId` sebagai kunci
`removeElement(elementId)`	Hapus dari `Map`, timer terkait, dan entri di JSON `localStorage`
`getScrollPosition(elementId)`	`{ scrollTop, scrollLeft }` atau `null`
`setScrollPosition(elementId, { scrollTop?, scrollLeft? })`	Set DOM lalu `saveScrollPosition`
`getElements()`	Array `{ id, element, className, position }`
`getSavedPositions()`	Objek mentah dari `localStorage` (parse aman)
`clearSavedPositions()`	`removeItem(storageKey)` — hapus semua posisi untuk key ini
`destroy()`	Hapus timer + kosongkan `Map` (observer tetap hidup)
`enable()` / `disable()`	Flag `on`; di beberapa versi jalur debounce masih bisa memanggil `saveScrollPosition` — verifikasi perilaku di build Anda atau bungkus sendiri jika perlu memutus penyimpanan

SPA / route dinamis

Isi innerHTML / pasang elemen scroll dulu.
new NX.Scroll({ storageKey: '...', autoInit: false }) lalu init() agar tidak memindai dokumen sebelum konten ada.
Bedakan storageKey per aplikasi atau fitur (demo: nexa-scroll-demo).

Contoh singkat

JavaScript

const sc = new NX.Scroll({
  storageKey: "myAppScroll",
  debounceDelay: 200,
  autoInit: false,
});
sc.init();
// sc.addElement(document.querySelector("#panel"), "panel");

const pos = sc.getScrollPosition("panel");
sc.setScrollPosition("panel", { scrollTop: 0 });

HTML

<div id="panel" class="nx-scroll" style="max-height: 200px">
  <!-- konten panjang -->
</div>

Demo di proyek

Rute: /scroll · Modul: templates/scroll.js — panel vertikal & horizontal, storageKey: 'nexa-scroll-demo', tombol reset clearSavedPositions dan scroll atas lewat setScrollPosition.

Impor modul langsung

JavaScript

import { NexaScroll } from "/assets/modules/Dom/NexaScroll.js";

const sc = new NexaScroll({ storageKey: "app", autoInit: false });
sc.init();

Setelah nxdom.js, gunakan NX.Scroll atau NX.NexaScroll.

Lihat juga

assets/modules/nxdom.js — registrasi Scroll / NexaScroll · NexaDom — route & hydrate

Nxdom Framework

NexaScroll NX.Scroll