Tutorial de Web Components

Elementos personalizados nativos, sem runtime de framework. Cada um gera um <button> ou um <input> real no DOM leve, por isso formulários, CSS e querySelector funcionam como em HTML escrito à mão.

O que você vai construir

Um pequeno formulário de contacto com campos rotulados e um botão de envio, ligado com algumas linhas de script, primeiro simples e depois estilizado, em cerca de 10 minutos.

Antes de começar

Precisa de Node.js e de um bundler ou de qualquer configuração que resolva importações de módulos sem caminho. O catálogo cobre 626 dos 661 componentes; os subelementos de tabela e algumas famílias de itens de lista ficam de fora, porque um elemento personalizado autónomo não pode substituir um <tr> ou um <li>.

Passo 1 — Instalar e registar

npm install @lilydesignsystem/web-components-headless
<script type="module">
  import "@lilydesignsystem/web-components-headless";
</script>

Importar o pacote define cada elemento, com o nome lily- mais o identificador do componente: <lily-button>, <lily-text-input>, <lily-range-fieldset>.

Passo 2 — O seu primeiro componente

<lily-button type="submit">Send</lily-button>

O elemento gera um <button class="button"> real dentro de si, por isso Enter, Espaço e o papel de botão são nativos. Os atributos que acrescentar passam para esse elemento interno.

Passo 3 — Compor um pequeno formulário

<lily-form label="Contact us">
  <lily-field label="Full name" required>
    <lily-text-input label="Full name" name="name" autocomplete="name" required></lily-text-input>
  </lily-field>
  <lily-field label="Email" required>
    <lily-email-input label="Email" name="email" required></lily-email-input>
  </lily-field>
  <lily-button type="submit">Send</lily-button>
</lily-form>

<script type="module">
  const form = document.querySelector("lily-form form");
  form.addEventListener("submit", () => {
    const data = new FormData(form);
    console.log(Object.fromEntries(data));
  });
</script>

<lily-form> impede a navegação da página e deixa o evento submit propagar-se, por isso o seu script decide o que acontece. Os campos são controlos de formulário genuínos, por isso FormData lê-os.

Verifique o seu trabalho: prima Tab para percorrer o formulário e depois envie-o: a consola mostra name e email. Deixe um campo vazio e a verificação required do próprio navegador impede o envio.

Passo 4 — Estilizar

As classes estão nos elementos internos, por isso os 63 temas e o seu próprio CSS visam-nos como em HTML simples:

<link rel="stylesheet" href="/themes/light.css" />

<style>
  .button { padding: 0.75rem 1.5rem; }
  lily-field { display: block; margin-block-end: 1rem; }
</style>

Não há shadow DOM a atravessar: nada fica escondido da sua folha de estilos nem das tecnologias de apoio.

Passo 5 — Ver tudo a funcionar

  • Cada elemento tem uma story: pnpm run storybook em lily-design-system-web-components-headless.
  • Os ajudantes também existem como elementos personalizados: <lily-theme-picker>, a grelha de dados, o calendário e os restantes (@lilydesignsystem/web-components-*).

Próximos passos