JavaScript Web Components 实战:使用 Custom Elements 与 Shadow DOM 开发可复用组件
现代前端开发中,组件化已经成为构建复杂界面的常见方式。
React、Vue 和其他框架都提供了组件抽象,但浏览器本身也具备一套原生组件标准,即 Web Components。
通过 Custom Elements、Shadow DOM 和 HTML Template,可以创建不依赖特定前端框架的自定义组件,并在不同页面中复用。
本文以一个可折叠信息面板为例,介绍如何使用浏览器原生 API 实现组件封装、属性同步、事件通信、插槽和样式隔离。
一、Web Components 包含哪些核心技术?
Web Components 并不是单独的 JavaScript 框架,而是多项浏览器标准的组合。
其中最常用的三个部分是:
- Custom Elements:允许开发者注册自定义 HTML 元素,并定义生命周期行为。
- Shadow DOM:允许组件拥有独立的 DOM 子树,并提供一定程度的样式隔离。
- HTML Template:使用模板保存尚未渲染的 HTML 结构,在需要时进行实例化。
这些技术可以配合使用,也可以根据需要独立采用其中某一部分。
例如,一个简单的自定义元素可以只使用 Custom Elements,而复杂的 UI 组件通常还需要 Shadow DOM。
二、定义自定义元素
首先,在页面中准备组件使用位置。
这里使用 info-panel 作为自定义元素名称。
<section class="demo-layout">
<h1>原生组件演示</h1>
<info-panel heading="系统通知">
<p>当前系统运行正常。</p>
</info-panel>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
自定义元素名称必须包含连字符,这是 Custom Elements 的命名要求之一。
在 JavaScript 中,可以通过继承 HTMLElement 定义元素行为。
class InfoPanel extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: "open" });
}
connectedCallback() {
this.render();
}
render() {
const heading = this.getAttribute("heading") ?? "";
const container = document.createElement("section");
const title = document.createElement("h2");
title.textContent = heading;
container.appendChild(title);
this.shadowRoot.replaceChildren(container);
}
}
customElements.define("info-panel", InfoPanel);
注册完成后,浏览器就会识别页面中的 <info-panel> 元素。
connectedCallback() 会在元素被连接到文档时执行。
需要注意,如果元素被反复移除并重新插入,connectedCallback() 可能执行多次,因此初始化逻辑应该具有幂等性。
三、使用 Template 管理复杂组件结构
当组件包含多个按钮、文本区域和状态提示时,直接在 JavaScript 中创建所有 DOM 节点会使代码变得冗长。
HTML Template 可以将组件结构集中管理。
<template id="info-panel-template">
<style>
.panel {
border: 1px solid #d0d7de;
border-radius: 8px;
padding: 16px;
}
.panel-header {
display: flex;
justify-content: space-between;
}
</style>
<section class="panel">
<header class="panel-header">
<h2 data-heading></h2>
<button
type="button"
data-toggle
aria-expanded="true"
>
收起
</button>
</header>
<div data-content>
<slot></slot>
</div>
</section>
</template>
<a href="https://www.yxtiktok.com/blog/guides/">
模板内部定义了组件结构和局部样式。
<slot> 用于显示组件使用者提供的内容。
与直接生成整段字符串不同,使用模板可以减少重复的 HTML 创建逻辑。
在生产环境中,通常会在组件模块中统一声明模板,再由各个组件实例克隆使用。
四、实现展开和收起功能
接下来完善组件类,为模板绑定交互逻辑。
class InfoPanel extends HTMLElement {
constructor() {
super();
const template = document.querySelector(
"#info-panel-template"
);
const shadow = this.attachShadow({
mode: "open"
});
shadow.appendChild(
template.content.cloneNode(true)
);
this.button = shadow.querySelector(
"[data-toggle]"
);
this.content = shadow.querySelector(
"[data-content]"
);
this.headingElement = shadow.querySelector(
"[data-heading]"
);
this.handleToggle = () => {
this.expanded = !this.expanded;
};
}
connectedCallback() {
this.button.addEventListener(
"click",
this.handleToggle
);
this.syncHeading();
this.syncExpanded();
}
disconnectedCallback() {
this.button.removeEventListener(
"click",
this.handleToggle
);
}
get expanded() {
return !this.hasAttribute("collapsed");
}
set expanded(value) {
this.toggleAttribute("collapsed", !value);
}
syncExpanded() {
const expanded = this.expanded;
this.content.hidden = !expanded;
this.button.setAttribute(
"aria-expanded",
String(expanded)
);
this.button.textContent = expanded
? "收起"
: "展开";
}
syncHeading() {
this.headingElement.textContent =
this.getAttribute("heading") ?? "";
}
}
这里将展开状态映射到 collapsed 属性。
这种设计的优点是,组件状态不仅可以通过 JavaScript 属性控制,也能通过 HTML 属性进行声明。
组件断开连接时移除事件监听器,避免反复挂载过程中重复绑定事件。
完整注册时,应确保同一个元素名称只注册一次。
五、响应外部属性变化
Web Components 可以通过 observedAttributes 监听属性变化。
例如,父页面更新组件标题时,组件内部的标题也应同步更新。
先准备一个支持动态标题的使用示例:
<section class="panel-controls">
<button
type="button"
data-change-heading
>
更新面板标题
</button>
<info-panel
id="dynamic-panel"
heading="初始标题"
>
<p>这里展示动态面板内容。</p>
</info-panel>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
在组件类中补充属性观察逻辑:
static get observedAttributes() {
return ["heading", "collapsed"];
}
attributeChangedCallback(name, oldValue, newValue) {
if (oldValue === newValue) {
return;
}
if (name === "heading") {
this.syncHeading();
}
if (name === "collapsed") {
this.syncExpanded();
}
}
当外部调用 setAttribute() 修改标题时,组件可以立即同步显示内容。
例如:
const panel = document.querySelector(
"#dynamic-panel"
);
panel.setAttribute(
"heading",
"最新系统通知"
);
与框架中的 Props 类似,属性可以承担组件对外暴露的配置接口。
不过,HTML 属性本质上是字符串,因此复杂对象、数组或函数通常更适合通过 JavaScript 属性传递。
六、通过 CustomEvent 与外部页面通信
组件内部的操作有时需要通知外部页面。
例如,信息面板展开或收起后,父页面需要更新统计数据。
使用 CustomEvent 可以定义组件自己的事件。
先创建一个状态展示区域:
<section class="panel-event-demo">
<h2>组件交互状态</h2>
<info-panel heading="事件通知测试">
<p>点击组件按钮可以改变展开状态。</p>
</info-panel>
<output data-panel-state>
等待操作
</output>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
在组件的状态更新逻辑中,可以派发事件:
this.dispatchEvent(
new CustomEvent("panel-toggle", {
detail: {
expanded: this.expanded
},
bubbles: true,
composed: true
})
);
外部页面监听:
document.addEventListener(
"panel-toggle",
event => {
const output = document.querySelector(
"[data-panel-state]"
);
output.textContent = event.detail.expanded
? "面板已展开"
: "面板已收起";
}
);
bubbles: true 允许事件沿 DOM 向上冒泡。
composed: true 允许事件跨越 Shadow DOM 边界传播。
对于组件库来说,定义稳定的自定义事件接口,比让外部代码直接操作组件内部 DOM 更容易维护。
七、使用 CSS 自定义属性实现主题配置
Shadow DOM 提供样式隔离,但组件仍然需要支持外部主题配置。
CSS 自定义属性是一种常见方式。
例如,在组件内部使用:
.panel {
color: var(--panel-text-color, #1f2937);
background: var(--panel-background, #ffffff);
border-color: var(--panel-border-color, #d0d7de);
}
在页面外部定义:
info-panel {
--panel-text-color: #e5e7eb;
--panel-background: #111827;
--panel-border-color: #374151;
}
这种方式允许外部页面控制组件主题,同时不需要直接访问 Shadow DOM 内部节点。
需要注意,CSS 自定义属性具有继承行为,因此它们可以成为组件公开的样式配置接口。
八、插槽与动态内容
slot 允许自定义元素接收来自外部页面的内容。
例如,可以给组件增加命名插槽,用于展示操作按钮或辅助说明。
<info-panel heading="用户资料">
<p>用户基础信息</p>
<button
slot="actions"
type="button"
>
编辑资料
</button>
</info-panel>
<a href="https://www.yxtiktok.com/blog/guides/">
相应地,组件模板中需要提供:
<slot name="actions"></slot>
使用命名插槽后,组件结构更加灵活,不需要将所有可变内容都定义为 HTML 属性。
不过,插槽内容仍然属于组件使用者提供的 DOM,不能简单地将 Shadow DOM 样式隔离理解为完全的安全隔离。
九、Web Components 的适用场景
Web Components 特别适合以下需求:
1. 多框架复用
同一个组件需要在原生 JavaScript、Vue、React 或其他项目中使用。
2. 独立业务控件
例如日期选择器、状态标签、数据卡片和轻量级弹窗。
3. 长期维护的组件库
当产品跨多个系统运行时,使用浏览器原生标准有利于降低对单一框架版本的依赖。
4. 微前端集成
不同业务模块可以使用不同技术栈,而公共 UI 控件通过标准自定义元素进行集成。
但是,Web Components 也有需要注意的地方。
Shadow DOM 会影响选择器作用范围;表单关联、服务端渲染、无障碍支持和组件间数据传递都需要按实际业务需求设计。
不能因为采用原生组件标准,就认为这些问题会自动得到解决。
十、总结
Web Components 提供了浏览器原生的组件化能力。
通过 Custom Elements 定义生命周期、Shadow DOM 管理内部结构、Template 复用组件布局,以及 CustomEvent 实现事件通信,可以构建具有较好独立性和可复用性的前端组件。
对于希望降低框架耦合、维护统一 UI 组件库或者构建跨项目业务控件的团队,Web Components 是一种值得考虑的技术方案。
实际开发时,应重点关注属性与状态同步、组件生命周期、样式配置以及无障碍交互,而不是仅仅把普通 HTML 包装成自定义标签。
浙公网安备 33010602011771号