Interattività con Alpine.js

Interattività con Alpine.js

Ogni pagina compilata da BX Sites carica già Alpine.js

• è ciò che alimenta l'interruttore modalità scura integrato e il menu a discesa della lingua in ognuno dei tre temi integrati. Quella stessa istanza Alpine è disponibile gratuitamente anche per il contenuto delle tue pagine: nessuna impostazione di bxsites.json da attivare, nessuna voce extraJs da aggiungere, nessun tag <script> extra da scrivere nel tuo markdown.

Dato che l'HTML grezzo a livello di blocco passa intatto nel tuo markdown, puoi mettere gli attributi x-data/x-show/@click/ecc. di Alpine direttamente su qualsiasi blocco HTML e funziona senza altro.

Prima di ricorrere ad Alpine

La maggior parte delle esigenze "interattive" ha già un blocco a direttiva pensato apposta che non richiede di scrivere alcun JS in prima persona - ricorri prima a questi:

• Una sezione comprimibile → Espandibile oppure un'ammonizione comprimibile
• Contenuto alternativo raggruppato dietro schede cliccabili → Schede di contenuto
• Un percorso guidato numerato → Stepper

Alpine serve per il contenuto interattivo che questi non coprono - qualsiasi cosa con un proprio stato lato client.

Un pulsante copia-negli-appunti

Un caso comune: un pulsante accanto a un comando di installazione che lo copia e conferma la copia:

<div x-data="{ copied: false }">
  <button type="button" @click="navigator.clipboard.writeText( 'box install bx-sites' ); copied = true; setTimeout( () => copied = false, 1500 )">
    <span x-show="!copied">Copy install command</span>
    <span x-show="copied" x-cloak>Copied!</span>
  </button>
</div>

Un filtro dal vivo

Filtrare una lista lato client, senza andata e ritorno verso il server:

<div x-data="{ query: '' }">
  <input type="text" x-model="query" placeholder="Filter providers...">
  <ul>
    <li x-show="'local'.includes( query.toLowerCase() )">local (static index, no server)</li>
    <li x-show="'algolia'.includes( query.toLowerCase() )">algolia (hosted DocSearch)</li>
    <li x-show="'pagefind'.includes( query.toLowerCase() )">pagefind (indexed at build time)</li>
  </ul>
</div>

x-model collega il valore dell'input allo stato Alpine; l'x-show di ogni <li> viene rivalutato a ogni tasto premuto.

Le basi di x-data, se sei nuovo ad Alpine

x-data dichiara lo stato reattivo proprio di uno scope come un semplice oggetto JS; qualsiasi cosa dentro quell'elemento può leggerlo/scriverlo, e x-show/x-text/x-model/@click (forma abbreviata di x-on:click) reagiscono tutti al suo cambiamento:

<div x-data="{ count: 0 }">
  <button type="button" @click="count++">Clicked <span x-text="count"></span> times</button>
</div>

Vedi la documentazione ufficiale di Alpine per l'elenco completo delle direttive (x-if, x-for, x-transition, e altre).

Cose da sapere

• È fondamentale, non opzionale. Gli elementi di contorno del tema (modalità scura, cambio lingua) dipendono da Alpine, quindi non può essere disattivato in bxsites.json come invece si può fare per mermaid/math.
• Versione. Attualmente alpinejs@3.14.1, incluso con questo modulo e servito da site/assets/vendor/alpine/ - nessuna CDN coinvolta. Controlla il layout.bxm proprio di un tema per il tag <script> esatto se ti serve sapere con precisione cosa viene caricato.
• CSP rigida. La build predefinita di Alpine valuta le espressioni JS dentro x-data/@click ecc. direttamente, il che richiede unsafe-eval sotto una Content-Security-Policy rigida. Se la tua distribuzione non può permetterlo, non affidarti ad Alpine nel contenuto delle tue pagine.
• Tienilo leggero. Una pagina di documentazione dovrebbe restare veloce e semplice - piccoli widget autonomi (un pulsante di copia, un filtro, un interruttore) sono adatti; una vera applicazione lato client non è ciò per cui questo esiste.