Risoluzione dei problemi
Suggerimento
Gli avvisi in console descritti qui sotto compaiono solo nelle build di sviluppo. Le build di produzione e la build CDN li rimuovono per risparmiare byte.
La sidebar non resta bloccata
- È allungata. In grid/flex la sidebar occupa per impostazione predefinita l'intera altezza della riga. Aggiungi
align-items: startal genitore oalign-self: startalla sidebar. Vedi Layout. - Un antenato ha
overflowimpostato.overflow: hidden | auto | scrollsu qualsiasi antenato lo trasforma nel contenitore sticky. Usaoverflow: clip, oppure passa quell'elemento comescrollerse è davvero il contenitore di scroll. medianon corrisponde. L'istanza resta inattiva finché la media query è falsa.- All'avvio è nascosta. Se la sidebar non ha altezza all'avvio (
display: none, dentro una tab chiusa), l'istanza resta in attesa. UnResizeObserverla rileva quando diventa visibile, oppure puoi chiamareupdate().
Errore "element not found"
stickySidebar('#sidebar') lancia un errore quando il selettore non trova nulla. Crea l'istanza dopo che l'elemento è nel DOM: dopo DOMContentLoaded, in onMounted / useEffect, oppure usa gli adapter per i framework, che se ne occupano al posto tuo.
Il selettore dell'header non trova nulla
[dynamic-sticky-sidebar] header selector ".site-header" matched no elements
All'avvio dell'istanza il selettore header non ha trovato nulla, quindi la sidebar si blocca alla cima del viewport e può finire sotto il tuo header. Controlla il selettore, oppure chiama refresh() dopo che l'header è stato renderizzato.
Scroller non trovato
[dynamic-sticky-sidebar] scroller "#app" not found, using the window
L'opzione scroller non corrisponde a nessun elemento. Controlla il selettore, oppure passa direttamente l'elemento.
Avviso in console su grid / row-flex
[dynamic-sticky-sidebar] parent is not grid / row-flex, so scrolling up uses a JS fallback …
Il genitore diretto della sidebar è un block. Funziona comunque, ma lo scroll verso l'alto può restare indietro di un frame. Assegna al genitore display: grid; align-items: start. Vedi Layout a blocchi.
La sidebar si sovrappone all'header o lascia un vuoto sotto di esso
- Assicurati di passare in
headertutte le righe dell'header. Con un selettore vengono usati tutti gli elementi trovati. - Se l'header si sposta per via di una classe su un antenato, la libreria non può accorgersene. Chiama
update(), oppure usasubscribe. - Gli header sostituiti nel DOM dopo l'avvio richiedono
refresh(). - Vuoi più spazio? Aumenta
gap(predefinito16) o aggiungioffsetTop.
Il contenuto della sidebar cambia altezza
Non serve fare nulla. Un ResizeObserver osserva la sidebar e il suo genitore. Se l'altezza della sidebar cambia mentre è rilasciata, viene riancorata alla sua posizione attuale sullo schermo e le posizioni bloccate vengono ricalcolate.
Rendering lato server
Il core accede a document e window solo quando viene chiamata stickySidebar(). L'hook React viene eseguito in una callback ref e l'entry React è marcata "use client". Il composable e la direttiva Vue vengono eseguiti dopo il mount. Puoi importarli tutti senza problemi in app SSR (Next.js, Nuxt, VuePress, …).