无需登录 数据私有 本地保存

内置Web组件演示 - 原生自定义元素

13
0
0
0
Web ComponentsShadow DOMCustom Elements

原生自定义元素演示

基于 Web Components 标准构建的原生自定义元素（Custom Elements）交互演示。所有组件均使用 Shadow DOM 封装，开箱即用，无需任何框架依赖。

开关切换<wc-toggle>
HTML
<wc-toggle checked label="启用通知"></wc-toggle>
<wc-toggle label="暗色模式" disabled></wc-toggle>
星级评分<wc-rating>
评分: 4 / 5
HTML
<wc-rating value="4" max="5"></wc-rating>
环形进度<wc-progress-ring>
72%
HTML
<wc-progress-ring percent="72" size="100" color="#4f46e5"></wc-progress-ring>
徽标计数<wc-badge>
HTML
<wc-badge count="8" max="99" variant="danger"></wc-badge>
复制按钮<wc-copy-btn>
点击按钮复制上方文本
HTML
<wc-copy-btn text="Hello Web Components!"></wc-copy-btn>
打字效果<wc-typing>
80
HTML
<wc-typing text="Web Components 让组件开发更优雅。" speed="80"></wc-typing>
Web Components 核心特性一览
特性说明支持度
Custom Elements定义新的 HTML 标签，扩展浏览器原生语义Chrome 54+
Shadow DOM样式与 DOM 完全隔离，避免 CSS 冲突Chrome 53+
HTML Templates使用 <template> 标签定义可复用的 DOM 结构Chrome 54+
observedAttributes监听属性变化并自动响应，实现声明式 API全支持
CSS 自定义属性通过 CSS 变量穿透 Shadow DOM 进行样式定制全支持
插槽 (Slots)支持内容投影，灵活组合子内容Chrome 53+

常见问题与知识点

Web Components 是一套 W3C 标准，用于创建可复用的自定义组件。它由三项核心技术组成：Custom Elements（自定义元素）允许开发者定义新的 HTML 标签；Shadow DOM 提供样式和 DOM 的封装隔离；HTML Templates（<template> 和 <slot>）用于定义可复用的结构模板。三者结合，使开发者无需任何框架即可构建封装良好的 UI 组件。

自定义元素名称必须包含连字符（-），例如 <my-element> 或 <wc-toggle>。这是规范强制要求的，目的是区分原生 HTML 元素和自定义元素，避免与未来新增的原生标签冲突。同时名称必须全部小写，不能使用驼峰命名。推荐使用有意义的短横线分隔命名，如 <user-avatar>、<data-table> 等。

Shadow DOM 创建了一个独立的 DOM 子树，其中的 CSS 样式完全不会影响外部页面，外部样式也不会渗透进来（除 CSS 自定义属性外）。这意味着组件内部的 class 名称不会与页面其他部分冲突，开发者可以自由使用简洁的类名而无需担心全局污染。同时，这也保护了组件内部结构不被外部脚本意外修改，提高了组件的健壮性和可维护性。

Attribute 是HTML 标签上的字符串值，通过 getAttribute()/setAttribute() 操作；Property 是DOM 对象的 JavaScript 属性，可以是任意类型。在自定义元素中，通常需要将两者同步（属性反射），通过 observedAttributes 和 attributeChangedCallback 实现。例如，<wc-rating value="4"> 中 "4" 是字符串 attribute，而组件内部可以通过 getter/setter 将其映射为数字类型的 property。

Web Components 是浏览器原生标准，不依赖任何框架，可以在任何 HTML 页面中直接使用，甚至可以跨框架复用。React/Vue 组件依赖各自的运行时和虚拟 DOM。Web Components 的优势在于互操作性强——同一个组件可以用在 React、Vue、Angular 或纯 HTML 项目中。但框架组件在开发体验、状态管理、响应式数据绑定等方面更加成熟。两者可以互补使用，许多项目将 Web Components 作为跨团队的 UI 标准基座。

自定义元素提供四个生命周期回调：
connectedCallback() — 元素被插入 DOM 时调用；
disconnectedCallback() — 元素从 DOM 移除时调用（适合清理定时器、事件监听等）；
adoptedCallback() — 元素被移动到新文档时调用（如 iframe 间移动）；
attributeChangedCallback(name, oldVal, newVal) — 监听的属性发生变化时调用。合理利用这些回调可以创建健壮、无内存泄漏的组件。

Web Components 在所有现代浏览器中均获得完整支持：Chrome 67+、Firefox 63+、Safari 10.1+、Edge 79+。全球覆盖率达 97% 以上。对于需要支持 IE11 的遗留项目，可以使用 webcomponents.js polyfill。目前许多大型企业（如 GitHub、YouTube、Salesforce）已在生产环境中广泛使用 Web Components。对于新项目，完全可以放心采用。

CSS 自定义属性（CSS Variables）可以穿透 Shadow DOM 边界，这是官方设计的样式定制通道。在组件内部使用 var(--my-var, fallback) 引用变量，外部用户可以通过 wc-toggle { --toggle-color: red; } 来覆盖样式。此外，::part() 伪元素选择器允许外部样式化组件中标记了 part 属性的内部元素，提供了更精细的样式控制能力。

插槽（<slot>）是 Shadow DOM 中的内容投影机制，允许外部内容渲染到组件内部的指定位置。命名插槽 <slot name="header"> 匹配外部 <span slot="header">，默认插槽捕获所有未指定 slot 属性的内容。这使得自定义元素可以像原生元素一样包裹任意子内容，实现灵活的布局组合，例如创建一个 <custom-card> 组件，其标题、正文、底部操作区都可以通过插槽灵活填充。

① 使用 CSS 自定义属性作为样式 API，而非暴露内部 class；② 合理使用 Shadow DOM——不需要样式隔离时可以用轻量级自定义元素（不附加 shadow root）；③ 属性反射确保 attribute 和 property 保持同步；④ 在 disconnectedCallback 中清理资源（定时器、事件监听）；⑤ 使用 ARIA 属性确保无障碍访问；⑥ 提供合理的默认值和降级方案；⑦ 组件命名遵循语义化原则，如 <data-chart>、<user-profile>。
🔧 相关工具