Alpine e gestione degli eventi: la direttiva x-on

Alpine dispone di direttive e proprietà per la manipolazione interattiva del DOM.

La direttiva x-on

La direttiva x-on (@ nella forma abbreviata) ascolta gli eventi che si propagano nel DOM e, al verificarsi dell'evento assegnato, esegue un'espressione JavaScript. Ecco un esempio:

<div x-data="{ open: false }">
	<button x-on:click="open = ! open">Fai clic</button>
</div>

In questo esempio, x-on:click esegue l'espressione open = ! open ogni volta che l'utente fa clic sul pulsante. Con la forma abbreviata, il codice diventa:

<div x-data="{ open: false }">
	<button @click="open = ! open">Fai clic</button>
</div>

La proprietà $event di Alpine

La proprietà $event di Alpine permette di accedere all'oggetto event nativo del browser dall'interno di un'espressione. Ecco un semplice esempio:

<div x-data>
	<button @click="alert($event.target.dataset.message)" data-message="Ciao mondo!">Fai clic</button>
</div>

In esso abbiamo passato al gestore di eventi @click un'espressione che apre un alert. Vediamo nel dettaglio cosa succede:

• $event rappresenta l'oggetto event. Questo contiene informazioni sull'evento (in questo caso, un clic).
• La proprietà .target di $event restituisce l'elemento HTML che ha originato l'evento, cioè il pulsante cliccato.
• La proprietà dataset è un oggetto che contiene tutti gli attributi data-* di un elemento HTML. Con dataset.message, si accede all'attributo data-message dell'elemento su cui si è verificato l'evento.

Il gestore di eventi può anche far riferimento ad un metodo invece che a un'espressione. Alpine passa automaticamente l'oggetto event a tutti i metodi invocati senza parentesi. L'esempio qui sopra potrebbe essere scritto anche in questo modo:

<div x-data>
	<button @click="showMessage" data-message="Ciao mondo!">Fai clic</button>
	<script>
		function showMessage(e) {
			alert(e.target.dataset.message);
		}
	</script>
</div>

È anche possibile spostare la funzione all'interno della direttiva x-data:

<div x-data="{ showMessage(e) { alert(e.target.dataset.message); } }">
	<button @click="showMessage" data-message="Ciao mondo!">Fai clic</button>
</div>

Si è detto che, invocando il metodo senza parentesi, la proprietà $event viene trasmessa automaticamente. È anche possibile passare esplicitamente alla funzione uno o più parametri:

<div x-data="{ showMessage(t) { alert(t.dataset.message); } }">
	<button @click="showMessage($event.target)" data-message="Ciao mondo!">Fai clic</button>
</div>

Eventi da tastiera

Con la direttiva x-on di Alpine è possibile intercettare gli eventi keyup e keydown sulle chiavi specificate. Vediamo un esempio con keyup:

<div x-data="{ nome: '', messaggio: '' }">
	<input type="text" x-model="nome" @keyup.enter="messaggio = 'Ciao, ' + nome + '!'; nome = ''" placeholder="Inserisci il tuo nome">
	<p x-text="messaggio"></p>
</div>

In questo esempio,

• x-model="nome" lega (binding bidirezionale) il valore del campo di testo alla variabile nome, il cui valore viene aggiornato automaticamente ogni volta che l'utente digita qualcosa sulla tastiera;
• @keyup.enter è un event listener di Alpine che ascolta l'evento sul campo di testo. In questo caso si tratta del rilascio del tasto Invio. Al verificarsi dell'evento, viene aggiornato il valore delle due variabili messaggio e nome.
• La direttiva x-text aggiorna dinamicamente il contenuto dell'elemento p.

È anche possibile combinare più modificatori. Ad esempio, si possono ascoltare combinazioni di tasti come Invio e Maiuscolo con @keyup.shift.enter.

Alpine supporta tutti i valori della proprietà KeyboardEvent.key convertiti in Kebab case. Nel seguente esempio utilizziamo i modificatori arrow-up e arrow-down:

<div x-data="{ contatore: 1 }">
	<input type="text" @keyup.arrow-up="contatore++" @keyup.arrow-down="contatore--">
	<p>Pagina: <span x-text="contatore"></span></p>
</div>

In questo esempio, il valore del contatore aumenta o diminuisce di 1 a seconda che l'utente rilasci il tasto Freccia Su o Freccia Giù.

Per l'elenco completo dei modificatori, si legga il Mozilla Developer Network.

Alpine ed eventi del mouse

Alpine dispone di numerosi eventi del mouse, come click, dblclick, mouseover, ecc. Questi possono essere combinati con un modificatore che ne altera il comportamento, tra cui:

• .shift
• .ctrl
• .cmd
• .meta
• .alt

Ecco un esempio in cui si fa uso di diversi eventi con e senza modificatori:

<div x-data="{ count: 0, message: '' }">
	<button
		@click="count++"
		@contextmenu.prevent="alert('Operazione non consentita!')"
		@click.shift="count = 0"
		@mouseover="message = 'Mouse sopra'"
		@mouseout="message = ''"
	>
		Cliccami
	</button>
		<p>Conta: <span x-text="count"></span></p>
		<p>Evento:<span x-text="message"></span></p>
</div>

• Con l'oggetto passato a x-data, vengono dichiarate due variabili, count e message.
• Al clic del mouse, la variabile count viene incrementata di 1.
• Al click con il pulsante destro (evento contextmenu), non appare il menu contestuale (.prevent) ma viene inviato un alert con un messaggio. Il modificatore prevent, infatti, impedisce il comportamento predefinito dell'evento contextmenu e permette di eseguire il codice che genera l'alert.
• @click.shift si verifica quando l'evento click è associato alla pressione del tasto maiuscolo. Con questa combinazione viene eseguito il codice che azzera il contatore.
• @mouseover si verifica quando il cursore del mouse è sopra il pulsante; @mouseout quando il cursore lascia il pulsante. Al verificarsi di uno di questi due eventi, viene aggiornata la variabile message.