Alpine.js 教程

Alpine 版 Lily 是你粘贴进页面的 HTML 代码片段,再加一个插件,为交互组件提供键盘操作和状态。

你将构建什么

一个小型设置表单:两个带标签的字段、一个开关和一个保存按钮,具备真实的键盘和读屏行为,先是无样式,再加样式,大约 10 分钟。

开始之前

你需要 Node.js,以及一个已加载 Alpine.js 3 的页面。Alpine 没有组件模型,所以这里的 Lily 组件是你复制的标记,而不是导入。

第 1 步 — 安装并注册插件

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>

插件为每个交互组件注册一个 Alpine.data() 行为,名称为 lily 加组件名: lilySwitchButton、 lilyTabs、 lilyCombobox。每个组件的代码片段都在包的 components/ 文件夹中,每个都有一段头部注释,说明其元素、类名、按键和 ARIA。

第 2 步 — 你的第一个组件

大多数组件只是普通标记,不需要插件:

<button class="button" type="submit">Save</button>

交互组件用 x-data 添加行为,并用 x-bind绑定:

<button
  class="switch-button"
  x-data="lilySwitchButton(false)"
  x-bind="button"
  aria-label="Email me about appointments"
>
  Email me about appointments
</button>

行为为它加上 role="switch" ,并在 Enter、空格或点击切换时保持 aria-checked 同步。文字由你提供:Lily 从不提供标签。

第 3 步 — 组合一个小表单

<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>

检查成果: 打开页面并按 Tab。焦点依次经过两个字段、开关和按钮。在开关上按 Space 可切换它,读屏软件会说“开关,开”或“关”。看起来很朴素,这是对的:样式在下一步。

第 4 步 — 添加样式

链接 63 个现成主题之一,它们针对同样的类名:

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

或者针对类名和行为设置的状态编写你自己的 CSS:

.switch-button[aria-checked="true"] { background: var(--color-primary); }
.switch-button:focus-visible { outline: 2px solid var(--lily-focus-ring); outline-offset: 2px; }

为 ARIA 状态设置样式,而不是自定义类:这样外观永远不会与读屏软件听到的内容不一致。

第 5 步 — 查看完整效果

  • Alpine.js 示例应用 lily-design-system-alpine-examples展示了所有带样式的组件: pnpm install && pnpm run build。
  • Alpine 有六个辅助组件:数据网格、看板、日历、甘特图,以及 Markdown 和 Org 编辑器(@lilydesignsystem/alpine-*)。

下一步