Tutorial de Alpine.js
O Lily para Alpine são fragmentos HTML que você cola na página, mais um plugin que dá aos interativos o seu teclado e o seu estado.
O que você vai construir
Um pequeno formulário de definições: dois campos rotulados, um interruptor e um botão de guardar, com comportamento real de teclado e leitor de tela, primeiro simples e depois estilizado, em cerca de 10 minutos.
Antes de começar
Precisa de Node.js e de uma página que já carregue o Alpine.js 3. O Alpine não tem modelo de componentes, por isso aqui um componente Lily é marcação que se copia, não um import.
Passo 1 — Instalar e registar o plugin
npm install alpinejs @lilydesignsystem/alpine-headless
<script type="module">
import Alpine from "alpinejs";
import lily from "@lilydesignsystem/alpine-headless/plugin";
Alpine.plugin(lily);
Alpine.start();
</script>
O plugin regista um comportamento Alpine.data() por componente interativo, com o nome lily mais o nome do componente:
lilySwitchButton, lilyTabs,
lilyCombobox. Os fragmentos de todos os componentes estão na pasta components/ do pacote, cada um com um comentário inicial que indica o elemento, a classe, as teclas e o ARIA.
Passo 2 — O seu primeiro componente
A maioria dos componentes é marcação simples e não precisa de nada do plugin:
<button class="button" type="submit">Save</button>
Um interativo acrescenta o seu comportamento com x-data e liga-o com x-bind:
<button
class="switch-button"
x-data="lilySwitchButton(false)"
x-bind="button"
aria-label="Email me about appointments"
>
Email me about appointments
</button>
O comportamento dá-lhe role="switch" e mantém
aria-checked atualizado quando Enter, Espaço ou um clique o alternam. As palavras são suas: o Lily nunca fornece um rótulo.
Passo 3 — Compor um pequeno formulário
<form class="form" aria-label="Settings">
<div class="field">
<label class="label" for="name">Full name</label>
<input class="text-input" type="text" id="name" name="name" autocomplete="name" required />
</div>
<div class="field">
<label class="label" for="email">Email</label>
<input class="email-input" type="email" id="email" name="email" autocomplete="email" required />
</div>
<button
class="switch-button"
type="button"
x-data="lilySwitchButton(true)"
x-bind="button"
aria-label="Email me about appointments"
>
Email me about appointments
</button>
<button class="button" type="submit">Save</button>
</form>
Verifique o seu trabalho: abra a página e prima Tab. O foco percorre os dois campos, o interruptor e o botão. No interruptor, Space alterna-o e um leitor de tela diz «interruptor, ligado» ou «desligado». Parece simples, e está certo: o aspeto vem a seguir.
Passo 4 — Estilizar
Ligue um dos 63 temas prontos, que visam as mesmas classes:
<link rel="stylesheet" href="/themes/light.css" />
Ou escreva o seu próprio CSS sobre as classes e o estado que o comportamento define:
.switch-button[aria-checked="true"] { background: var(--color-primary); }
.switch-button:focus-visible { outline: 2px solid var(--lily-focus-ring); outline-offset: 2px; }
Estilize o estado ARIA, não uma classe sua: assim o aspeto nunca contradiz o que um leitor de tela ouve.
Passo 5 — Ver tudo a funcionar
-
A aplicação de exemplo de Alpine.js,
lily-design-system-alpine-examples, mostra todos os componentes estilizados:pnpm install && pnpm run build. -
Há seis ajudantes para Alpine: a grelha de dados, o quadro kanban, o calendário, o gráfico de Gantt e os editores de Markdown e Org (
@lilydesignsystem/alpine-*).
Próximos passos
- Formação — oito módulos, cada um com um exercício e uma autoavaliação.
- Formulários acessíveis — erros, um resumo de erros e o foco.
- Temas — mudar de tema em tempo de execução.
- Catálogo de componentes — a referência completa.