Composable

useSkeletonizer e i data composable skeleton-aware.

Composable

useSkeletonizer()

const skeletonizer = useSkeletonizer()

skeletonizer.enable()          // attiva la modalità skeleton globalmente
skeletonizer.disable()         // la disattiva
skeletonizer.toggle()          // la inverte; restituisce il nuovo booleano
skeletonizer.isEnabled         // ComputedRef<boolean>
skeletonizer.config            // configurazione risolta reattiva
skeletonizer.stats             // statistiche di runtime reattive
skeletonizer.refresh()         // riscansiona tutti gli host montati
skeletonizer.scan()            // riscansiona; restituisce { nodes, svg, cacheHit }

skeletonizer.setTheme({ baseColor: '#ddd', highlightColor: '#fff' })
skeletonizer.setAnimation('pulse')
skeletonizer.registerAnimation({ name: 'blink', css: '…' })

skeletonizer.config.renderMode  // sempre 'svg' (sola lettura)
skeletonizer.engine             // lo SkeletonEngine per-app

scan() esegue la pipeline (misura → render dell'overlay SVG) e restituisce un riepilogo del risultato:

const { nodes, svg, cacheHit } = skeletonizer.scan()
// nodes    — ScannedNode[] misurati per questo host (DOMRect, relativi all'host)
// svg      — l'elemento <svg> overlay generato (o il suo markup)
// cacheHit — true quando il blueprint SVG è stato servito dalla cache di layout

Funziona a qualsiasi scope — globale, per pagina, per componente o per contenitore — perché ogni controllo passa per un singolo store reattivo a cui ogni host <Skeletonizer> si sottoscrive.

stats

const { stats } = useSkeletonizer()
// { hosts, bones, ignored, scans, lastScanMs, enabled,
//   renderMode, score, fps, animationTier, memoryMB,
//   cacheHits, cacheMisses, degraded, timings }
// timings = { scanMs, renderMs, totalMs }

Statistiche di runtime reattive, esposte anche nella scheda DevTools. renderMode è sempre 'svg'. I campi di Step 3 (score, fps, animationTier, contatori di cache…) vengono popolati dal motore adattivo quando è attivo.

useSkeletonPerformance()

La superficie avanzata di performance / DevTools — telemetria, modalità Explain e la classifica dei colli di bottiglia, più i controlli a runtime. Alimenta una dashboard diagnostica (e il Performance Lab).

const perf = useSkeletonPerformance()

perf.stats                       // lo stesso oggetto stats reattivo
perf.telemetry()                 // { avgTotalMs, avgScanMs, cacheHitRatio, … }
perf.series('fps')               // number[] per una sparkline
perf.explanations()              // decisioni del motore in linguaggio naturale (Explain)
perf.lastExplanation             // ComputedRef<SkeletonExplainEntry | null>
perf.bottlenecks()               // host ordinati per costo di skeletonizzazione
perf.cacheHitRatio               // ComputedRef<number> in [0,1]
perf.blueprint()                 // SvgBlueprint | null — l'SVG Blueprint Inspector
perf.engine                      // lo SkeletonEngine per-app

blueprint()

Restituisce il Blueprint SVG corrente per l'host attivo (o null quando non c'è nulla di skeletonizzato) — la descrizione serializzabile dell'overlay generato: il viewBox bloccato sul bounding box dell'host, l'id del gradiente condiviso (sk-shimmer-{uid}) e l'elenco delle forme (<rect> / <circle>) con le loro coordinate relative all'host. Alimenta l'SVG Blueprint Inspector nei DevTools, così puoi leggere il vettore esatto prodotto dal motore e verificare i cache hit.

const bp = perf.blueprint()
// { uid, viewBox, gradientId, shapes: [{ kind: 'rect' | 'circle', x, y, … }], cached }

Data composable skeleton-aware

Rispecchiano i data composable di Nuxt e, quando skeleton: true (il predefinito), attivano lo skeleton globale mentre la richiesta è in corso e lo disattivano al termine — con conteggio dei riferimenti, così le richieste concorrenti si compongono correttamente.

const { data } = await useSkeletonFetch('/api/users', { skeleton: true })

Wrapper disponibili:

  • useSkeletonFetch — avvolge useFetch
  • useSkeletonLazyFetch — avvolge useLazyFetch
  • useSkeletonAsyncData — avvolge useAsyncData
  • useSkeletonLazyAsyncData — avvolge useLazyAsyncData

Passa { skeleton: false } per escludere una singola chiamata. Qualsiasi <Skeletonizer> senza un :enabled esplicito segue questo stato globale.

Preferisci il controllo esplicito? Collega :enabled a un ref pending — vedi Integrazione Nuxt.