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-*)。