Web Components 教程

原生自定义元素,无需框架运行时。每个元素都在轻量 DOM 中渲染真实的 <button> 或 <input> ,因此表单、CSS 和 querySelector 都像在手写 HTML 中一样工作。

你将构建什么

一个带标签字段和提交按钮的小型联系表单,用几行脚本连接,先是无样式,再加样式,大约 10 分钟。

开始之前

你需要 Node.js,以及打包工具或任何能解析裸模块导入的环境。该组件库覆盖 661 个组件中的 626 个;表格子元素和少数列表项系列未包含,因为自主自定义元素无法替代 <tr> 或 <li>。

第 1 步 — 安装并注册

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

导入包即定义所有元素,名称为 lily- 加组件标识: <lily-button>、 <lily-text-input>、 <lily-range-fieldset>。

第 2 步 — 你的第一个组件

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

该元素在内部渲染一个真实的 <button class="button"> ,因此 Enter、空格和按钮角色都是原生的。你添加的属性会传给这个内部元素。

第 3 步 — 组合一个小表单

<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> 阻止页面跳转,并让 submit 事件冒泡,由你的脚本决定后续。输入框是真正的表单控件,因此 FormData 可以读取它们。

检查成果: 按 Tab 遍历表单,然后提交:控制台显示 name 和 email。留空一个字段,浏览器自带的 required 检查会阻止提交。

第 4 步 — 添加样式

类名位于内部元素上,所以 63 个主题和你自己的 CSS 像对待普通 HTML 一样选中它们:

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

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

没有需要穿透的 Shadow DOM:样式表和辅助技术都能看到一切。

第 5 步 — 查看完整效果

  • 每个元素都有 story: pnpm run storybook 位于 lily-design-system-web-components-headless。
  • 辅助组件也以自定义元素形式提供: <lily-theme-picker>、数据网格、日历及其他(@lilydesignsystem/web-components-*)。

下一步